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. 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`.

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’.

Returns:: A string representation of the units for use in plotting

units¶: The units for the quantity to display on the plot