covsirphy.dynamics package

Submodules

covsirphy.dynamics.dynamics module

class Dynamics(model, date_range, tau=None, name=None)[source]

Bases: Term

Class to hand phase-dependent SIR-derived ODE models.

Parameters:

model (ODEModel) – definition of ODE model
date_range (tuple[str | None, str | None]) – start date and end date of dynamics to analyze
tau (int | None) – tau value [min] or None (set later with data)
name (str | None) – name of dynamics to show in figures (e.g. “baseline”) or None (un-set)

detect(algo='Binseg-normal', min_size=7, display=True, **kwargs)[source]

Perform S-R trend analysis to find change points of log10(S) - R of model-specific variables, not that segmentation requires .segment() method.

Parameters:

algo (str) – detection algorithms and models
min_size (int) – minimum value of phase length [days], be equal to or over 3
display (bool) – whether display figure of log10(S) - R plane or not
**kwargs – keyword arguments of algorithm classes (ruptures.Pelt, .Binseg, BottomUp) except for “model”, covsirphy.VisualizeBase(), matplotlib.legend.Legend()

Raises:

NotEnoughDataError – we have not enough records, the length of the records must be equal to or over min_size * 2

Return type:

tuple[Timestamp, DataFrame]

Returns:

- pandas.Timestamp – date of change points - pandas.Dataframe:

Index
R (int): actual R (R of the ODE model) values

Columns
Actual (float): actual log10(S) (common logarithm of S of the ODE model) values Fitted (float): log10(S) values fitted with y = a * R + b 0th (float): log10(S) values fitted with y = a * R + b and 0th phase data 1st, 2nd… (float): fitted values of 1st, 2nd phases

Note

Python library ruptures will be used for off-line change point detection.
Refer to documentation of ruptures library, https://centre-borelli.github.io/ruptures-docs/
Candidates of @algo are “Pelt-rbf”, “Binseg-rbf”, “Binseg-normal”, “BottomUp-rbf”, “BottomUp-normal”.

Note

S-R trend analysis is original to Covsirphy, https://www.kaggle.com/code/lisphilar/covid-19-data-with-sir-model/notebook
“Phase” means a sequential dates in which the parameters of SIR-derived models are fixed.
“Change points” means the dates when trend was changed.
“Change points” is the same as the start dates of phases except for the 0th phase.

estimate(**kwargs)[source]

Run covsirphy.Dynamics.estimate_tau() and covsirphy.Dynamics.estimate_params().

Parameters:: **kwargs – keyword arguments of covsirphy.Dynamics.estimate_tau() and covsirphy.Dynamics.estimate_params()
Return type:: Self
Returns:: Updated Dynamics object with estimated ODE parameter values.

estimate_params(metric='RMSLE', digits=None, n_jobs=None, **kwargs)[source]

Set ODE parameter values optimized for the registered data with hyperparameter optimization using Optuna.

Parameters:

metric (str) – metric name for scoring when optimizing ODE parameter values of phases
digits (int | None) – effective digits of ODE parameter values or None (skip rounding)
n_jobs (int | None) – the number of parallel jobs or None (CPU count)
**kwargs – keyword arguments of optimization, refer to covsirphy.ODEModel.from_data_with_optimization()

Raises:

UnExpectedNoneError – tau value is un-set
NotEnoughDataError – less than three non-NA records are registered

Return type:

DataFrame

Returns:

Index: Date (pandas.Timestamp): dates
Columns: (numpy.float64): ODE parameter values defined with model.PARAMETERS {metric}: score with the estimated parameter values Trials (int): the number of trials Runtime (str): runtime of optimization, like 0 min 10 sec

estimate_tau(metric='RMSLE', q=0.5, digits=None, n_jobs=None)[source]

Set the best tau value for the registered data, estimating ODE parameters with quantiles.

Parameters:

metric (str) – metric name for scoring when selecting best tau value
q (float) – the quantiles to compute, values between (0, 1)
digits (int | None) – effective digits of ODE parameter values or None (skip rounding)
n_jobs (int | None) – the number of parallel jobs or None (CPU count)

Raises:

NotEnoughDataError – less than three non-NA records are registered

Return type:

