NSSP emergency department visits¶

Data access¶

get_nssp ¶

get_nssp(disease: str | Iterable[str] | None = None, state_abb: str | Iterable[str] | None = None, dataset: NSSPDataset = 'gold', as_of: date | None = None, start_date: date | None = None, end_date: date | None = None, lazy: Literal[True] = ..., get_exclusions: bool = False, exclusions_as_of: date | None = None) -> LazyFrame

get_nssp(disease: str | Iterable[str] | None = None, state_abb: str | Iterable[str] | None = None, dataset: NSSPDataset = 'gold', as_of: date | None = None, start_date: date | None = None, end_date: date | None = None, lazy: Literal[False] = ..., get_exclusions: bool = False, exclusions_as_of: date | None = None) -> DataFrame

get_nssp(disease: str | Iterable[str] | None = None, state_abb: str | Iterable[str] | None = None, dataset: NSSPDataset = 'gold', as_of: date | None = None, start_date: date | None = None, end_date: date | None = None, lazy: bool = True, get_exclusions: bool = False, exclusions_as_of: date | None = None) -> DataFrame | LazyFrame

Retrieve and filter NSSP emergency department data.

This function retrieves vintages of NSSP emergency department visits data specified by the as_of date from the datacat.public.stf catalog. It filters data for a specific disease and location, within optional date boundaries, as available up to a specified reference date.

Parameters:

Name	Type	Description	Default
`disease`	`str \| Iterable[str] \| None`	The disease to filter for ("covid", "flu", "rsv", or the aggregate "total" series). If None, all diseases are included.	`None`
`state_abb`	`str \| Iterable[str] \| None`	Location abbreviation to filter for. If None, all locations are included.	`None`
`dataset`	`NSSPDataset`	One of the two datasets to retrieve from datacat: "gold" or "comprehensive" (defaults to "gold").	`'gold'`
`as_of`	`date \| None`	Reference date for data availability. Only data available as of this date will be used. If None, all available data will be used (defaults to None).	`None`
`start_date`	`date \| None`	Start date for filtering data (inclusive). If None, no lower bound is applied (defaults to None).	`None`
`end_date`	`date \| None`	End date for filtering data (inclusive). If None, no upper bound is applied (defaults to None).	`None`
`lazy`	`bool`	Whether to return a lazy frame (defaults to True). If True, returns a `pl.LazyFrame`; if False, returns a `pl.DataFrame`.	`True`
`get_exclusions`	`bool`	Add Boolean `exclude` flags from a published data-review snapshot, without removing observations. Defaults to False. Reviews apply to all diseases at a location. The latest `report_date` in the loaded NSSP data selects the review date, before applying observation filters.	`False`
`exclusions_as_of`	`date \| None`	The latest catalog version date to consider for the data-review snapshot, or None for the newest available snapshot. Uses the same inclusive cutoff convention as `as_of`, independently of the NSSP vintage and review report date. Requires `get_exclusions=True`. Use `resolve_nssp_exclusion_version(as_of=exclusions_as_of)` to record the selected version.	`None`

Returns:

Type Description

DataFrame | LazyFrame

Aggregated ED counts with columns: date, state_abb, disease, target_type, value, and exclude. target_type is always "inc ed visits", and value is the corresponding incident ED-visit count. exclude is always a non-null Boolean column. Flags are False when exclusions are disabled or missing. A missing snapshot or review date emits a warning; an incompatible snapshot schema raises ValueError.

Notes

Catalog disease labels are converted to the canonical names "covid", "flu", and "rsv".
The function only includes data from parquet files with dates up to and including the as_of date.

Version resolution¶

resolve_nssp_version ¶

resolve_nssp_version(dataset: NSSPDataset = 'gold', as_of: date | None = None) -> datetime | str | None

Resolve the catalog version that get_nssp would load.

Parameters:

Name	Type	Description	Default
`dataset`	`NSSPDataset`	One of the two NSSP datasets: `"gold"` or `"comprehensive"`.	`'gold'`
`as_of`	`date \| None`	The latest catalog version date to consider. If None, resolves the most recent available version.	`None`

Returns:

Type	Description
`datetime \| str \| None`	The selected catalog version converted to a datetime when possible, or None if no version matches.

resolve_nssp_exclusion_version ¶

resolve_nssp_exclusion_version(as_of: date | None = None) -> datetime | str | None

Resolve the data-review snapshot that get_nssp would load.

Parameters:

Name	Type	Description	Default
`as_of`	`date \| None`	The latest catalog version date to consider, corresponding to `get_nssp(exclusions_as_of=...)`. If None, resolves the most recent available version.	`None`

Returns:

Type	Description
`datetime \| str \| None`	The selected catalog version converted to a datetime when possible, or None if no version matches.