covsirphy.util package

covsirphy.util.alias module

class Alias(target_class=None)[source]

Bases: Term

Remember and parse aliases, just like defaultdict.

Parameters:

target_class (Any) – class of targets or None (all objects)

all()[source]

List up all targets of aliases.

Return type:

dict[str, Any]

Returns:

all aliases

delete(name)[source]

Delete alias.

Parameters:

name (str) – alias name

Raises:

KeyError – the alias has not been registered as an alias

Return type:

Self

Returns:

updated Alias instance

find(name, default=None)[source]

Find the target of the alias.

Parameters:
  • name (str) – alias name

  • default (Any) – default value when not found

Return type:

Any

Returns:

the target or default value

classmethod for_variables()[source]

Initialize covsirphy.Alias with preset of variable aliases.

Return type:

Self

update(name, target)[source]

Update target of the alias.

Parameters:
  • name (str) – alias name

  • targets – target to link with the name

Return type:

Self

Returns:

updated Alias instance

covsirphy.util.config module

covsirphy.util.error module

exception EmptyError(name, details=None)[source]

Bases: _ValidationError

Error when the dataframe is empty un-expectedly.

Parameters:
  • name (str) – name of the target

  • details (str or None) – details of error

exception ExperimentalWarning[source]

Bases: Warning

Class to explain the method/function is experimental and its name, features and arguments may changed later.

exception NAFoundError(name, value=None, details=None)[source]

Bases: _ValidationError

Error when NA values are included un-expectedly.

Parameters:
  • name (str) – name of the target

  • value (str or None) – value of the target

  • details (str or None) – details of error

exception NotEnoughDataError(name, value, required_n, details=None)[source]

Bases: _ValidationError

Error when we do not have enough data for analysis.

Parameters:
  • name (str) – name of the target

  • value (str) – value of the target

  • required_n (int) – required number of records

  • details (str or None) – details of error

exception NotIncludedError(key_name, container_name, details=None)[source]

Bases: _ValidationError

Error when a necessary key was not included in a container.

Parameters:
  • key_name (str) – key name

  • container_name (str) – name of the container

  • details (str or None) – details of error

exception NotNoneError(name, value, details=None)[source]

Bases: _ValidationError

Error when a value must be None but not None un-expectedly.

Parameters:
  • name (str) – name of the target

  • value (str) – value of the target

  • details (str or None) – details of error

exception NotRegisteredError(name, details=None)[source]

Bases: UnExecutedError

Error when no records have been registered yet.

exception NotSubclassError(name, target, parent, details=None)[source]

Bases: _ValidationError

Error when an object is not a subclass of the parent class un-expectedly.

Parameters:
  • name (str) – name of the target

  • target (object) – target object

  • parent (object) – expected parent class

  • details (str or None) – details of error

exception ScenarioNotFoundError(name, details=None)[source]

Bases: _BaseException

Error when unregistered scenario name was specified.

Parameters:
  • name (str) – scenario name

  • details (str or None) – details of error

exception SubsetNotFoundError(geo=None, country=None, country_alias=None, province=None, start_date=None, end_date=None, date=None, details=None)[source]

Bases: _BaseException

Error when subset was failed with specified arguments.

Parameters:
  • geo (tuple(list[str] or tuple(str) or str) or str or None) – location names to filter or None

  • country (str) – country name

  • country_alias (str or None) – country name used in the dataset

  • province (str or None) – province name

  • start_date (str or None) – start date, like 22Jan2020

  • end_date (str or None) – end date, like 01Feb2020

  • date (str or None) – specified date, like 22Jan2020

  • details (str or None) – details of error

exception UnExecutedError(name, details=None)[source]

Bases: _BaseException

Error when we have unexecuted methods that we need to run in advance.

Parameters:
  • name (str) – method name to run in advance

  • details (str or None) – details of error

exception UnExpectedLengthError(name, value, length, details=None)[source]

Bases: _ValidationError

Error when a sequence has un-expended length.

Parameters:
  • name (str) – argument name

  • value (object) – value user applied

  • length (int) – length of the sequence

  • details (str or None) – details of error

exception UnExpectedNoneError(name, details=None)[source]

Bases: _ValidationError

Error when a value is None un-expectedly.

Parameters:
  • name (str) – name of the target

  • details (str or None) – details of error

