zoltr: Interface to the 'Zoltar' Forecast Repository API

Description

'Zoltar' https://www.zoltardata.com/ is a website that provides a repository of model forecast results in a standardized format and a central location. It supports storing, retrieving, comparing, and analyzing time series forecasts for prediction challenges of interest to the modeling community. This package provides functions for working with the 'Zoltar' API, including connecting and authenticating, getting meta information (projects, models, and forecasts, and truth), and uploading, downloading, and deleting forecast and truth data.

Author(s)

Maintainer: Matthew Cornell cornell@umass.edu

Authors:

• Nicholas Reich nick@schoolph.umass.edu [copyright holder]

See Also

Useful links:

• https://github.com/reichlab/zoltr

• http://reichlab.io/zoltr/

• Report bugs at https://github.com/reichlab/zoltr/issues

Pipe operator

Description

See ⁠magrittr::[\%>\%][magrittr::\%>\%]⁠ for details.

Usage

lhs %>% rhs

Poll job's status

Description

A convenience function that polls the passed Job's status waiting for either FAILED, TIMEOUT, or SUCCESS.

Usage

busy_poll_job(zoltar_connection, job_url, verbose = TRUE)

Arguments

Examples

## Not run: 
  busy_poll_job(conn, "http://example.com/api/job/2/")

## End(Not run)

Create a model

Description

Creates the model in the passed project using the passed list. Fails if a model with the passed name already exists.

Usage

create_model(zoltar_connection, project_url, model_config)

Arguments

Value

model_url of the newly-created model

Examples

## Not run: 
  new_model_url <- create_model(conn, "https://www.zoltardata.com/api/project/9/",
                     jsonlite::read_json("example-model-config.json"))

## End(Not run)

Create a project

Description

Creates the project using the passed project configuration list. Fails if a project with the passed name already exists.

Usage

create_project(zoltar_connection, project_config)

Arguments

Value

project_url of the newly-created project

Examples

## Not run: 
  new_project_url <- create_project(conn, jsonlite::read_json("cdc-project.json"))

## End(Not run)

Create a timezero

Description

Creates the timezero in the passed project using the passed list. Fails if a timezero with the passed timezero_date already exists.

Usage

create_timezero(
  zoltar_connection,
  project_url,
  timezero_date,
  data_version_date = NULL,
  is_season_start = FALSE,
  season_name = ""
)

Arguments

Value

model_url of the newly-created timezero

Examples

## Not run: 
  new_timezero_url <- create_timezero(conn, "https://www.zoltardata.com/api/project/9/",
                     "2022-11-08", "2022-11-09", TRUE, "2010-2011")

## End(Not run)

Converts forecast data from Zoltar's native list format to a data.frame

Description

Converts forecast data from Zoltar's native list format to a data.frame

Usage

data_frame_from_forecast_data(forecast_data)

Arguments

Value

A data.frame from forecast_data in zoltar-specific format. The columns are: 'unit', 'target', 'class', 'value', 'cat', 'prob', 'sample', 'quantile', 'family', 'param1', 'param2', 'param3'. They are documented at https://docs.zoltardata.com/fileformats/#forecast-data-format-csv . NB: columns are all character (i.e., data type information from forecast_data is lost). Also note that a retracted prediction element is represented as a single row with NA values for all but the first four columns.

Examples

## Not run: 
  forecast_data <- jsonlite::read_json("docs-predictions.json")
  data_frame <- data_frame_from_forecast_data(forecast_data)

## End(Not run)

Delete a forecast

Description

Deletes the forecast with the passed URL. This is permanent and cannot be undone.

Usage

delete_forecast(zoltar_connection, forecast_url)

Arguments

Value

A Job URL for the deletion

Examples

## Not run: 
  delete_forecast(conn, "http://example.com/api/forecast/1/")

## End(Not run)

Delete a model

Description

Deletes the model with the passed ID. This is permanent and cannot be undone.

Usage

delete_model(zoltar_connection, model_url)

Arguments

Value

None

Examples

## Not run: 
  delete_model(conn, "http://www.zoltardata.com/api/model/1/")

## End(Not run)

