Skip to content

epymorph.adrio.cdc

ResultT module-attribute 

ResultT = TypeVar('ResultT', bound=generic)

COVIDFacilityHospitalization 

COVIDFacilityHospitalization(
    *,
    age_group: Literal[
        "adult", "pediatric", "both"
    ] = "both",
    fix_redacted: FixLikeInt = False,
    fix_missing: FillLikeInt = False,
)

Bases: _HealthdataAnagCw7uMixin, FetchADRIO[DateValueType, int64]

Loads COVID hospitalization data from HealthData.gov's "COVID-19 Reported Patient Impact and Hospital Capacity by Facility" dataset. The data were reported by healthcare facilities on a weekly basis, starting 2019-12-29 and ending 2024-04-21, although the data is not complete over this entire range, nor over the entire United States.

This ADRIO supports geo scopes at US State and County granularities in 2019. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of reported hospitalizations. The data contain sentinel values (-999999) which represent values redacted for the sake of protecting patient privacy -- there were between 1 and 3 cases reported by the facility on that date.

NOTE: this data source has a number of issues representing Alaska geography. It uses borough 02280 which isn't in the Census geography until 2020, and simultaneously uses pre-1980 Alaska geography (02080, 02120, 02210, and 02260). This makes these data inaccessible via this ADRIO. If Alaska data is important for your use-case, we recommend processing the data another way.