exception UnExpectedTypeError(name, target, expected, details=None)[source]

Bases: _ValidationError

Error when an object cannot be converted to an instance un-expectedly.

Parameters:
  • name (str) – name of the target

  • target (object) – target object

  • expected (object) – expected type

  • details (str or None) – details of error

exception UnExpectedValueError(name, value, candidates, details=None)[source]

Bases: _ValidationError

Error when unexpected value was applied as the value of an argument.

Parameters:
  • name (str) – argument name

  • value (object) – value user applied

  • candidates (list[object]) – candidates of the argument

  • details (str or None) – details of error

exception UnExpectedValueRangeError(name, target, value_range, details=None)[source]

Bases: _ValidationError

Error when the value is out of value range.

Parameters:
  • name (str) – name of the target

  • target (object) – target object

  • value_range (tuple(int or None, int or None)) – value range, None means un-specified

  • details (str or None) – details of error

deprecate(old, new=None, version=None, ref=None)[source]

Decorator to raise deprecation warning.

Parameters:
  • old (str) – description of the old method/function

  • new (str or None) – description of the new method/function

  • version (str or None) – version number, like 2.7.3-alpha

  • ref (str or None) – reference URL of the new method/function

experimental(name, version)[source]

Decorator to raise ExperimentalWarning because the method/function is experimental.

Parameters:
  • name (str) – description of the method/function

  • version (str) – version number, like 2.7.3-alpha

covsirphy.util.evaluator module

class Evaluator(y_true, y_pred, how='inner', on=None)[source]

Bases: object

Evaluate residual errors.

Parameters:
Raises:

NAFoundError – either @y_true or @pred has NA values

classmethod best_one(candidate_dict, **kwargs)[source]

Select the best one with scores.

Parameters:
  • candidate_dict (dict[object, float]) – scores of candidates

  • kwargs – keyword arguments of Evaluator.smaller_is_better()

Returns:

tuple(object, float) – the best one and its score

classmethod metrics()[source]

Return the list of metric names.

Returns:

list[str] – list of metric names

score(metric='RMSLE')[source]

Calculate score with specified metric.

Parameters:

metric (str) – ME, MAE, MSE, MSLE, MAPE, RMSE, RMSLE, R2

Raises:
Returns:

float – score with the metric

Note

ME: maximum residual error MAE: mean absolute error MSE: mean square error MSLE: mean squared logarithmic error MAPE: mean absolute percentage error RMSE: root mean squared error RMSLE: root mean squared logarithmic error R2: the coefficient of determination

classmethod smaller_is_better(metric='RMSLE')[source]

Whether smaller value of the metric is better or not.

Parameters:

metric (str) – ME, MAE, MSE, MSLE, MAPE, RMSE, RMSLE, R2

Returns:

bool – whether smaller value is better or not

covsirphy.util.filer module

class Filer(directory, prefix=None, suffix=None, numbering=None)[source]

Bases: object

Produce filenames and manage files.

Parameters:
  • directory (list[str] or tuple(str) or str) – top directory name(s)

  • prefix (str or None) – prefix of the filenames or None (no prefix)

  • suffix (str or None) – suffix of the filenames or None (no suffix)

  • numbering (str or None) – “001”, “01”, “1” or None (no numbering)

Examples

>>> import covsirphy as cs
>>> filer = cs.Filer(directory="output", prefix="jpn", suffix=None, numbering="01")
>>> filer.png("records")
{"filename": "<absolute path>/output/jpn_01_records.png"}
>>> filer.jpg("records")
{"filename": "<absolute path>/output/jpn_01_records.jpg"}
>>> filer.json("backup")
{"filename": "<absolute path>/output/jpn_01_backup.json"}
>>> filer.geojson("geometry", "driver": "GeoJson")
{"filename": "<absolute path>/output/jpn_01_geometry.geojson", "driver": "GeoJson"}
>>> filer.csv("records", index=True)
{"path_or_buf": "<absolute path>/output/jpn_01_records.csv", index: True}
csv(title, **kwargs)[source]

Create CSV filename and register it.

Parameters:
  • title (str) – title of the filename, like ‘records’

  • kwargs – keyword arguments to be included in the output

Returns:

dict[str, str] – absolute filename (key: ‘path_or_buf’) and kwargs

