Episuite API

episuite – Main package

episuite.data – Data handling and samples

episuite.data.admissions_sample() → pandas.core.frame.DataFrame

Sample data for ICU hospitalization admissions. This data is based on COVID-19 outbreak in Porto Alegre/RS/Brazil. This dataset contains three columns that are described below.

DATE_START

When the patient enters in the ICU.

DATE_END

When the patient left the ICU by an outcome.

OUTCOME

Outcome when the patient left the ICU (DATE_END)

Returns

sample data w/ admission

episuite.data.download_remote(url: str, stream: BinaryIO, desc: Optional[str] = None, show_progress: bool = True) → None

This function will download data frmo a remote URL and will optionally show the progress.

Parameters

• url – the url to download from

• stream – buffered IO object

• desc – progress bar description

• show_progress – whether to show progress or not

episuite.data.get_cache_dir_file(filename: Optional[Union[str, pathlib.Path]] = None) → pathlib.Path

episuite.data.load_from_cache(url: str, filename: Union[str, pathlib.Path], desc: Optional[str] = None, show_progress: bool = True, invalidate: bool = False) → pathlib.Path

episuite.icu – Intensive Care Unit (ICU) tools

class episuite.icu.ICUAdmissions(s_admissions: pandas.core.series.Series)

Bases: object

This class will wrap admissions (Series) and will provide utility methods to handle ICU admissions. The series is sorted by the index in ascending manner. The series is also copied.

Parameters

s_admissions – a series with dates in the index and admissions for each day.

get_admissions_series() → pandas.core.series.Series

Returns the internal admission series.

sanity_check() → None

This method will peform a check for the consistency of the data. It will check if there are duplicates and also if there are gaps between dates, which can be problematic when using for simulation and modelling. It will trigger an exception upon faliure.

class episuite.icu.ICUAdmissionsPlot(icu_admissions: episuite.icu.ICUAdmissions)

Bases: object

bar(locator: str = 'month', interval: int = 1) → None

class episuite.icu.ICUSimulation(admissions: episuite.icu.ICUAdmissions, duration_distribution: episuite.distributions.DurationDistribution)

Bases: object

This is the main class for the simulation of ICU/beds occupancy based on observed admissions or predicted admission.

See also

Forecasting critical care bed requirements for COVID-19 patients in England

This simulator is mainly based on this work by Jombart et al. [JNJ+20].

Analysis of the SARS-CoV-2 outbreak in Rio Grande do Sul / Brazil

This article Perone [Per20] used this simulator and describes how it works.

Parameters

• admissions – the admissions (observed or forecast)

• duration_distribution – it can be a fitted distribution supporting the duration distribution or a empirical distribution.

get_admissions() → episuite.icu.ICUAdmissions

Return the admissions.

get_duration_distribution() → episuite.distributions.DurationDistribution

Return the duration distribution.

simulate(iterations: int = 10, show_progress: bool = True, max_workers: Optional[int] = None) → episuite.icu.ICUSimulationResults

This method will perform many rounds of simulation.

Parameters

• iterations – number of simulation rounds to incorporate the uncertainty from the LoS distribution.

• show_progress – show the progress of simulation

• max_workers – the number of workers to use (processes), default to the number of cores in the machine.

simulation_round() → pandas.core.series.Series

This method will perform a single simulation round.

class episuite.icu.ICUSimulationResults(icu_simulation: episuite.icu.ICUSimulation, df_simulation: pandas.core.frame.DataFrame)

Bases: object

This class holds the results from many simulation rounds.

Parameters

• icu_simulation – the simulation instance that produced the results.

• df_simulation – the results dataframe

get_admissions() → episuite.icu.ICUAdmissions

Returns the admissions used for simulation.

get_simulation_results() → pandas.core.frame.DataFrame

Returns the dataframe with the simulation results.

hdi() → pandas.core.frame.DataFrame

Returns a dataframe with computed HPD (high density interval), mean and median values.

class episuite.icu.ICUSimulationResultsPlot(simulation_results: episuite.icu.ICUSimulationResults)

Bases: object

lineplot() → Any

Plot the simulation results and admissions used.

episuite.durations – Durations

class episuite.durations.Durations(df_durations: pandas.core.frame.DataFrame, column_start: str = 'DATE_START', column_end: str = 'DATE_END', filter_gt: bool = True)

Bases: object

COLUMN_STAY_DURATION: str = '__EPISUITE_STAY_DURATION'

get_bootstrap() → episuite.distributions.EmpiricalBootstrap

get_dataframe() → pandas.core.frame.DataFrame

get_stay_distribution() → numpy.ndarray

class episuite.durations.DurationsPlot(duration: episuite.durations.Durations)

Bases: object

Makes plots for the durations

Parameters

duration – the duration

density(**kwargs: Dict) → Any

histogram(**kwargs: Dict) → Any

timeplot(locator: str = 'month', interval: int = 1, **kwargs: Dict) → Any

episuite.distributions – Distributions

class episuite.distributions.DurationDistribution

Bases: abc.ABC

Base class for a duration distribution.

abstract sample(size: int) → numpy.ndarray

Sample from the duration distribution.

Parameters

