Result#

class Result(name=None, label=None, dtype=<class 'float'>, shape=None, scale=True, auto_plot=True, module=None, values=None, timevec=None, low=None, high=None, summarize_by=None, **kwargs)[source]#

Bases: BaseArr

Array-like container for holding sim results.

Parameters:

  • module (str) – the name of the parent module, e.g. ‘hiv’

  • name (str) – the name of this result, e.g. ‘new_infections’

  • shape (int/tuple) – the shape of the result array (usually module.npts)

  • scale (bool) – whether or not the result scales by population size (e.g. a count does, a prevalence does not)

  • auto_plot (bool) – whether to include automatically in sim.plot() results

  • label (str) – a human-readable label for the result

  • values (array) – prepopulate the Result with these values

  • timevec (array) – an array of time points

  • low (array) – values for the lower bound

  • high (array) – values for the upper bound

  • summarize_by (str) – how to summarize the data, e.g. ‘sum’ or ‘mean’

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

full_label

<label>, e.g. "HIV: New infections".

has_dates

Check whether the time vector uses dates (rather than numbers)

initialized

key

<module>.<name>, e.g. "hiv.new_infections".

Methods

property has_dates#

Check whether the time vector uses dates (rather than numbers)

init_values(values=None, dtype=None, shape=None, force=False)[source]#

Handle values

update(*args, **kwargs)[source]#

Update parameters, and initialize values if needed

property key#

<module>.<name>, e.g. “hiv.new_infections”

Type:

Return the unique key of the result

property full_label#

<label>, e.g. “HIV: New infections”

Type:

Return the full label of the result

Type:

<Module>

resample(new_unit='year', summarize_by=None, col_names='vlh', die=False, output_form='series', use_years=False, sep='_')[source]#

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:

  • new_unit (str) – the new unit to resample to, e.g. ‘year’, ‘month’, ‘week’, ‘day’, ‘1W’, ‘2M’, etc.

  • summarize_by (str) – how to summarize the data, e.g. ‘sum’ or ‘mean’

  • col_names (str) – whether to rename the columns with the name of the result

  • die (bool) – whether to raise an error if the summarization method cannot be determined

  • output_form (str) – ‘series’, ‘dataframe’, or ‘result’

  • use_years (bool) – whether to use years as the unit of time

from_df(df)[source]#

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

to_series(set_name=False, resample=None, sep='_', **kwargs)[source]#

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

to_df(sep='_', col_names='vlh', resample=None, set_date_index=False, **kwargs)[source]#

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

Parameters:

  • 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

  • set_date_index (bool) – if True, use the timevec as the index

  • resample (str) – if provided, resample the data to this frequency

  • kwargs – passed to the resample method

plot(fig=None, ax=None, fig_kw=None, plot_kw=None, fill_kw=None, **kwargs)[source]#

Plot a single result; kwargs are interpreted as plot_kw