files(ext=None)[source]

List-up filenames.

Parameters:

ext (str or None) – file extension or None (all)

Returns:

list[str] – list of files

geojson(title, **kwargs)[source]

Create GeoJSON filename and register it.

Parameters:
  • title (str) – title of the filename, like ‘records’

  • kwargs – keyword arguments to be included in the output

Returns:

dict[str, str] – absolute filename (key: ‘filename’) and kwargs

jpg(title, **kwargs)[source]

Create JPG filename and register it.

Parameters:
  • title (str) – title of the filename, like ‘records’

  • kwargs – keyword arguments to be included in the output

Returns:

dict[str, str] – absolute filename (key: ‘filename’) and kwargs

json(title, **kwargs)[source]

Create JSON filename and register it.

Parameters:
  • title (str) – title of the filename, like ‘records’

  • kwargs – keyword arguments to be included in the output

Returns:

dict[str, str] – absolute filename (key: ‘filename’) and kwargs

png(title, **kwargs)[source]

Create PNG filename and register it.

Parameters:
  • title (str) – title of the filename, like ‘records’

  • kwargs – keyword arguments to be included in the output

Returns:

dict[str, str] – absolute filename (key: ‘filename’) and kwargs

covsirphy.util.stopwatch module

class StopWatch[source]

Bases: object

Calculate elapsed time.

static show(time_sec)[source]

Show the elapsed time as string.

Parameters:

time_sec (int) – time [sec]

Returns:

str – eg. ‘1 min 30 sec’

stop()[source]

Stop.

Returns:

int – elapsed time [sec]

stop_show()[source]

Stop and show time.

Returns:

str – eg. ‘1 min 30 sec’

covsirphy.util.term module

class Term[source]

Bases: object

Term definition.

A = '_actual'
ACTUAL = 'Actual'
AREA_ABBR_COLS = ['ISO3', 'Country', 'Province']
AREA_COLUMNS = ['Country', 'Province']
C = 'Confirmed'
CI = 'Infected'
CITY = 'City'
COLUMNS = ['Date', 'Country', 'Province', 'Confirmed', 'Infected', 'Fatal', 'Recovered']
COUNTRY = 'Country'
DATE = 'Date'
DATE_FORMAT = '%d%b%Y'
DATE_FORMAT_DESC = 'DDMmmYYYY'
DSIFR_COLUMNS = ['Date', 'Susceptible', 'Infected', 'Fatal', 'Recovered']
E = 'Exposed'
END = 'End'
F = 'Fatal'
FIG_COLUMNS = ['Infected', 'Fatal', 'Recovered', 'Fatal or Recovered', 'Vaccinated', 'Exposed', 'Waiting']
FITTED = 'Fitted'
FR = 'Fatal or Recovered'
FUTURE = 'Future'
ID = 'ID'
INITIAL = 'Initial'
ISO3 = 'ISO3'
MAIN = 'Main'
MODERATE = 'Moderate'
MONO_COLUMNS = ['Confirmed', 'Fatal', 'Recovered']
N = 'Population'
NA = '-'
NLOC_COLUMNS = ['Date', 'Confirmed', 'Infected', 'Fatal', 'Recovered']
ODE = 'ODE'
OTHERS = 'Others'
P = '_predicted'
PARAM_DICT = 'param_dict'
PAST = 'Past'
PHASE = 'Phase'
PRODUCT = 'Product'
PROVINCE = 'Province'
R = 'Recovered'
RATE_COLUMNS = ['Fatal per Confirmed', 'Recovered per Confirmed', 'Fatal per (Fatal or Recovered)']
RT = 'Rt'
RT_FULL = 'Reproduction number'
RUNTIME = 'Runtime'
S = 'Susceptible'
SEP = '/'
SERIES = 'Scenario'
SEVERE = 'Severe'
START = 'Start'
STEP_N = 'step_n'
STR_COLUMNS = ['Date', 'Country', 'Province']
SUB_COLUMNS = ['Date', 'Confirmed', 'Infected', 'Fatal', 'Recovered', 'Susceptible']
SUFFIX_DICT = {1: 'st', 2: 'nd', 3: 'rd'}
T = 'Elapsed'
TAU = 'tau'
TENSE = 'Type'
TESTS = 'Tests'
TESTS_DIFF = 'Tests_diff'
TRIALS = 'Trials'
TS = 't'
V = 'Vaccinated'
VAC = 'Vaccinations'
VAC_BOOSTERS = 'Vaccinations_boosters'
VALUE_COLUMNS = ['Confirmed', 'Infected', 'Fatal', 'Recovered']
V_FULL = 'Vaccinated_full'
V_ONCE = 'Vaccinated_once'
W = 'Waiting'
Y0_DICT = 'y0_dict'
classmethod num2str(num)[source]