Parameters:

  • age_group (Literal['adult', 'pediatric', 'both'], default: 'both' ) –

    Which age group to fetch data for.

  • fix_redacted (FixLikeInt, default: False ) –

    The method to use to replace redacted values (-999999 in the data).

  • fix_missing (FillLikeInt, default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation.

InfluenzaFacilityHospitalization 

InfluenzaFacilityHospitalization(
    *,
    fix_redacted: FixLikeInt = False,
    fix_missing: FillLikeInt = False,
)

Bases: _HealthdataAnagCw7uMixin, FetchADRIO[DateValueType, int64]

Loads influenza hospitalization data from HealthData.gov's "COVID-19 Reported Patient Impact and Hospital Capacity by Facility" dataset. The data were reported by healthcare facilities on a weekly basis, starting 2019-12-29 and ending 2024-04-21, although the data is not complete over this entire range, nor over the entire United States.

This ADRIO supports geo scopes at US State and County granularities in 2019. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of reported hospitalizations. The data contain sentinel values (-999999) which represent values redacted for the sake of protecting patient privacy -- there were between 1 and 3 cases reported by the facility on that date.

NOTE: the data source has a number of issues representing Alaska geography. It uses borough 02280 which isn't in the Census geography until 2020, and simultaneously uses pre-1980 Alaska geography (02080, 02120, 02210, and 02260). This makes these data inaccessible via this ADRIO. If Alaska data is important for your use-case, we recommend processing the data another way.

Parameters:

  • fix_redacted (FixLikeInt, default: False ) –

    The method to use to replace redacted values (-999999 in the data).

  • fix_missing (FillLikeInt, default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation.

COVIDCountyCases 

COVIDCountyCases(
    *,
    fix_missing: Fill[int64]
    | int
    | Callable[[], int]
    | Literal[False] = False,
)

Bases: FetchADRIO[DateValueType, int64]

Loads COVID case data from data.cdc.gov's dataset named "United States COVID-19 Community Levels by County".

The data were reported starting 2022-02-24 and ending 2023-05-11, and aggregated by CDC to the US County level.

This ADRIO supports geo scopes at US State and County granularity (2015 through 2019 allowed). The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of cases, calculated by multiplying the per-100k rates by the county population and rounding (via banker's rounding).

Parameters:

See Also

The dataset documentation.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

validate_context 

validate_context(context: Context)

Validates the context before ADRIO evaluation.

Parameters:

  • context (Context) –

    The context to validate.

Raises:

validate_result 

validate_result(context: Context, result: NDArray) -> None

Validates that the result of evaluating the ADRIO adheres to the expected result format.

Parameters:

  • context (Context) –

    The context in which the result has been evaluated.

  • result (NDArray[ResultT]) –

    The result produced by the ADRIO.

Raises:

COVIDStateHospitalization 

COVIDStateHospitalization(
    *,
    fix_missing: FillLikeInt = False,
    allow_voluntary: bool = True,
)

Bases: _DataCDCAemtMg7gMixin, FetchADRIO[DateValueType, int64]

Loads COVID hospitalization data from data.cdc.gov's dataset named "Weekly United States Hospitalization Metrics by Jurisdiction, During Mandatory Reporting Period from August 1, 2020 to April 30, 2024, and for Data Reported Voluntarily Beginning May 1, 2024, National Healthcare Safety Network (NHSN) - ARCHIVED".

The data were reported by healthcare facilities on a weekly basis to CDC's National Healthcare Safety Network with reporting dates starting 2020-08-08 and ending 2024-10-26. The data were aggregated by CDC to the US State level. While reporting was initially federally required, beginning May 2024 reporting became entirely voluntary and as such may include fewer responses.

This ADRIO supports geo scopes at US State granularity. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of reported hospitalizations.

Parameters:

  • fix_missing (FillLikeInt, default: False ) –

    The method to use to fix missing values.

  • allow_voluntary (bool, default: True ) –

    Whether or not to accept voluntary data. If False and if the simulation time frame overlaps the voluntary period, such data will be masked. Set this to False if you want to be sure you are only using data during the required reporting period.

See Also

The dataset documentation.

InfluenzaStateHospitalization 

InfluenzaStateHospitalization(
    *,
    fix_missing: FillLikeInt = False,
    allow_voluntary: bool = True,
)

Bases: _DataCDCAemtMg7gMixin, FetchADRIO[DateValueType, int64]

Loads influenza hospitalization data from data.cdc.gov's dataset named "Weekly United States Hospitalization Metrics by Jurisdiction, During Mandatory Reporting Period from August 1, 2020 to April 30, 2024, and for Data Reported Voluntarily Beginning May 1, 2024, National Healthcare Safety Network (NHSN) - ARCHIVED".

The data were reported by healthcare facilities on a weekly basis to CDC's National Healthcare Safety Network with reporting dates starting 2020-08-08 and ending 2024-10-26. The data were aggregated by CDC to the US State level. While reporting was initially federally required, beginning May 2024 reporting became entirely voluntary and as such may include fewer responses.

This ADRIO supports geo scopes at US State granularity. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of reported hospitalizations.

Parameters:

  • fix_missing (FillLikeInt, default: False ) –

    The method to use to fix missing values.

  • allow_voluntary (bool, default: True ) –

    Whether or not to accept voluntary data. If False and if the simulation time frame overlaps the voluntary period, such data will be masked. Set this to False if you want to be sure you are only using data during the required reporting period.

See Also

The dataset documentation.

COVIDVaccination 

COVIDVaccination(
    vaccine_status: Literal[
        "at least one dose",
        "full series",
        "full series and booster",
    ],
    *,
    fix_missing: Fill[int64]
    | int
    | Callable[[], int]
    | Literal[False] = False,
)

Bases: FetchADRIO[DateValueType, int64]

Loads COVID hospitalization data from data.cdc.gov's dataset named "COVID-19 Vaccinations in the United States,County".

The data cover a time period starting 2020-12-13 and ending 2023-05-10. Up through 2022-06-16, data were reported on a daily cadence, and after that switched to a weekly cadence.

This ADRIO supports geo scopes at US State and County granularity (2015 through 2019 allowed). The data appears to have been compiled using 2019 Census delineations, so for best results, use a geo scope for that year. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting dates during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of people who have had the requested vaccine dosage.

Parameters:

  • vaccine_status (Literal['at least one dose', 'full series', 'full series and booster']) –

    The dataset breaks down vaccination status by how many doses individuals have received. Use this to specify which status you're interested in. "at least one dose" includes people who have received at least one COVID vaccine dose; "full series" includes people who have received at least either two doses of a two-dose vaccine or one dose of a one-dose vaccine; "full series and booster" includes people who have received the full series and at least one booster dose.

  • fix_missing (Fill[int64] | int | Callable[[], int] | Literal[False], default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

validate_context 

validate_context(context: Context)

Validates the context before ADRIO evaluation.

Parameters:

  • context (Context) –

    The context to validate.

Raises:

validate_result 

validate_result(context: Context, result: NDArray) -> None

Validates that the result of evaluating the ADRIO adheres to the expected result format.

Parameters:

  • context (Context) –

    The context in which the result has been evaluated.

  • result (NDArray[ResultT]) –

    The result produced by the ADRIO.

Raises:

CountyDeaths 

CountyDeaths(
    cause_of_death: Literal["all", "COVID-19"],
    *,
    fix_redacted: Fix[int64]
    | int
    | Callable[[], int]
    | Literal[False] = False,
    fix_missing: Fill[int64]
    | int
    | Callable[[], int]
    | Literal[False] = False,
)

Bases: FetchADRIO[DateValueType, int64]

Loads COVID and total deaths data from data.cdc.gov's dataset named "AH COVID-19 Death Counts by County and Week, 2020-present".

The data were reported starting 2020-01-04 and ending 2023-04-01, and aggregated by CDC to the US County level.

This ADRIO supports geo scopes at US State and County granularity (2014 through 2019 allowed). The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of deaths.

NOTE: this data source uses non-standard geography for two county-equivalents. In Alaska, 02270 was the Wade Hampton Census Area prior to 2015 and thereafter renamed Kusilvak Census Area with code 02158. And in South Dakota, 46113 was Shannon County prior to 2015 and thereafter renamed Oglala Lakota County with code 46102. These data are inaccessible via this ADRIO unless you use 2014 geography.

Parameters:

  • cause_of_death (Literal['all', 'COVID-19']) –

    The cause of death.

  • fix_redacted (Fix[int64] | int | Callable[[], int] | Literal[False], default: False ) –

    The method to use to fix redacted values.

  • fix_missing (Fill[int64] | int | Callable[[], int] | Literal[False], default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

validate_context 

validate_context(context: Context)

Validates the context before ADRIO evaluation.

Parameters:

  • context (Context) –

    The context to validate.

Raises:

validate_result 

validate_result(context: Context, result: NDArray) -> None

Validates that the result of evaluating the ADRIO adheres to the expected result format.

Parameters:

  • context (Context) –

    The context in which the result has been evaluated.

  • result (NDArray[ResultT]) –

    The result produced by the ADRIO.

Raises:

StateDeaths 

StateDeaths(
    cause_of_death: Literal[
        "all", "COVID-19", "influenza", "pneumonia"
    ],
    *,
    fix_redacted: Fix[int64]
    | int
    | Callable[[], int]
    | Literal[False] = False,
    fix_missing: Fill[int64]
    | int
    | Callable[[], int]
    | Literal[False] = False,
)

Bases: FetchADRIO[DateValueType, int64]

Loads deaths data (COVID-19, influenza, pneumonia, and total) from data.cdc.gov's dataset named "Provisional COVID-19 Death Counts by Week Ending Date and State".

The data were reported starting 2020-01-04 and aggregated by CDC to the US State level.

This ADRIO supports geo scopes at US State granularity. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Values are tuples of date and the integer number of deaths.

Parameters:

  • cause_of_death (Literal['all', 'COVID-19', 'influenza', 'pneumonia']) –

    The cause of death.

  • fix_redacted (Fix[int64] | int | Callable[[], int] | Literal[False], default: False ) –

    The method to use to fix redacted values.

  • fix_missing (Fill[int64] | int | Callable[[], int] | Literal[False], default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

validate_context 

validate_context(context: Context)

Validates the context before ADRIO evaluation.

Parameters:

  • context (Context) –

    The context to validate.

Raises:

validate_result 

validate_result(context: Context, result: NDArray) -> None

Validates that the result of evaluating the ADRIO adheres to the expected result format.

Parameters:

  • context (Context) –

    The context in which the result has been evaluated.

  • result (NDArray[ResultT]) –

    The result produced by the ADRIO.

Raises:

CurrentStateHospitalization 

CurrentStateHospitalization(
    *,
    disease: Disease,
    age_group: AgeGroup = "Total",
    fix_missing: FillLikeInt = False,
)

Bases: _DataCDCMpgqJmmrMixin[int64], FetchADRIO[DateValueType, int64]

Loads disease-specific hospitalization data from data.cdc.gov's dataset named "Weekly Hospital Respiratory Data (HRD) Metrics by Jurisdiction, National Healthcare Safety Network (NHSN) (Preliminary)".

The data are currently being reported by healthcare facilities on a weekly basis to CDC's National Healthcare Safety Network. This ADRIO loads recent data from the source, starting 2024-11-02 and onward. (Data exist before this date but with some caveats; see COVIDStateHospitalization and InfluenzaStateHospitalization for ADRIOs which support earlier, archived data.) The data were aggregated by CDC to the US State level.

This ADRIO supports geo scopes at US State granularity. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Dates represent the MMWR week ending date of the data collection week. Values are tuples of date and the integer number of reported hospitalizations.

Parameters:

  • fix_missing (FillLikeInt, default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation. epymorph.adrio.cdc.COVIDStateHospitalization and epymorph.adrio.cdc.InfluenzaStateHospitalization for data prior to 2024-11-01.

Disease class-attribute instance-attribute 

Disease = Literal['Covid', 'Influenza', 'RSV']

A disease category available in this data.

AgeGroup class-attribute instance-attribute 

AgeGroup = Literal['Total', 'Adult', 'Pediatric']

An age category available in this data.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

CurrentStateHospitalizationICU 

CurrentStateHospitalizationICU(
    *,
    disease: Disease,
    age_group: AgeGroup = "Total",
    fix_missing: FillLikeFloat = False,
)

Bases: _DataCDCMpgqJmmrMixin[float64], FetchADRIO[DateValueType, float64]

Loads disease-specific ICU hospitalization data from data.cdc.gov's dataset named "Weekly Hospital Respiratory Data (HRD) Metrics by Jurisdiction, National Healthcare Safety Network (NHSN) (Preliminary)".

The data are currently being reported by healthcare facilities on a weekly basis to CDC's National Healthcare Safety Network. This ADRIO loads recent data from the source, starting 2024-11-02 and onward. The data were aggregated by CDC to the US State level.

This ADRIO supports geo scopes at US State granularity. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Dates represent the MMWR week ending date of the data collection week. Values are tuples of date and the integer number of reported ICU hospitalizations.

Parameters:

  • fix_missing (FillLikeFloat, default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation.

Disease class-attribute instance-attribute 

Disease = Literal['Covid', 'Influenza', 'RSV']

A disease category available in this data.

AgeGroup class-attribute instance-attribute 

AgeGroup = Literal['Total', 'Adult', 'Pediatric']

An age category available in this data.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

CurrentStateAdmissions 

CurrentStateAdmissions(
    *,
    disease: Disease,
    age_group: AgeGroup = "Total",
    fix_missing: FillLikeInt = False,
)

Bases: _DataCDCMpgqJmmrMixin[int64], FetchADRIO[DateValueType, int64]

Loads disease-specific hospital admissions data from data.cdc.gov's dataset named "Weekly Hospital Respiratory Data (HRD) Metrics by Jurisdiction, National Healthcare Safety Network (NHSN) (Preliminary)".

The data are currently being reported by healthcare facilities on a weekly basis to CDC's National Healthcare Safety Network. This ADRIO loads recent data from the source, starting 2024-11-02 and onward. (Data exist before this date but with some caveats; see COVIDStateHospitalization and InfluenzaStateHospitalization for ADRIOs which support earlier, archived data.) The data were aggregated by CDC to the US State level.

This ADRIO supports geo scopes at US State granularity. The data loaded will be matched to the simulation time frame. The result is a 2D matrix where the first axis represents reporting weeks during the time frame and the second axis is geo scope nodes. Dates represent the MMWR week ending date of the data collection week. Values are tuples of date and the integer number of reported hospital admissions.

Parameters:

  • fix_missing (FillLikeInt, default: False ) –

    The method to use to fix missing values.

See Also

The dataset documentation. epymorph.adrio.cdc.COVIDStateHospitalization and epymorph.adrio.cdc.InfluenzaStateHospitalization for data prior to 2024-11-01.

Disease class-attribute instance-attribute 

Disease = Literal['Covid', 'Influenza', 'RSV']

A disease category available in this data.

AgeGroup class-attribute instance-attribute 

AgeGroup = Literal[
    "0 to 4",
    "5 to 17",
    "18 to 49",
    "50 to 64",
    "65 to 74",
    "75 and above",
    "Unknown",
    "Adult",
    "Pediatric",
    "Total",
]

An age category available in this data.

result_format property 

result_format: ResultFormat

Information about the expected format of the ADRIO's resulting data.

healthdata_api_key 

healthdata_api_key() -> str | None

Loads the Socrata API key to use for healthdata.gov, as environment variable 'API_KEY__healthdata.gov'.

Returns:

  • str | None –

    The key or None if it is not set.

data_cdc_api_key 

data_cdc_api_key() -> str | None

Loads the Socrata API key to use for data.cdc.gov, as environment variable 'API_KEY__data.cdc.gov'.

Returns:

  • str | None –

    The key or None if it is not set.