Delphi Forecasts

Attribute	Details
Source Name	delphi
Data Source	Delphi
Temporal Granularity	Weekly (Epiweek)
Systems available	af, eb, ec, sp, st (see details below)
Reporting Cadence	Inactive - No longer updated since 2020w19
Temporal Scope Start	Varies by system (earliest 2014w41)
License	CC BY

Overview

This data source provides access to experimental and retrospective Delphi forecasting systems and nowcasting outputs.

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

Forecasting Systems

The following systems are available, representing different forecasting models for ILINet % weighted ILI:

Code	Name
af	Archefilter
eb	Empirical Bayes
ec	Epicast
sp	Pinned Spline
st	Delphi-Stat

Table of contents

1. Forecasting Systems
2. The API
   1. Parameters
      1. Required
   2. Response
3. Example URLs
   1. Delphi on 2015w01 (EC)
4. Code Samples
   1. Legacy Clients

The API

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

Parameters

Required

Parameter	Description	Type
system	system	system name (af, eb, ec, sp, st)
epiweek	epiweek (see Date Formats)	epiweek when forecast was made

Response

Field	Description	Type
result	result code: 1 = success, 2 = too many results, -2 = no results	integer
epidata	list of single result	array of object
epidata[].system	system	string
epidata[].epiweek	epiweek	integer
epidata[].forecast	forecast structure	object
epidata[].forecast._version	forecast version	integer
epidata[].forecast.baselines	baseline values for each region	object
epidata[].forecast.baselines.<region>	baseline value for <region>	float
epidata[].forecast.data	forecast data for each region	object
epidata[].forecast.data.<region>	forecast data for <region>	object
epidata[].forecast.data.<region>.<distrib>	distribution for <distrib> (peak, peakweek, onset, x1, x2, x3, x4)	object
epidata[].forecast.data.<region>.<distrib>.dist	probability distribution	array of float
epidata[].forecast.data.<region>.<distrib>.point	point estimate	float
epidata[].forecast.data.<region>.<distrib>.none	probability of “none” (if applicable)	float
epidata[].forecast.epiweek	forecast epiweek	integer
epidata[].forecast.ili_bin_size	size of ILI bins	float
epidata[].forecast.ili_bins	number of ILI bins	integer
epidata[].forecast.name	system name	string
epidata[].forecast.season	season year (yyyy)	integer
epidata[].forecast.season_weeks	number of weeks in season	integer
epidata[].forecast.year_weeks	number of weeks in year	integer
message	success or error message	string

Example URLs

Delphi on 2015w01 (EC)

https://api.delphi.cmu.edu/epidata/delphi/?system=ec&epiweek=201501

{
  "result": 1,
  "epidata": [
    {
      "system": "ec",
      "epiweek": 202001,
      "forecast": {
        "season": 2019,
        "ili_bins": 131,
        "data": {
          "hhs5": {
            "peakweek": {
              "point": 52,
              "dist": [
                0.00021925496021215,
                ...
              ]
            },
            "onset": {
              "point": 48,
              "none": 0.0002,
              "dist": [
                0.00020000000000012,
                ...
              ]
            },
            "x2": {
              "point": 3.07298,
              "dist": [
                0.0010569913847139,
                ...
              ]
            },
            "x4": {
              "point": 2.85944,
              "dist": [
                0.0014449186313411,
                ...
              ]
            },
            "x3": {
              "point": 2.94803,
              "dist": [
                0.0012245906869107,
                ...
              ]
            },
            "peak": {
              "point": 4.5724227117742,
              "dist": [
                0.0010000000000028,
                ...
              ]
            },
            "x1": {
              "point": 3.35905,
              "dist": [
                0.0010036642441866,
                ...
              ]
            }
          },
          ...
        },
        "name": "delphi-epicast",
        "year_weeks": 52,
        "ili_bin_size": 0.1,
        "season_weeks": 33,
        "_version": 3,
        "epiweek": 202001
      }
    }
  ],
  "message": "success"
}

Code Samples

Libraries are available for R and Python. The following samples show how to import the library and fetch Delphi Forecast data for system ec on epiweek 201501.

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.delphi('ec', 201501)
print(res['result'], res['message'], len(res['epidata']))

library(epidatr)
# Fetch data
res <- pub_delphi(system = 'ec', epiweek = 201501)
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

Place delphi_epidata.py from this repo next to your python script.

# Import
from delphi_epidata import Epidata
# Fetch data
res = Epidata.delphi('ec', 201501)
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$delphi(system = 'ec', epiweek = 201501)
print(res$message)
print(length(res$epidata))

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