results

results

Result structures.

Classes

Name	Description
Result	Array-like container for holding sim results.
Results	Container for storing results

Result

results.Result(
    self,
    name=None,
    label=None,
    dtype=float,
    shape=None,
    scale=True,
    auto_plot=True,
    module=None,
    values=None,
    timevec=None,
    low=None,
    high=None,
    summarize_by=None,
    **kwargs,
)

Array-like container for holding sim results.

Parameters

Name	Type	Description	Default
module	str	the name or label of the parent module, e.g. ‘SIR’	None
name	str	the name of this result, e.g. ‘new_infections’	None
shape	int / tuple	the shape of the result array (usually module.npts)	None
scale	bool	whether or not the result scales by population size (e.g. a count does, a prevalence does not)	True
auto_plot	bool	whether to include automatically in sim.plot() results	True
label	str	a human-readable label for the result	None
values	array	prepopulate the Result with these values	None
timevec	array	an array of time points	None
low	array	values for the lower bound	None
high	array	values for the upper bound	None
summarize_by	str	how to summarize the data, e.g. ‘sum’ or ‘mean’	None

In most cases, ss.Result behaves exactly like np.array(), except with the additional fields listed above. To see everything contained in a result, you can use result.disp().

Attributes

Name	Description
full_label	Return the full label of the result: : , e.g. “HIV: New infections”
has_dates	Check whether the time vector uses dates (rather than numbers)
key	Return the unique key of the result: ., e.g. “hiv.new_infections”

Methods

Name	Description
convert_timevec	Make sure we’re using a timevec that’s in the right format i.e. dates
disp	Full display of all attributes/methods
from_df	Make a copy of the result with new values from a dataframe
init_values	Handle values
plot	Plot a single result; kwargs are interpreted as plot_kw
resample	Resample the result, e.g. from days to years. Leverages the pandas resample method.
to_df	Convert to a dataframe with timevec, value, low, and high columns
to_series	Convert to a series with timevec as the index and value as the data
to_str	Convert Result object to a string
update	Update parameters, and initialize values if needed

convert_timevec

results.Result.convert_timevec(force=False)

Make sure we’re using a timevec that’s in the right format i.e. dates

disp

results.Result.disp()

Full display of all attributes/methods

from_df

results.Result.from_df(df)

Make a copy of the result with new values from a dataframe

init_values

results.Result.init_values(values=None, dtype=None, shape=None, force=False)

Handle values

plot

results.Result.plot(
    fig=None,
    ax=None,
    fig_kw=None,
    plot_kw=None,
    fill_kw=None,
    **kwargs,
)

Plot a single result; kwargs are interpreted as plot_kw

resample

results.Result.resample(
    new_unit='year',
    summarize_by=None,
    col_names='vlh',
    die=False,
    output_form='series',
    use_years=False,
    sep='_',
)

Resample the result, e.g. from days to years. Leverages the pandas resample method. Accepts all the Starsim units, plus the Pandas ones documented here: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases

Parameters

Name	Type	Description	Default
new_unit	str	the new unit to resample to, e.g. ‘year’, ‘month’, ‘week’, ‘day’, ‘1W’, ‘2M’, etc.	'year'
summarize_by	str	how to summarize the data, e.g. ‘sum’ or ‘mean’	None
col_names	str	whether to rename the columns with the name of the result	'vlh'
die	bool	whether to raise an error if the summarization method cannot be determined	False
output_form	str	‘series’, ‘dataframe’, or ‘result’	'series'
use_years	bool	whether to use years as the unit of time	False

to_df

results.Result.to_df(
    sep='_',
    col_names='vlh',
    bounds=True,
    resample=None,
    set_date_index=False,
    **kwargs,
)

Convert to a dataframe with timevec, value, low, and high columns

Parameters

Name	Type	Description	Default
sep	str	separator for the column names	'_'
col_names	str or None	if None, uses the name of the result. Default is ‘vlh’ which uses value, low, high	'vlh'
set_date_index	bool	if True, use the timevec as the index	False
bounds	bool	include high and low bounds as well (if and only if they exist, e.g. from a MultiSim)	True
resample	str	if provided, resample the data to this frequency	None
kwargs		passed to the resample method if resample=True	{}

to_series

results.Result.to_series(set_name=False, resample=None, sep='_', **kwargs)

Convert to a series with timevec as the index and value as the data Args: set_name (bool): whether to set the name of the series to the name of the result resample (str): if provided, resample the data to this frequency kwargs: passed to the resample method

to_str

results.Result.to_str(label=True)

Convert Result object to a string

update

results.Result.update(*args, **kwargs)

Update parameters, and initialize values if needed

Results

results.Results(self, module, *args, strict=True, **kwargs)

Container for storing results

Attributes

Name	Description
all_results	Iterator over all results, skipping any nested values
all_results_dict	Dictionary of all results, skipping any nested values
equal_len	Check if all results are equal length
is_msim	Check if this is a MultiSim

Methods

Name	Description
append	This is activated by adding as well, e.g. results += result
flatten	Turn from a nested dictionary into a flat dictionary, keeping only results by default
plot	Plot all the results
to_df	Merge all results dataframes into one

append

results.Results.append(arg, key=None)

This is activated by adding as well, e.g. results += result

flatten

results.Results.flatten(
    sep='_',
    only_results=True,
    only_auto=False,
    keep_case=False,
    **kwargs,
)

Turn from a nested dictionary into a flat dictionary, keeping only results by default

plot

results.Results.plot(style='fancy', fig_kw=None, plot_kw=None)

Plot all the results

to_df

results.Results.to_df(sep='_', descend=False, **kwargs)

Merge all results dataframes into one Args: sep (str): separator for the column names descend (bool): whether to descend into nested results kwargs: passed to the Result.to_df() method, can include instructions for summarizing results by time