tuple[float, DataFrame]

Returns:

- float – tau value with best metric score - pandas.DataFrame: metric scores of tau candidates

Index
tau (int): candidate of tau values

Columns
{metric}: score of estimation with metric

evaluate(date_range=None, metric='RMSLE', display=True, **kwargs)[source]

Compare the simulated results and actual records, and evaluate the differences.

Parameters:

date_range (tuple[str | Timestamp | None, str | Timestamp | None] | None) – range of dates to evaluate or None (the first and the last date)
metric (str) – metric to evaluate the difference
display (bool) – whether display figure of comparison or not
kwargs – keyword arguments of covsirphy.compare_plot()

Return type:

float

Returns:

evaluation score

classmethod from_data(model, data, tau=1440, name=None)[source]

Initialize model with data.

Parameters:

data (DataFrame) –
new data to overwrite the current information Index

Date (pandas.Timestamp): Observation dates

Columns
Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Fatal (int): the number of fatal cases Recovered (int): the number of recovered cases (numpy.float64): ODE parameter values defined with the ODE model (optional)
tau (int | None) – tau value [min] or None (un-set)
name (str | None) – name of dynamics to show in figures (e.g. “baseline”) or None (un-set)

Return type:

Self

Returns:

initialized model

Note

Regarding @date_range, refer to covsirphy.ODEModel.from_sample().

classmethod from_sample(model, date_range=None, tau=1440)[source]

Initialize model with sample data of one-phase ODE model.

Parameters:

model (ODEModel) – definition of ODE model
date_range (tuple[str | None, str | None] | None) – start date and end date of simulation
[min] (tau value)

Return type:

Self

Returns:

initialized model

Note

Regarding @date_range, refer to covsirphy.ODEModel.from_sample().

property model: ODEModel: Return model class.

property model_name: str: Return name of ODE model.

property name: str | None: Return name of dynamics to show in figures (e.g. “baseline”) or None (un-set).

parse_days(days, ref='last')[source]

Return min(ref, ref + days) and max(ref, ref + days).

Parameters:

days (int) – the number of days
ref (Timestamp | str | None) – reference date or “first” (the first date of records) or “last”/None (the last date)

Return type:

tuple[Timestamp, Timestamp]

Returns:

minimum date and maximum date of the selected dates

Note

Note that the days clipped with the first and the last dates of records.

parse_phases(phases=None)[source]

Return minimum date and maximum date of the phases.

Parameters:: phases (list[str] | None) – phases (0th, 1st, 2nd,… last) or None (all phases)
Return type:: tuple[Timestamp, Timestamp]
Returns:: minimum date and maximum date of the phases

Note

“last” can be used to specify the last phase.

register(data=None)[source]

Register data to get initial values and ODE parameter values (if available).

Parameters:

data (DataFrame | None) –

new data to overwrite the current information or None (no new records) Index

Date (pandas.Timestamp): Observation dates

Columns: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases (numpy.float64): ODE parameter values defined with the model

Return type:

DataFrame

Returns:

dataframe of the current information –

Index: Date (pandas.Timestamp): Observation dates
Columns: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases (numpy.float64): ODE parameter values defined with model.PARAMETERS

Note

Change points of ODE parameter values will be recognized as the change points of phases.

Note

NA can used in the newer phases because filled with that of the older phases.

segment(points=None, overwrite=False, **kwargs)[source]

Perform time-series segmentation with points manually selected or found with S-R trend analysis.

Parameters:

points (list[str] | None) – dates of change points or None (will be found with S-R trend analysis via .detect() method)
overwrite (bool) – whether remove all phases before segmentation or not
**kwargs – keyword arguments of covsirphy.Dynamics.detect()

Return type:

Self

Returns:

Updated Dynamics object

Note

@points can include the first date, but not required.

Note

@points must be selected from the first date to three days before the last date specified covsirphy.Dynamics(date_range).

simulate(model_specific=False)[source]

Perform simulation with phase-dependent ODE model.

Parameters:

model_specific (bool) – whether convert S, I, F, R to model-specific variables or not

Raises:

UnExpectedNoneError – tau value is un-set
NAFoundError – ODE parameter values on the start dates of phases are un-set

