covsirphy.util package

Submodules

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:

y_true (pandas.DataFrame or pandas.Series) – correct target values
y_pred (pandas.DataFrame or pandas.Series) – estimated target values
how (str) – “all” (use all records) or “inner” (intersection will be used)
on (str or list[str] or None) – column names to join on or None (join on index)

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:

UnExpectedValueError – un-expected metric was applied
ValueError – ME was selected as metric when the targets have multiple columns

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:

UnExpectedTypeError – the target is not a dataframe or that has un-expected-type index
EmptyError – empty when @empty_ok is False
NotIncludedError – expected columns were not included

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:

value_range (tuple[Timestamp | None, Timestamp | None]) – value range, None means un-specified
default (Timestamp | None) – default value when the target is None

Raises:

UnExpectedNoneError – the default value is None when the target is None
UnExpectedTypeError – the target cannot be converted to a date object
UnExpectedValueRangeError – the value is out of value range

Return type:

Timestamp

Returns:

converted date

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

Ensure the target is a dictionary.

Parameters:

default (dict[str, Any] | None) – default values, when the target is None or key is not included in the target
required_keys (list[Any] | None) – keys which must be included
errors (str) – “coerce” or “raise”

Raises:

UnExpectedTypeError – the target is not a dictionary
NAFoundError – values of the required keys are not specified when @errors=”raise”

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:

value_range (tuple[int | None, int | None]) – value range, None means un-specified
default (float | None) – default value when the target is None
digits (int | None) – effective digits or None (skip rounding)

Raises:

UnExpectedNoneError – the default value is None when the target is None
UnExpectedTypeError – the target cannot be converted to a float value
UnExpectedValueRangeError – the value is out of value range

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:

value_range (tuple[int | None, int | None]) – value range, None means un-specified
default (int | None) – default value when the target is None
round_ok (bool) – whether ignore round-off error

Raises:

UnExpectedNoneError – the default value is None when the target is None
UnExpectedTypeError – the target cannot be converted to an integer or round-off error exists when @round_ok is False
UnExpectedValueRangeError – the value is out of value range

Return type:

int

Returns:

converted float value

kwargs(functions, default=None)[source]

Find keyword arguments of the functions.

Parameters:

functions (Union[list[Callable], Callable]) – target functions
default (dict[str, Any] | None) – default values, when the target is None or key is not included in the target

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 (int | None) – length of the sequence or None (no limitations)

Raises:

UnExpectedTypeError – the target cannot be converted to a list or failed in flattening
UnExpectedValueError – the target has a value which is not included in the candidates
UnExpectedLengthError – the number of elements is not the same as @length

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 (int | None) – default value when the target is None

Raises:

UnExpectedTypeError – the target cannot be converted to an integer
UnExpectedValueRangeError – the value is out of value range

Return type:

int | None

Returns:

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