Package 'iidda.api'

Title: IIDDA API
Description: R Bindings for the IIDDA API.
Authors: Steve Walker [aut, cre]
Maintainer: Steve Walker <[email protected]>
License: GPL (>= 3)
Version: 0.5.0
Built: 2026-05-15 06:16:33 UTC
Source: https://github.com/canmod/iidda-tools

Help Index

iidda.api

Description

R wrapper for the IIDDA API.

Details

IIDDA is the International Infectious Disease Data Archive. This archive has an API (Application Programming Interface) for accessing data and potentially for building applications. This R package provides a simple wrapper to this API so that the datasets are returned as data frames.

Useful links for people who just want to get data.

  • ?featured

  • vignette("Quickstart")

  • vignette("Provenance")

More advanced users might be interested in the lower-level wrapper of the API operations here: ?ops.

Author(s)

Maintainer: Steve Walker [email protected]

See Also

Useful links:

CANDID Datasets

Description

Access datasets used in the paper describing the Canadian Disease Incidence Dataset (CANDID).

Usage

candid_data(dataset_id)

candid_lookup(lookup_id)

candid_metadata()

candid_data_ids()

candid_lookup_ids()

Arguments

dataset_id

ID for a particular CANDID dataset. Run candid_data_ids() for the list of available options.
lookup_id

ID for a particular CANDID lookup table. Run candid_lookup_ids() for the list of available options.

Functions

  • candid_data(): Return a data frame of one of the datasets used in the CANDID paper.

  • candid_lookup(): Return a data frame of one of the datasets used in the CANDID paper.

  • candid_metadata(): Return a list of lists, each of which represents the metadata for a CANDID dataset.

  • candid_data_ids(): Return the IDs of all the datasets used in the CANDID paper.

  • candid_lookup_ids(): Return the IDs of all the lookup tables used in the CANDID paper.

Featured Datasets

Description

Access featured datasets and associated metadata. These datasets required substantial preparation to enhance their utility for research and analysis.

Usage

featured_data(dataset_id, ...)

featured_metadata()

featured_ids()

Arguments

dataset_id

ID for a particular featured dataset. Run featured_ids() for the list of available options.
...

Character vectors for filtering the data on specific columns, with one vector for each column. See examples below for the syntax for different types of columns. The following list gives instructions for columns that might be available for your dataset. If they are not available you will get a message telling you what columns are in the dataset that you are asking for.

  • location : Location descriptor as reported in the original source.

  • iso_3166 : ISO-3166 codes for locations corresponding to countries.

  • iso_3166_2 : ISO-3166-2 codes for locations corresponding to sub-national jurisdictions.

  • date : Date of time point at which a value is reported, in ISO-8601 format (i.e. YYYY-MM-DD). Must be in the form \<start date\>..<end date\>.

  • period_start_date : The first date within the time interval for which a count was reported, in ISO-8601 format (i.e. YYYY-MM-DD). Must be in the form \<start date\>..<end date\>.

  • period_end_date : The last date within the time interval for which a count was reported, in ISO-8601 format (i.e. YYYY-MM-DD). Must be in the form \<start date\>..<end date\>.

  • period_mid_date : Date in the (rounded down) middle of a time interval for which a count was reported, in ISO-8601 format (i.e. YYYY-MM-DD). Must be in the form \<start date\>..<end date\>.

  • historical_disease_family : Disease family as reported by the original source.

  • historical_disease : Disease name as reported by the original source.

  • disease : Disease name harmonized over data sources.

  • nesting_disease : Disease name that encapsulates this disease in a hierarchy of diseases.

  • basal_disease : Base disease name that encapsulates this disease in a hierarchy of diseases.

  • icd_9 : Disease codes for version 9 of the International Statistical Classification of Diseases and Related Health Problems, published by the World Health Organization.

  • icd_7 : Disease codes for version 7 of the International Statistical Classification of Diseases and Related Health Problems, published by the World Health Organization.

  • historical_disease_subclass : Disease subclass as reported by the original source – cf. Disease

  • icd_9_subclass : Disease codes associated with a subclass identified by the original source. Codes are for version 9 of the International Statistical Classification of Diseases and Related Health Problems, published by the World Health Organization.

  • icd_7_subclass : Disease codes associated with a subclass identified by the original source. Codes are for version 7 of the International Statistical Classification of Diseases and Related Health Problems, published by the World Health Organization.

  • lower_age : Lower age bound in years of all individuals associated with a particular record. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • upper_age : Upper age bound in years of all individuals associated with a particular record. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • sex : Sex of all individuals associated with a particular record as reported by the original source.

  • cases_this_period : Number of cases reported for this period, at the end of this period – as reported by the original source. Includes different types of missing values as reported by the original source. Type "string" allows different types of missing values to be specified as reported by the original source and allows users to choose which type of missing values to work with. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • cases_prev_period : Number of cases reported for the previous period, at the end of this current period – as reported by the original source. Includes different types of missing values as reported by the original source. Type "string" allows different types of missing values to be specified as reported by the original source and allows users to choose which type of missing values to work with. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • cases_cum_report_year : Total number of cases up until this current period, in the current year – as reported by the original source. Includes different types of missing values as reported by the original source. Type "string" allows different types of missing values to be specified as reported by the original source and allows users to choose which type of missing values to work with. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • cases_cum_prev_year : Total number of cases up until this current period, in the previous year – as reported by the original source. Includes different types of missing values as reported by the original source. Type "string" allows different types of missing values to be specified as reported by the original source and allows users to choose which type of missing values to work with.

  • cases_median_prev_5_years : Median number of weekly cases in this current period, with the median taken over the previous five years – as reported by the original source. Includes different types of missing values as reported by the original source. Type "string" allows different types of missing values to be specified as reported by the original source and allows users to choose which type of missing values to work with. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • cases_cum_median_prev_5_years : Median number of cumulative cases by this current period, with the median taken over the previous five years – as reported by the original source. Includes different types of missing values as reported by the original source. Type "string" allows different types of missing values to be specified as reported by the original source and allows users to choose which type of missing values to work with. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • population : Estimated total number of individuals associated with a particular record. The first item must either be a number interval of the form \<min\>-\<max\> or 'none' (meaning no filter is applied to the case numbers). Additional items are meant to be any 'unavailable values' like 'Not available', 'Not reportable', or 'null'.

  • cause : Cause of mortality as reported by the original source.

  • location_type : Location type of recorded data (continents, countries, canadian-provinces, canadian-cities, ontario-cities, uk-cities, london-parishes) for a given record.

  • time_scale : Time scale of recorded data (wk, 2wk, mo, qr, yr) for a given record. This field is a qualitative and approximate measure of the time scale over which data were counted. For example, monthly (mo) data might include four-weekly or even five-weekly data. See columns like days_this_period for a quantitative description of the time scale if it is available, or produce your own description using period_start_date and period_end_date.