Return type:

DataFrame

Returns:

dataframe of time-series simulated data.

Index: Date (pd.Timestamp): dates
Columns: if @model_specific is False: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases if @model_specific is True, variables defined by model.VARIABLES of covsirphy.Dynamics(model)

start_dates()[source]

Return the start dates of phases.

Return type:: list[str]
Returns:: start dates

summary()[source]

Summarize phase information.

Return type:

DataFrame

Returns:

Summarized information.

Index: Phase (str): phase names, 0th, 1st,…
Columns: Start (pandas.Timestamp): start date of the phase End (pandas.Timestamp): end date of the phase Rt (float): phase-dependent reproduction number (if parameters are available) (float): parameter values, including rho (if available) (int or float): dimensional parameters, including 1/beta [days] (if tau and parameters are available)

property tau: int | None: Return tau value [min] or None (un-set).

track()[source]

Track reproduction number, parameter value and dimensional parameter values.

Return type:

DataFrame

Returns:

Dataframe of time-series data of the values.

Index: Date (pandas.Timestamp): dates
Columns: Rt (float): phase-dependent reproduction number (if parameters are available) (float): parameter values, including rho (if available) (int or float): dimensional parameters, including 1/beta [days] (if tau and parameters are available)

covsirphy.dynamics.ode module

class ODEModel(date_range, tau, initial_dict, param_dict)[source]

Bases: Term

Basic class of ordinary differential equation (ODE) model.

Parameters:

date_range (tuple[str, str]) – start date and end date of simulation
tau (int) – tau value [min]
initial_dict (dict[str, int]) – initial values
param_dict (dict[str, float]) – non-dimensional parameter values

classmethod definitions()[source]

Return definitions of ODE model.

Return type:: dict[str, Any]
Returns:: - “name” (str) – ODE model name - “variables” (list of [str]): variable names - “parameters” (list of [str]): non-dimensional parameter names - “dimensional_parameters” (list of [str]): dimensional parameter names

dimensional_parameters()[source]

Calculate dimensional parameter values.

Return type:: NoReturn
Returns:: dictionary of dimensional parameter values

Note

This method must be defined by child classes.

classmethod from_data(data, param_dict, tau=1440, digits=None)[source]

Initialize model with data and ODE parameter values.

Parameters:

data (DataFrame) –
Index
reset index

Columns
- Date (pd.Timestamp): Observation date
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Recovered (int): the number of recovered cases
- Fatal (int): the number of fatal cases
param_dict (dict[str, float]) – non-dimensional parameter values
tau (int) – tau value [min]
digits (int | None) – effective digits of ODE parameter values or None (skip rounding)

Return type:

Self

Returns:

initialized model

classmethod from_data_with_optimization(data, tau=1440, metric='RMSLE', digits=None, **kwargs)[source]

Initialize model with data, estimating ODE parameters hyperparameter optimization using Optuna.

Parameters:

data (DataFrame) –
Index
reset index

Columns
- Date (pd.Timestamp): Observation date
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Fatal (int): the number of fatal cases
- Recovered (int): the number of recovered cases
tau (int) – tau value [min]
metric (str) – metric to minimize, refer to covsirphy.Evaluator.score()
digits (int | None) – effective digits of ODE parameter values or None (skip rounding)
**kwargs – keyword arguments of optimization - quantiles (tuple(int, int)): quantiles to cut parameter range, like confidence interval, (0.1, 0.9) as default - timeout (int): timeout of optimization, 180 as default - timeout_iteration (int): timeout of one iteration, 1 as default - tail_n (int): the number of iterations to decide whether score did not change for the last iterations, 4 as default - allowance (tuple(float, float)): the allowance of the max predicted values, (0.99, 1.01) as default - pruner (str): kind of pruner (hyperband, median, threshold or percentile), “threshold” as default - upper (float): works for “threshold” pruner, intermediate score is larger than this value, it prunes, 0.5 as default - percentile (float): works for “Percentile” pruner, the best intermediate value is in the bottom percentile among trials, it prunes, 50 as default - constant_liar (bool): whether use constant liar to reduce search effort or not, False as default

Return type:

Self

Returns:

initialized model