Delete a project

Description

Deletes the project with the passed URL. This is permanent and cannot be undone.

Usage

delete_project(zoltar_connection, project_url)

Arguments

Value

None

Examples

## Not run: 
  delete_project(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

A convenience function to construct and execute a Zoltar query for either forecast or truth data.

Description

A convenience function to construct and execute a Zoltar query for either forecast or truth data.

Usage

do_zoltar_query(
  zoltar_connection,
  project_url,
  query_type,
  models = NULL,
  units = NULL,
  targets = NULL,
  timezeros = NULL,
  types = NULL,
  as_of = NULL,
  verbose = TRUE
)

Arguments

Value

A data.frame of Job's data. Full documentation at https://docs.zoltardata.com/.

Examples

## Not run: 
  forecast_data <- do_zoltar_query(
    conn, "https://www.zoltardata.com/api/project/44/", "forecasts",
    models=c("CMU-TimeSeries", "UMass-MechBayes"), units=c("01003", "US"),
    targets=c("1 wk ahead inc death"), targets=c("2020-07-19", "2020-07-20"),
    types=c("quantile"), as_of="2020-07-10")
  truth_data <- do_zoltar_query(
    conn, "https://www.zoltardata.com/api/project/44/", "truth", c("01003", "US"),
    c("1 wk ahead inc death"), c("2020-07-19", "2020-07-20"))

## End(Not run)

Gets a forecast's data

Description

Gets a forecast's data

Usage

download_forecast(zoltar_connection, forecast_url)

Arguments

Value

Forecast data as a list in the Zoltar standard format. meta information is ignored. Full documentation at https://docs.zoltardata.com/.

Examples

## Not run: 
  forecast_data <- download_forecast(conn, "http://example.com/api/forecast/1/")

## End(Not run)

Edit a model

Description

Edits the model in the passed project using the passed list. Fails if a model with the passed name already exists.

Usage

edit_model(zoltar_connection, model_url, model_config)

Arguments

Examples

## Not run: 
  edit_model(conn, "https://www.zoltardata.com/api/model/2/",
    jsonlite::read_json("example-model-config.json"))

## End(Not run)

Loads and converts a CDC CSV file to Zoltar's native list format

Description

Loads and converts a CDC CSV file to Zoltar's native list format

Usage

forecast_data_from_cdc_csv_file(season_start_year, cdc_csv_file)

Arguments

Value

cdc_csv_file's data as Zoltar's native list format, but only the "predictions" item, and not "meta"

Examples

## Not run: 
  forecast_data <- forecast_data_from_cdc_csv_file(2016, "my_forecast.cdc.csv")

## End(Not run)

forecast_data_from_cdc_csv_file() helper

Description

forecast_data_from_cdc_csv_file() helper

Usage

forecast_data_from_cdc_data_frame(season_start_year, cdc_data_frame)

Arguments

Value

same as forecast_data_from_cdc_csv_file()

Gets a forecast's information

Description

Gets a forecast's information

Usage

forecast_info(zoltar_connection, forecast_url)

Arguments

Value

A list of forecast information for the passed forecast_url

Examples

## Not run: 
  the_forecast_info <- forecast_info(conn, "http://example.com/api/forecast/1/")

## End(Not run)

Get a model's forecasts

Description

Get a model's forecasts

Usage

forecasts(zoltar_connection, model_url)

Arguments

Value

A data.frame of forecast information for the passed model

Examples

## Not run: 
  the_forecasts <- forecasts(conn, "http://www.zoltardata.com/api/model/1/")

## End(Not run)

Get JSON for a resource (URL). Authenticates if necessary

Description

Get JSON for a resource (URL). Authenticates if necessary

Usage

get_resource(zoltar_connection, url, col_types = NULL)

Arguments

Value

A list that contains JSON information for the passed URL

Gets a job's file's data

Description

Downloads the data for jobs that have an associated file, such as a query's results. Called on Jobs that are the results of a project forecast or truth queries via submit_query(). NB: It is a 404 Not Found error if this is called on a Job that has no underlying S3 data file, which can happen b/c: 1) 24 hours has passed (the expiration time) or 2) the Job is not complete and therefore has not saved the data file. For the latter you may use busy_poll_job() to ensure the job is done.

Usage

job_data(zoltar_connection, job_url, query_type)

Arguments

Value

A data.frame of Job's data. The columns depend on query_type - see https://docs.zoltardata.com/fileformats/#truth-data-format-csv and https://docs.zoltardata.com/fileformats/#forecast-data-format-csv.

Examples

## Not run: 
  the_job_data <- job_data(conn, "http://example.com/api/job/2/")

## End(Not run)

Get a job's information

Description

Gets a job's information that can be used to track the job's progress. Jobs represent long-running asynchronous activities like uploading a file (e.g., a forecast or truth) or running a query.

Usage

job_info(zoltar_connection, job_url)

Arguments

Value

A list of job information for the passed job_url. it has these names: id, url, status, user, created_at, updated_at, failure_message, input_json, output_json

Examples

## Not run: 
  the_job_info <- job_info(conn, "http://example.com/api/job/2/")

## End(Not run)

Get a new forecast upload's url

Description

A helper function for jobs representing file uploads. Returns the URL of a newly-uploaded forecast from job_info.

Usage

job_info_forecast_url(zoltar_connection, the_job_info)

Arguments

Value

A URL of the new forecast

Examples

## Not run: 
  new_forecast_url <- job_info_forecast_url(conn, "http://example.com/api/job/2/")

## End(Not run)

Get a project's latest_forecasts

Description

Get a project's latest_forecasts

Usage

latest_forecasts(zoltar_connection, project_url)

Arguments

Value

A data.frame of all of the latest forecasts for the passed project. columns: forecast_id, source. (Later we may generalize to allow passing specific columns to retrieve, such as 'forecast_model_id', 'time_zero_id', 'issued_at', 'created_at', 'source', and 'notes'.)

Examples

## Not run: 
  the_latest_forecasts <- latest_forecasts(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

Get information about a model

Description

Get information about a model

Usage

model_info(zoltar_connection, model_url)

Arguments

Value

A list of model information for the passed model_url

Examples

## Not run: 
  the_model_info <- model_info(conn, "http://www.zoltardata.com/api/model/1/")

## End(Not run)

Get a project's models

Description

Get a project's models

Usage

models(zoltar_connection, project_url)

Arguments

Value

A data.frame of model contents for all models in the passed project

Examples

## Not run: 
  the_models <- models(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

Get a connection to a Zoltar host

Description

Returns a new connection object, which is the starting point for working with the Zoltar API. Once you have the connection you can call zoltar_authenticate() on it, and then call projects() to get a list of Project objects to start working with.

Usage

new_connection(host = "https://zoltardata.com")

Arguments

Details

A note on URLs: We require a trailing slash ('/') on all URLs. The only exception is the host arg passed to this function. This convention matches Django REST framework one, which is what Zoltar is written in.

Value

A ZoltarConnection object

Examples

## Not run: 
  conn <- new_connection()

## End(Not run)

Get information about a project

Description

Get information about a project

Usage

project_info(zoltar_connection, project_url)

Arguments

Value

A list of project information for the passed project_url

Examples

## Not run: 
  the_project_info <- project_info(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

Get information about all projects

Description

Get information about all projects

Usage

projects(zoltar_connection)

Arguments

Value

A data.frame of all projects' contents

Examples

## Not run: 
  the_projects <- projects(conn)

## End(Not run)

Converts forecast data from Zoltar's native list format to a quantile data.frame

Description

Converts forecast data from Zoltar's native list format to a quantile data.frame

Usage

quantile_data_frame_from_forecast_data(forecast_data)

Arguments

Value

A data.frame from forecast_data that's the same as data_frame_from_forecast_data() does except only includes point and quantile rows, and with this header: 'location', 'target', 'type', 'quantile', 'value', i.e., 'unit' -> 'location' and 'class' -> 'type'

Examples

## Not run: 
  forecast_data <- jsonlite::read_json("docs-predictions.json")
  data_frame <- quantile_data_frame_from_forecast_data(forecast_data)

## End(Not run)

Submit a query

Description

Submits a request for the execution of a query of either forecasts or truth in this Project.

Usage

submit_query(zoltar_connection, project_url, query_type, query)

Arguments

Value

a Job URL for tracking the query and getting its results when it successfully completes

Examples

## Not run: 
  job_url <- submit_query(conn, "https://www.zoltardata.com/api/project/9/", "forecasts",
                          list("models"=list("60-contact", "CovidIL_100"), "units"=list("US"),
                          "targets"=list(1894, 1897), "timezeros"=list("2020-05-14", "2020-05-09"),
                          "types"=list("point", "quantile")))

## End(Not run)

Get information about a target

Description

Get information about a target

Usage

target_info(zoltar_connection, target_url)

Arguments

Value

A list of target information for the passed target_url

Examples

## Not run: 
  the_target_info <- target_info(conn, "https://www.zoltardata.com/api/target/3/")

## End(Not run)

Get a project's targets

Description

Get a project's targets

Usage

targets(zoltar_connection, project_url)

Arguments

Value

A data.frame of target contents for the passed project

Examples

## Not run: 
  the_targets <- targets(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

Get information about a timezero

Description

Get information about a timezero

Usage

timezero_info(zoltar_connection, timezero_url)

Arguments

Value

A list of timezero information for the passed timezero_url

Examples

## Not run: 
  the_timezero_info <- timezero_info(conn, "https://www.zoltardata.com/api/timezero/3/")

## End(Not run)

Get a project's timezeros

Description

Get a project's timezeros

Usage

timezeros(zoltar_connection, project_url)

Arguments

Value

A data.frame of timezero contents for the passed project

Examples

## Not run: 
  the_timezeros <- timezeros(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

Get information about a project's truth

Description

Get information about a project's truth

Usage

truth_info(zoltar_connection, project_url)

Arguments

Value

A list of project truth information for the passed project_url

Examples

## Not run: 
  the_truth_info <- truth_info(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)

Get information about a unit

Description

Get information about a unit

Usage

unit_info(zoltar_connection, unit_url)

Arguments

Value

A list of unit information for the passed unit_url

Examples

## Not run: 
  the_unit_info <- unit_info(conn, "https://www.zoltardata.com/api/unit/3/")

## End(Not run)

Upload a forecast

Description

This function submits forecast data to the server for uploading. Returns a Job object that can be used to up, which depends on the number of current uploads in the queue. Zoltar tracks these via Job objects.)

Usage

upload_forecast(
  zoltar_connection,
  model_url,
  timezero_date,
  forecast_data,
  is_json = TRUE,
  notes = ""
)

Arguments

Value

A Job URL for the upload

Examples

## Not run: 
  forecast_data <- jsonlite::read_json("docs-predictions.json")
  job_url <- upload_forecast(conn, "http://www.zoltardata.com/api/model/1/",
                             "2017-01-17", forecast_data, TRUE, "a mid-January forecast")

## End(Not run)

Upload truth data

Description

Uploads the data in truth_csv_file to the project identified by project_url.

Usage

upload_truth(zoltar_connection, project_url, truth_csv_file, issued_at = NULL)

Arguments

Value

A Job URL for the upload

Examples

## Not run: 
  job_url <- upload_truth(conn, "http://www.zoltardata.com/api/project/1/", "truth.csv")

## End(Not run)

Log in to a Zoltar host

Description

Returns a new ZoltarConnection object, which is the starting point for working with the Zoltar API. Once you have the connection you can call zoltar_authenticate() on it, and call projects() to get a list of objects to start working with.

Usage

zoltar_authenticate(zoltar_connection, username, password)

Arguments

Value

None

Examples

## Not run: 
  zoltar_authenticate(conn, "USERNAME", "PASSWORD")

## End(Not run)

Get a project's zoltar_units

Description

Get a project's zoltar_units

Usage

zoltar_units(zoltar_connection, project_url)

Arguments

Value

A data.frame of unit contents for the passed project

Examples

## Not run: 
  the_units <- zoltar_units(conn, "https://www.zoltardata.com/api/project/9/")

## End(Not run)