Functions

  • featured_data(): Return a data frame of a featured dataset, possibly filtered.

  • featured_metadata(): Return a list of lists, each of which represents the metadata for a featured dataset.

  • featured_ids(): Return the IDs of all the featured datasets in the repository.

Examples

options(iidda_api_msgs = FALSE)
featured_ids()
atlantic_polio_1950s = featured_data("canmod-cdi-normalized"
  , iso_3166_2 = c("CA-NL", "CA-NS", "CA-PE", "CA-NB")
  , basal_disease = "poliomyelitis"
  , period_end_date = "1950-01-01..1959-12-31"
)
head(atlantic_polio_1950s)

Links to IIDDA API Interactive Documentation

Description

Links to IIDDA API Interactive Documentation

Usage

docs_url

docs_url_staging

docs_url_local

Format

An object of class character of length 0.

An object of class character of length 1.

An object of class character of length 1.

Functions

  • docs_url: Link to interactive documentation.

  • docs_url_staging: Link to interactive documentation for a staging environment.

  • docs_url_local: Localhost link to interactive documentation for a development environment, if it exists.

IIDDA API Operations

Description

Objects containing the functions associated with API functions documented here. These objects are for advanced usage, providing more functionality than the simpler tools for accessing featured_data.

Usage

ops

ops_local

ops_staging

Format

An object of class try-error of length 1.

An object of class try-error of length 1.

An object of class list of length 6.

Functions

  • ops: List containing available operations from the IIDDA API as R functions

  • ops_local: Operations list for a local development environment, if it exists

  • ops_staging: Operations list for a staging environment, if it exists

Examples

## Print out the available functions.
names(ops_staging)

## Access functions with a dollar sign. For example, this command
## will give weekly incidence data in January of 1956.
options(iidda_api_msgs = FALSE, iidda_api_all_char = TRUE)
jan_56 = ops_staging$filter(
     resource_type = "Communicable Disease Incidence"
   , dataset_id = "cdi_ca_1956_wk_prov_dbs"
   , period_end_date = "1956-01-01..1956-02-01"
   , time_scale = "wk"
)
cols = c(
    "period_end_date"
  , "location"
  , "historical_disease"
  , "cases_this_period"
)
print(jan_56[, cols])

## Operations objects that are not available are error objects. As of the
## time of writing `ops` is not live, but will be.
print(class(ops))

## The `ops_local` is only live for developers who have deployed a
## local version of the API.
print(class(ops_local))

Data Provenance

Description

Get URLs to dependencies of datasets for investigating data provenance. See vignette("Provenance") for an illustration. See iidda-staging for information on IIDDA identifiers. If you do not have access to this link, please contact the maintainer.

Usage

url_scans(
  scan_ids,
  dataset_ids = character(),
  metadata = ops_staging$metadata(dataset_ids = dataset_ids)
)

url_digitizations(
  digitization_ids,
  dataset_ids = character(),
  metadata = ops_staging$metadata(dataset_ids = dataset_ids)
)

url_affected_scripts(
  digitization_id,
  dataset_ids = character(),
  metadata = ops_staging$metadata(dataset_ids = dataset_ids)
)

Arguments

scan_ids

Character vector of identifiers for scans.
dataset_ids

Identifiers for datasets that will restrict the search for dependencies to metadata for these datasets.
metadata

List of IIDDA DataCite metadata over a collection of datasets.
digitization_ids

Character vector of identifiers for digitizations.
digitization_id

Single digitization identifier.

Functions

  • url_scans(): Convert scan identifiers into URLs that link to associated scans (typically PDF files).

  • url_digitizations(): Convert digitization identifiers into URLs that link to associated digitizations (typically Excel files).

  • url_affected_scripts(): Returns URLs to all prep scripts that could have their output modified if the identified digitization were modified.