atomica.plotting.Series

class atomica.plotting.Series(tvec, vals, result='default', pop='default', output='default', data_label='', color=None, units='', timescale=None, data_pop='')[source]

Bases: object

Represent a plottable time series

A Series represents a quantity available for plotting. It is like a TimeSeries but contains additional information only used for plotting, such as color.

Parameters
  • tvec – array of time values

  • vals – array of values

  • result – name of the result associated with ths data

  • pop – name of the pop associated with the data

  • output – name of the output associated with the data

  • data_label – name of a quantity in project data to plot in conjunction with this Series

  • color – the color to render the Series with

  • units – the units for the values

  • timescale – For Number, Probability and Duration units, there are timescales associated with them

Attributes

unit_string

Return the units for the quantity including timescale

data_label

Used to identify data for plotting - should match the name of a data TDVE

data_pop

Used to identify which population in the TDVE (specified by data_label) to look up

units

The units for the quantity to display on the plot

timescale

If the quantity has a time-like denominator (e.g.

Methods

interpolate

Return interpolated vector of values

data_label

Used to identify data for plotting - should match the name of a data TDVE

data_pop

Used to identify which population in the TDVE (specified by data_label) to look up

interpolate(new_tvec)[source]

Return interpolated vector of values

This function returns an np.array() with the values of this series interpolated onto the requested time array new_tvec. To ensure results are not misleading, extrapolation is disabled and will return NaN if new_tvec contains values outside the original time range.

Note that unlike PlotData.interpolate(), Series.interpolate() does not modify the object but instead returns the interpolated values. This makes the Series object more versatile (PlotData is generally used only for plotting, but the Series object can be a convenient way to work with values computed using the sophisticated aggregations within PlotData).

Parameters

new_tvec – array of new time values

Returns

array with interpolated values (same size as new_tvec)

timescale

If the quantity has a time-like denominator (e.g. number/year, probability/day) then the denominator is stored here (in units of years) This enables quantities to be time-aggregated correctly (e.g. number/day must be converted to number/timestep prior to summation or integration) For links, the timescale is normally just dt. This also enables more rigorous checking for quantities with time denominators than checking for a string like '/year' because users may not set this specifically.

property unit_string: str

Return the units for the quantity including timescale

When making plots, it is useful for the axis label to have the units of the quantity. The units should also include the time scale e.g. “Death rate (probability per day)”. However, if the timescale changes due to aggregation or accumulation, then the value might be different. In that case, The unit of the quantity is interpreted as a numerator if the Timescale is not None. For example, Compartments have units of ‘number’, while Links have units of ‘number/timestep’ which is stored as Series.units='number' and Series.timescale=0.25 (if dt=0.25). The unit_string attribute returns a string that is suitable to use for plots e.g. ‘number per week’.

Return type

str

Returns

A string representation of the units for use in plotting

units

The units for the quantity to display on the plot