classmethod from_data_with_quantile(data, tau=1440, q=0.5, digits=None)[source]

Initialize model with data, estimating ODE parameters with quantiles.

Parameters:

data (DataFrame) –
Index
reset index

Columns
- Date (pd.Timestamp): Observation date
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Recovered (int): the number of recovered cases
- Fatal (int): the number of fatal cases
tau (int) – tau value [min]
q (float) – the quantiles to compute, values between (0, 1)
digits (int | None) – effective digits of ODE parameter values or None (skip rounding)

Return type:

Self

Returns:

initialized model

classmethod from_sample(date_range=None, tau=1440)[source]

Initialize model with sample data.

Parameters:

date_range (tuple[str | None, str | None] | None) – start date and end date of simulation
tau (int) – tau value [min]

Return type:

Self

Returns:

initialized model

Note

When @date_range or the first value of @date_range is None, today when executed will be set as start date.
When @date_range or the second value of @date_range is None, 180 days after start date will be used as end date.

classmethod inverse_transform(data, tau=None, start_date=None)[source]

Transform a dataframe, converting model-specific variables to Susceptible/Infected/Fatal/Recovered.

Parameters:

data (DataFrame) –

Index
any index

Columns
model-specific variables
tau (int | None) – tau value [min]
start_date (str | Timestamp | None) – start date of records ie. TIME(0)

Return type:

NoReturn

Returns:

Index

Date (pandas.DatetimeIndex) or as-is @data (when either @tau or @start_date are None)

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of currently infected cases
Fatal (int): the number of fatal cases
Recovered (int): the number of recovered cases

Note

This method must be defined by child classes.

classmethod name()[source]

Return name of ODE model.

Return type:: str

r0()[source]

Calculate basic reproduction number.

Return type:: NoReturn
Returns:: reproduction number of the ODE model and parameters

Note

This method must be defined by child classes.

settings(with_estimation=False)[source]

Return settings.

Parameters:

with_estimation (bool) – whether includes information regarding ODE parameter estimation or not

Return type:

dict[str, Any]

Returns:

