ILI Nearby Nowcast

Attribute Details
Source Name nowcast
Data Source Delphi’s ILI Nearby system
Dataset Type Predictive (Leading Indicator)
Geographic Levels National, Department of Health & Human Services (HHS) Regions, Census Divisions, State (see Geographic Codes)
Temporal Granularity Weekly (Epiweek)
Reporting Cadence Inactive - No longer updated since 2022w36
Temporal Scope Start 2010w45
License CC BY

Overview

This endpoint provides Delphi’s nowcast estimates of the percentage of outpatient visits due to Influenza-Like Illness (ILI).

This system uses a sensor-fusion approach to estimate the current level of flu activity before the official CDC reports are finalized. It is available for:

  • National/Regional: 7 days before the first official CDC ILINet report for a given date.
  • State-level: 5 days before the first official CDC ILINet report for a given date. State values report weighted percent ILI.

General topics not specific to any particular endpoint are discussed in the API overview. Such topics include: contributing, citing, and data licensing.

Table of contents

  1. Estimation
  2. Lag and Backfill
  3. Limitations
  4. The API
    1. Parameters
      1. Required
    2. Response
  5. Example URLs
    1. ILI Nearby on 2020w01 (national)
  6. Code Samples
    1. Legacy Clients

Estimation

This system uses a sensor-fusion approach to estimate the current level of flu activity (ILI%). It combines data sources to produce a single estimate, aiming to provide an early indicator before the official CDC FluView report is finalized.

The endpoint exposes the following signals:

  • value: The nowcast estimate of the percentage of outpatient visits due to Influenza-Like Illness (ILI).
  • std: The standard deviation of the nowcast estimate, providing a measure of uncertainty.

The model combines multiple digital surveillance signals, including Wikipedia access logs (see Wikipedia Access) and CDC webpage visits (see CDC Webpage Visits), to create a predictive model for the current week’s ILI%.

Lag and Backfill

Nowcast estimates were subject to revision as input data was updated or backfilled.

Limitations

  • These values are estimates (nowcasts), not ground-truth surveillance data. They are subject to modeling errors.
  • The accuracy of the nowcast depends on the availability and stability of the input (Wikipedia, CDC page hits, etc.). Changes in user behaviour or platform algorithms can affect these inputs.

The API

The base URL is: https://api.delphi.cmu.edu/epidata/nowcast/

Parameters

Required

Parameter Description Type
epiweeks epiweeks (see Date Formats) list of epiweeks
locations locations list of location codes: nat, HHS regions, Census divisions, or state codes (see Geographic Codes)

Response

Field Description Type
result result code: 1 = success, 2 = too many results, -2 = no results integer
epidata list of results array of objects
epidata[].location location identifier (e.g., ‘nat’, state code, HHS region, census division) string
epidata[].epiweek epiweek for the nowcast estimate integer
epidata[].value nowcast estimate of %ILI (percentage of outpatient visits due to ILI) float
epidata[].std standard deviation of the nowcast estimate float
message success or error message string

Example URLs

ILI Nearby on 2020w01 (national)

https://api.delphi.cmu.edu/epidata/nowcast/?locations=nat&epiweeks=202001

{
  "result": 1,
  "epidata": [
    {
      "location": "nat",
      "epiweek": 202001,
      "value": 6.08239,
      "std": 0.12595
    }
  ],
  "message": "success"
}

Code Samples

Libraries are available for R and Python. The following samples show how to import the library and fetch national ILI Nearby data for epiweeks 202001-202010 (10 weeks total).

Install the package using pip:

pip install -e "git+https://github.com/cmu-delphi/epidatpy.git#egg=epidatpy"

# Import
from epidatpy import CovidcastEpidata, EpiDataContext, EpiRange
# Fetch data
epidata = EpiDataContext()
res = epidata.pub_nowcast(locations=['nat'], epiweeks=EpiRange(202001, 202010))
print(res)

library(epidatr)
# Fetch data
res <- pub_nowcast(locations = 'nat', epiweeks = epirange(202001, 202010))
print(res)

Legacy Clients

We recommend using the modern client libraries mentioned above. Legacy clients are also available for Python, R, and JavaScript.

Optionally install the package using pip(env):

pip install delphi-epidata

Otherwise, place delphi_epidata.py from this repo next to your python script.

# Import
from delphi_epidata import Epidata
# Fetch data
res = Epidata.nowcast(['nat'], Epidata.range(202001, 202010))
print(res['result'], res['message'], len(res['epidata']))

Place delphi_epidata.R from this repo next to your R script.

source("delphi_epidata.R")
# Fetch data
res <- Epidata$nowcast(locations = list("nat"), epiweeks = Epidata$range(202001, 202010))
print(res$message)
print(length(res$epidata))

<!-- Imports -->
<script src="delphi_epidata.js"></script>
<!-- Fetch data -->
<script>
  EpidataAsync.nowcast('nat', [EpidataAsync.range(201501, 201510)]).then((res) => {
    console.log(res.result, res.message, res.epidata != null ? res.epidata.length : 0);
  });
</script>