Convert numbers to 1st, 2nd etc.

Parameters:

num (int) – number

Returns:

str

static str2num(string, name='phase names')[source]

Convert 1st to 1 and so on.

Parameters:
  • string (str) – like 1st, 2nd, 3rd,…

  • name (str) – name of the string

Returns:

int

covsirphy.util.validator module

class Validator(target, name='target', accept_none=True)[source]

Bases: object

Validate objects and arguments.

Parameters:
  • target (object) – target object to validate

  • name (str) – name of the target shown in error code

  • accept_none (str) – whether accept None as the target value or not

Raises:

NAFoundError – @accept_none is False, but @target is None

Note

When @accept_none is True and @target is None, default values will be returned with instance methods.

dataframe(time_index=False, columns=None, empty_ok=True)[source]

Ensure the target is a dataframe.

Parameters:
  • time_index (bool) – if True, the dataframe must has DatetimeIndex

  • columns (list[str] or None) – the columns the dataframe must have

  • empty_ok (bool) – whether give permission to empty dataframe or not

Raises:
Return type:

DataFrame

Returns:

pandas.DataFrame – the target itself

date(value_range=(None, None), default=None)[source]

Convert a value to a date object.

Parameters:
Raises:
Return type:

Timestamp

Returns:

converted date

dict(default=None, required_keys=None, errors='coerce')[source]

Ensure the target is a dictionary.

Parameters:
  • default (Optional[dict[str, Any]]) – default values, when the target is None or key is not included in the target

  • required_keys (Optional[list[Any]]) – keys which must be included

  • errors (str) – “coerce” or “raise”

Raises:
Return type:

dict[str, Any]

Returns:

the target is self with default values and required keys

Note

All keys of @default will be included and the target will overwrite it.

Note

If some keys of @required_keys are not included and @errors=”coerce”, None will be set as the values of the keys.

float(value_range=(0, None), default=None, digits=None)[source]

Convert a value to a float value.

Parameters:
Raises:
Return type:

float

Returns:

converted float value

instance(expected)[source]

Ensure that the target is an instance of a specified class.

Parameters:

expected (Any) – expected class or sequence of expected classes

Raises:

UnExpectedTypeError – the target is not an instance of the class

Return type:

Any

Returns:

the target itself

int(value_range=(0, None), default=None, round_ok=False)[source]

Convert a value to an integer.

Parameters:
Raises:
Return type:

int

Returns:

converted float value

kwargs(functions, default=None)[source]

Find keyword arguments of the functions.

Parameters:
Raises:

UnExpectedTypeError – the target is not a dictionary

Return type:

dict[str, Any]

Returns:

dict – keyword arguments of the functions

sequence(default=None, flatten=False, unique=False, candidates=None, length=None)[source]

Convert a sequence (list, tuple) to a list.

Parameters:
  • default (Optional[Iterable[Any]]) – default value when the target is None

  • flatten (bool) – whether flatten the sequence or not

  • unique (bool) – whether remove duplicated values or not, the first value will remain

  • candidates (Optional[Iterable[Any]]) – list of candidates or None (no limitations)

  • length (Optional[int]) – length of the sequence or None (no limitations)

Raises:
Return type:

list[Any]

Returns:

converted list or empty list (when both of the target and @default are None)

subclass(parent)[source]

Ensure the target is a subclass of the parent class.

Parameters:

parent (Any) – parent class or sequence of parent classes

Raises:

NotSubclassError – the target is not the subclass

Return type:

Any

Returns:

the target itself

tau(default=None)[source]

Validate the value can be used as tau value [min].

Parameters:

default (Optional[int]) – default value when the target is None

Raises:
Return type:

Optional[int]

Returns:

converted float value or None (when both of the target and @default are None)