size – amount of samples to draw.

Returns

samples from the distribution

class episuite.distributions.EmpiricalBootstrap(samples: Union[List[int], numpy.ndarray], replace: bool = True)

Bases: episuite.distributions.DurationDistribution

This distribution will bootstrap from an empirical distribution.

Parameters

replace – if sample w/ replacement or not

sample(size: Optional[int] = None) → numpy.ndarray

Sample from the duration distribution.

Parameters

size – amount of samples to draw.

Returns

samples from the distribution

episuite.prevalence – Prevalence models

episuite.prevalence.apparent_prevalence_model(x_se: int, n_se: int, x_sp: int, n_sp: int, obs_total: int, obs_positive: int, true_p_prior: numpyro.distributions.distribution.Distribution = <numpyro.distributions.continuous.Beta object>) → Any

This is a more realistic model that takes into consideration a imperfect testing validation, and uses the Rogan-Gladen estimator to model the observed prevalence as an apparent prevalence.

See also

Estimating SARS-CoV-2 seroprevalence and epidemiological parameters with uncertainty from serological surveys

This is mostly based on the work Larremore et al. [LFB+20].

Bayesian modelling for COVID-19 seroprevalence studies

This is a talk that uses the same models implemented in Episuite.

Parameters

• x_se – sensitivity parameter (i.e. if there was 33 positive samples, and 27 were detected, this parameter is 27).

• n_se – sensitivity parameter (i.e. if there was 33 positive samples, and 27 were detected, this parameter is 33).

• x_sp – specificity parameter (i.e. if 172 negative tests, there was 2 false positives, this parameter is 170).

• n_sp – specificity parameter (i.e. if 172 negative tests, there was 2 false positives, this parameter is 172).

• obs_positive – number of observed positive counts

• obs_total – the total of observed samples

• true_p_prior – it can be any numpyro distribution to use as prior for the true prevalence (default to a flat Beta prior)

episuite.prevalence.true_prevalence_model(obs_positive: int, obs_total: int, true_p_prior: numpyro.distributions.distribution.Distribution = <numpyro.distributions.continuous.Beta object>) → Any

This is a true prevalence model, which means that it will assume for instance perfect testing validation results if it is a seroprevalence study.

Parameters

• obs_positive – number of observed positive counts

• obs_total – the total of observed samples

• true_p_prior – it can be any numpyro distribution to use as prior for the true prevalence (default to a flat Beta prior)

episuite.mobility – Mobility data

episuite.mobility.facebook – Facebook Mobility data

class episuite.mobility.facebook.FacebookMovementRange

Bases: object

This is a client API for Facebook Movement Range data.

See also

Please look at HDX Movement Range Maps for more information about this data.

MAIN_RESOURCE_URL = 'https://data.humdata.org/dataset/movement-range-maps'

load_movement_range(country_code: Optional[str] = None, show_progress: bool = True) → pandas.core.frame.DataFrame

This method will load the movement range data and optionally filter for the specified country code.

Parameters

• country_code – country code (i.e. ‘BRA’ for Brazil)

• show_progress – show download progress

Returns

a DataFrame with the movement range dataset

class episuite.mobility.facebook.FacebookSymptomSurvey(base_url: str = 'https://covidmap.umd.edu/api')

Bases: object

This is a class implementing a client for the COVID-19 World Survey Data API from Facebook and the University of Maryland.

See also

Please see Fan et al. [FLS+20] for more information about the COVID-19 World Survey Data API.

get_survey_country_region() → pandas.core.frame.DataFrame

Get the survey country/region list.

get_survey_date_avail(country_name: str, region_name: str) → pandas.core.frame.DataFrame

Retrieve all dates for survey responses for a place.

Parameters

• country_name – the name of the country

• region_name – name of the region.

get_survey_range(country_name: str, region_name: str, start_date: str, end_date: str, type_: str = 'daily', indicator: str = 'covid') → pandas.core.frame.DataFrame

Retrieve data for a particular indicator. This method will return a DataFrame with pre-computed confidence intervals (percent_cli_95_upper_ci/percent_cli_95_lower_ci).

See also

Please see Fan et al. [FLS+20] for more information about the COVID-19 World Survey Data API.

Parameters

• country_name – the name of the country

• region_name – name of the region.

• start_date – start date in the format (YYYYMMDD), example: 20200921.

• end_date – start date in the format (YYYYMMDD), example: 20200921.

• type – can be “daily” or “smoothed”

• indicator – can be “covid”, “mask” or “vaccine_acpt”

static plot_region_percent_cli(df_survey_range: pandas.core.frame.DataFrame, locator: str = 'month', interval: int = 1) → Any

Plot the CLI (Covid-like illness) from the results of a region.

Parameters

• df_survey_range – the results from the survey

• locator – can be “month” or “day”, to define the location of ticks in the plot for the dates

• interval – interval to show the date labels in the plot

class episuite.mobility.facebook.MovementRangeResource(date, url, filename)

Bases: tuple

date: datetime.date

Alias for field number 0

filename: str

Alias for field number 2

url: str

Alias for field number 1

Mobility: Google COVID-19 Community Mobility Reports Bibliography