- date_range (tuple of (str, str)) – start date and end date of simulation - tau (int): tau value [min] - initial_dict (dict of {str: int}): initial values - param_dict (dict of {str: float}): non-dimensional parameter values - estimation_dict (dict of {str: str or int}: information regarding ODE parameter estimation, when @with_estimation is True

method (str): method of estimation, “with_quantile” or “with_optimization” or “not_performed”

{metric} (int): score of hyperparameter optimization, if available

Trials (int) : the number of trials of hyperparameter optimization, if available

Runtime (str): runtime of hyperparameter optimization, if available

keyword arguments set with covsirphy.ODEModel.with_optimization(), if available

keyword arguments set with covsirphy.ODEModel.with_quantile(), if available

solve()[source]

Solve an initial value problem.

Return type:

DataFrame

Returns:

dataframe of analytical solutions.

Index: Date (pandas.Timestamp): dates from start date to end date
Columns: (pandas.Int64): model-specific dimensional variables of the model

classmethod sr(data)[source]

Return log10(S) and R of model-specific variables for S-R trend analysis.

Parameters:

data (DataFrame) –

Index: Date (pd.Timestamp): Observation date
Columns: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases

Return type:

NoReturn

Returns:

Index: Date (pandas.Timestamp): date
Columns: log10(S) (np.float64): common logarithm of S of the ODE model R (np.int64): R of the model

Note

This method must be defined by child classes.

classmethod transform(data, tau=None)[source]

Transform a dataframe, converting Susceptible/Infected/Fatal/Recovered to model-specific variables.

Parameters:

data (DataFrame) –
Index
reset index or pandas.DatetimeIndex (when tau is not None)

Columns
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Fatal (int): the number of fatal cases
- Recovered (int): the number of recovered cases
tau (int | None) – tau value [min]

Return type:

NoReturn

Returns:

Index: as the same as index of @data when @tau is None else converted to time(x) = (TIME(x) - TIME(0)) / tau
Columns: model-specific variables

Note

This method must be defined by child classes.

covsirphy.dynamics.sewirf module

class SEWIRFModel(date_range, tau, initial_dict, param_dict)[source]

Bases: ODEModel

Class of SEWIR-F model.

Parameters:

date_range (tuple[str, str]) – start date and end date of simulation
tau (int) – tau value [min]
initial_dict (dict[str, int]) –
initial values
- Susceptible (int): the number of susceptible cases
- Exposed (int): the number of cases who are exposed and in latent period without infectivity
- Waiting (int): the number of cases who are waiting for confirmation diagnosis with infectivity
- Infected (int): the number of infected cases
- Fatal (int): the number of fatal cases
- Recovered (int): the number of recovered cases
param_dict (dict[str, float]) –
non-dimensional parameter values
- theta: direct fatality probability of un-categorized confirmed cases
- kappa: non-dimensional mortality rate
- rho1: non-dimensional exposure rate (the number of encounter with the virus in a minute)
- rho2: non-dimensional inverse value of latent period
- rho3: non-dimensional inverse value of waiting time for confirmation
- sigma: non-dimensional recovery rate

dimensional_parameters()[source]

Calculate dimensional parameter values.

Raises:

ZeroDivisionError – either kappa or rho_i for i=1,2,3 or sigma value was over 0

Return type:

dict[str, float | int]

Returns:

dictionary of dimensional parameter values

”alpha1 [-]” (float): direct fatality probability of un-categorized confirmed cases
”1/alpha2 [day]” (int): mortality period of infected cases
”1/beta1 [day]” (int): period for susceptible people to encounter with the virus
”1/beta2 [day]” (int): latent period
”1/beta3 [day]” (int): waiting time for confirmation
”1/gamma [day]” (int): recovery period

classmethod from_data_with_optimization(*args, **kwargs)[source]

Initialize model with data, estimating ODE parameters hyperparameter optimization using Optuna.

Raises:: NotImplementedError – this model cannot be used for parameter estimation because Exposed/Waiting data is un-available
Return type:: NoReturn

classmethod from_data_with_quantile(*args, **kwargs)[source]

Initialize model with data, estimating ODE parameters with quantiles.

Raises:: NotImplementedError – this model cannot be used for parameter estimation because Exposed/Waiting data is un-available
Return type:: NoReturn

classmethod inverse_transform(data, tau=None, start_date=None)[source]

Transform a dataframe, converting model-specific variables to Susceptible/Infected/Fatal/Recovered.

Parameters:

data (DataFrame) –
Index
any index

Columns
- Susceptible (int): the number of susceptible cases
- Exposed (int): the number of cases who are exposed and in latent period without infectivity
- Waiting (int): the number of cases who are waiting for confirmation diagnosis with infectivity
- Infected (int): the number of infected cases
- Recovered (int): the number of recovered cases
- Fatal (int): the number of fatal cases
tau (int | None) – tau value [min]
start_date (str | Timestamp | None) – start date of records ie. TIME(0)

Return type:

DataFrame

Returns:

Index

Date (pandas.DatetimeIndex) or as-is @data (when either @tau or @start_date are None the index @data is date)

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of currently infected cases
Recovered (int): the number of recovered cases
Fatal (int): the number of fatal cases

r0()[source]

Calculate basic reproduction number.

Raises:: ZeroDivisionError – rho2 or sigma + kappa value was over 0
Return type:: float
Returns:: reproduction number of the ODE model and parameters

classmethod sr(data)[source]

Return log10(S) and R of model-specific variables for S-R trend analysis.

Parameters:

data (DataFrame) –

Index

Date (pd.Timestamp): Observation date

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of currently infected cases
Recovered (int): the number of recovered cases
Fatal (int): the number of fatal cases

Return type:

DataFrame

Returns:

Index: Date (pandas.Timestamp): date
Columns: log10(S) (np.float64): common logarithm of Susceptible R (np.int64): Recovered

classmethod transform(data, tau=None)[source]

Transform a dataframe, converting Susceptible/Infected/Fatal/Recovered to model-specific variables.

Parameters:

data (DataFrame) –
Index
reset index or pandas.DatetimeIndex (when tau is not None)

Columns
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Fatal (int): the number of fatal cases
- Recovered (int): the number of recovered cases
tau (int | None) – tau value [min]

Return type:

DataFrame

Returns:

Index

as the same as index if @data when @tau is None else converted to time(x) = (TIME(x) - TIME(0)) / tau

Columns

Susceptible (int): the number of susceptible cases
Exposed (int): the number of cases who are exposed and in latent period without infectivity
Waiting (int): the number of cases who are waiting for confirmation diagnosis with infectivity
Infected (int): the number of infected cases
Recovered (int): the number of recovered cases
Fatal (int): the number of fatal cases

covsirphy.dynamics.sir module

class SIRModel(date_range, tau, initial_dict, param_dict)[source]

Bases: ODEModel

Class of SIR model.

Parameters:

date_range (tuple[str, str]) – start date and end date of simulation
tau (int) – tau value [min]
initial_dict (dict[str, int]) –
initial values
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of infected cases
- Fatal or Recovered (int): the number of fatal or recovered cases
param_dict (dict[str, float]) –
non-dimensional parameter values
- rho: non-dimensional effective contact rate
- sigma: non-dimensional recovery plus mortality rate

dimensional_parameters()[source]

Calculate dimensional parameter values.

Raises:

ZeroDivisionError – either rho or sigma value was over 0

Return type:

dict[str, int]

Returns:

dictionary of dimensional parameter values

”1/beta [day]” (int): infection period
”1/gamma [day]” (int): recovery period

classmethod inverse_transform(data, tau=None, start_date=None)[source]

Transform a dataframe, converting model-specific variables to Susceptible/Infected/Fatal/Recovered.

Parameters:

data (DataFrame) –
Index
any index

Columns
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of infected cases
- Fatal or Recovered (int): the number of fatal or recovered cases
tau (int | None) – tau value [min]
start_date (str | Timestamp | None) – start date of records ie. TIME(0)

Return type:

DataFrame

Returns:

Index

Date (pandas.DatetimeIndex) or as-is @data (when either @tau or @start_date are None the index @data is date)

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of currently infected cases
Recovered (int): the number of recovered cases
Fatal (int): the number of fatal cases

r0()[source]

Calculate basic reproduction number.

Raises:: ZeroDivisionError – Sigma value was over 0
Return type:: float
Returns:: reproduction number of the ODE model and parameters

classmethod sr(data)[source]

Return log10(S) and R of model-specific variables for S-R trend analysis.

Parameters:

data (DataFrame) –

Index: Date (pd.Timestamp): Observation date
Columns: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases

Return type:

DataFrame

Returns:

Index: Date (pandas.Timestamp): date
Columns: log10(S) (np.float64): common logarithm of Susceptible R (np.int64): Fatal or Recovered

classmethod transform(data, tau=None)[source]

Transform a dataframe, converting Susceptible/Infected/Fatal/Recovered to model-specific variables.

Parameters:

data (DataFrame) –
Index
reset index or pandas.DatetimeIndex (when tau is not None)

Columns
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Recovered (int): the number of recovered cases
- Fatal (int): the number of fatal cases
tau (int | None) – tau value [min]

Return type:

DataFrame

Returns:

Index

as the same as index if @data when @tau is None else converted to time(x) = (TIME(x) - TIME(0)) / tau

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of infected cases
Fatal or Recovered (int): the number of fatal or recovered cases

covsirphy.dynamics.sird module

class SIRDModel(date_range, tau, initial_dict, param_dict)[source]

Bases: ODEModel

Class of SIR-D model.

Parameters:

date_range (tuple[str, str]) – start date and end date of simulation
tau (int) – tau value [min]
initial_dict (dict[str, int]) –
initial values
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of infected cases
- Fatal (int): the number of fatal cases
- Recovered (int): the number of recovered cases
param_dict (dict[str, float]) –
non-dimensional parameter values
- kappa: non-dimensional mortality rate
- rho: non-dimensional effective contact rate
- sigma: non-dimensional recovery rate

dimensional_parameters()[source]

Calculate dimensional parameter values.

Raises:

ZeroDivisionError – either kappa or rho or sigma value was over 0

Return type:

dict[str, int]

Returns:

dict of {str –

int}: dictionary of dimensional parameter values

”1/alpha2 [day]” (int): mortality period
”1/beta [day]” (int): infection period
”1/gamma [day]” (int): recovery period

classmethod inverse_transform(data, tau=None, start_date=None)[source]

Transform a dataframe, converting model-specific variables to Susceptible/Infected/Fatal/Recovered.

Parameters:

data (DataFrame) –
Index
any index

Columns
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of infected cases
- Recovered (int): the number of recovered cases
- Fatal (int): the number of fatal cases
tau (int | None) – tau value [min]
start_date (str | Timestamp | None) – start date of records ie. TIME(0)

Return type:

DataFrame

Returns:

Index

Date (pandas.DatetimeIndex) or as-is @data (when either @tau or @start_date are None the index @data is date)

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of currently infected cases
Recovered (int): the number of recovered cases
Fatal (int): the number of fatal cases

r0()[source]

Calculate basic reproduction number.

Raises:: ZeroDivisionError – sigma + kappa value was over 0
Return type:: float
Returns:: float – reproduction number of the ODE model and parameters

classmethod sr(data)[source]

Return log10(S) and R of model-specific variables for S-R trend analysis.

Parameters:

data (DataFrame) –

Index: Date (pd.Timestamp): Observation date
Columns: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases

Return type:

DataFrame

Returns:

Index: Date (pandas.Timestamp): date
Columns: log10(S) (np.float64): common logarithm of Susceptible R (np.int64): Recovered

classmethod transform(data, tau=None)[source]

Transform a dataframe, converting Susceptible/Infected/Fatal/Recovered to model-specific variables.

Parameters:

data (DataFrame) –
Index
reset index or pandas.DatetimeIndex (when tau is not None)

Columns
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of currently infected cases
- Recovered (int): the number of recovered cases
- Fatal (int): the number of fatal cases
tau (int or None) – tau value [min]

Return type:

DataFrame

Returns:

Index

as the same as index if @data when @tau is None else converted to time(x) = (TIME(x) - TIME(0)) / tau

Columns

Susceptible (int): the number of susceptible cases
Infected (int): the number of infected cases
Fatal (int): the number of fatal cases
Recovered (int): the number of recovered cases

covsirphy.dynamics.sirf module

class SIRFModel(date_range, tau, initial_dict, param_dict)[source]

Bases: SIRDModel

Class of SIR-F model.

Parameters:

date_range (tuple[str, str]) – start date and end date of simulation
tau (int) – tau value [min]
initial_dict (dict[str, int]) –
initial values
- Susceptible (int): the number of susceptible cases
- Infected (int): the number of infected cases
- Fatal (int): the number of fatal cases
- Recovered (int): the number of recovered cases
param_dict (dict[str, float]) –
non-dimensional parameter values
- theta: direct fatality probability of un-categorized confirmed cases
- kappa: non-dimensional mortality rate of infected cases
- rho: non-dimensional effective contact rate
- sigma: non-dimensional recovery rate

Note

SIR-F model is original to Covsirphy, https://www.kaggle.com/code/lisphilar/covid-19-data-with-sir-model/notebook

dimensional_parameters()[source]

Calculate dimensional parameter values.

Raises:

ZeroDivisionError – either kappa or rho or sigma value was over 0

Return type:

dict[str, float | int]

Returns:

dictionary of dimensional parameter values

”alpha1 [-]” (float): direct fatality probability of un-categorized confirmed cases
”1/alpha2 [day]” (int): mortality period of infected cases
”1/beta [day]” (int): infection period
”1/gamma [day]” (int): recovery period

r0()[source]

Calculate basic reproduction number.

Raises:: ZeroDivisionError – sigma + kappa value was over 0
Return type:: float
Returns:: reproduction number of the ODE model and parameters

classmethod sr(data)[source]

Return log10(S) and R of model-specific variables for S-R trend analysis.

Parameters:

data (DataFrame) –

Index: Date (pd.Timestamp): Observation date
Columns: Susceptible (int): the number of susceptible cases Infected (int): the number of currently infected cases Recovered (int): the number of recovered cases Fatal (int): the number of fatal cases

Return type:

DataFrame

Returns:

Index: Date (pandas.Timestamp): date
Columns: log10(S) (np.float64): common logarithm of Susceptible R (np.int64): Recovered