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] = ...) -> 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] = ...) -> 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) -> 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`

Returns:

Type	Description
`DataFrame \| LazyFrame`	Aggregated ED counts with columns: `date`, `state_abb`, `disease`, `target_type`, and `value`. `target_type` is always `"inc ed visits"`, and `value` is the corresponding incident ED-visit count.

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.

Tail exclusion¶

get_nssp_with_exclusion ¶

get_nssp_with_exclusion(disease: str, state_abb: str, exclusion_strategy: Literal['tail_by_target_disease', 'tail_by_all_disease', 'tail_by_total', 'tail_by_n'] = 'tail_by_total', dataset: NSSPDataset = 'gold', as_of: date | None = None, start_date: date | None = None, end_date: date | None = None, **exclusion_strategy_args) -> DataFrame

Retrieve NSSP data and attach an exclusion flag for tail observations.

The exclusion flag is calculated for a single disease and location using one of the supported strategies, then joined back to the requested NSSP data by date.

Parameters:

Name	Type	Description	Default
`disease`	`str`	Disease to retrieve. Exactly one disease must be supplied.	required
`state_abb`	`str`	Location abbreviation to retrieve. Exactly one location must be supplied.	required
`exclusion_strategy`	`Literal['tail_by_target_disease', 'tail_by_all_disease', 'tail_by_total', 'tail_by_n']`	Strategy used to calculate the exclusion flag: "tail_by_target_disease": detect tail outliers using the requested disease only. "tail_by_all_disease": detect tail outliers using flu, rsv, and covid summed by date. "tail_by_total": detect tail outliers using the NSSP "total" disease series. "tail_by_n": exclude the final `n` reference dates.	`'tail_by_total'`
`dataset`	`NSSPDataset`	NSSP dataset to retrieve from datacat: "gold" or "comprehensive".	`'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.	`None`
`start_date`	`date \| None`	Start date for filtering NSSP data, inclusive. If None, no lower bound is applied.	`None`
`end_date`	`date \| None`	End date for filtering NSSP data, inclusive. If None, no upper bound is applied.	`None`
`**exclusion_strategy_args`		Additional keyword arguments passed to the selected exclusion strategy. For automatic tail strategies, these are passed to `exclude_tail_auto`; for "tail_by_n", pass `n`.	`{}`

Returns:

Type	Description
`DataFrame`	NSSP data for the requested disease and location with an added `exclude` column indicating whether each `date` should be excluded.

Raises:

Type	Description
`ValueError`	If multiple diseases or locations are supplied, or if `exclusion_strategy` is not supported.

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.