atomica.utils.TimeSeries¶
- class atomica.utils.TimeSeries(t=None, vals=None, units=None, assumption=None, sigma=None)[source]¶
Bases:
object
Class to store time-series data
Internally values are stored as lists rather than numpy arrays because insert/remove operations on lists tend to be faster (and working with sparse data is a key role of TimeSeries objects). Note that methods like
interpolate()
return numpy arrays, so the output types from such functions should generally match up with what is required by the calling function.- Parameters
t – Optionally specify a scalar, list, or array of time values
vals – Optionally specify a scalar, list, or array of values (must be same size as
t
)units (
Optional
[str
]) – Optionally specify units (as a string)assumption (
Optional
[float
]) – Optionally specify a scalar assumptionsigma (
Optional
[float
]) – Optionally specify a scalar uncertainty
Attributes
Sorted array of time points.
Time-specific values - indices correspond to
self.t
The units of the quantity
The time-independent scalar assumption
Uncertainty value, assumed to be a standard deviation
Check if any data has been provided
Check if time-specific data has been provided
Methods
Return a copy of the
TimeSeries
Retrieve value at a particular time
Return arrays with the contents of this TimeSeries
Insert a value or list of at a particular time
Return interpolated values
Remove single time point
Remove times from start
Remove times from start
Remove a range of times
Return a sampled copy of the TimeSeries
- assumption¶
The time-independent scalar assumption
- get(t)[source]¶
Retrieve value at a particular time
This function will automatically retrieve the value of the assumption if no time specific values have been provided, or if any time specific values are provided, will return the value entered at that time. If time specific values have been entered and the requested time is not explicitly present, an error will be raised.
This function may be deprecated in future because generally it is more useful to either call
TimeSeries.interpolate()
if interested in getting values at arbitrary times, orTimeSeries.get_arrays()
if interested in retrieving values that have been entered.- Parameters
t – A time value. If
None
, will return assumption regardless of whether time data has been entered or not- Return type
- Returns
The value at the corresponding time. Returns None if the value no value present
- get_arrays()[source]¶
Return arrays with the contents of this TimeSeries
The TimeSeries instance may have time values, or may simply have an assumption. If obtaining raw arrays is desired, this function will return arrays with values extracted from the appropriate attribute of the TimeSeries. However, in general, it is usually .interpolate() that is desired, rather than .get_arrays()
- Returns
Tuple with two arrays - the first item is times (with a single NaN if the TimeSeries only has an assumption) and the second item is values
- property has_data: bool¶
Check if any data has been provided
- Return type
- Returns
True
if any data has been entered (assumption or time-specific)
- property has_time_data: bool¶
Check if time-specific data has been provided
Unlike
has_data
, this will returnFalse
if only an assumption has been entered- Return type
- Returns
True
if any time-specific data has been entered
- insert(t, v)[source]¶
Insert a value or list of at a particular time
If the value already exists in the
TimeSeries
, it will be overwritten/updated. The arrays are internally sorted by time value, and this order will be maintained.- Parameters
t – Time value to insert or update. If
None
, the value will be assigned to the assumptionv – Value to insert. If
None
, this function will return immediately without doing anything
- Return type
- interpolate(t2, method='linear', **kwargs)[source]¶
Return interpolated values
This method returns interpolated values from the time series at time points t2 according to a given interpolation method. There are 4 possibilities for the method
‘linear’ - normal linear interpolation (with constant, zero-gradient extrapolation)
‘pchip’ - legacy interpolation with some curvature between points (with constant, zero-gradient extrapolation)
‘previous’ - stepped interpolation, maintain value until the next timepoint is reached (with constant, zero-gradient extrapolation)
Interpolation class or generator function
That final option allows the use of arbitrary interpolation methods. The underlying call will be
c = method(t1, v1, **kwargs) return c(t2)
so for example, if you wanted to use the base Scipy pchip method with no extrapolation, then could pass in
TimeSeries.interpolate(…,method=scipy.interpolate.PchipInterpolator)
Note that the following special behaviours apply:
If there is no data at all, this function will return
np.nan
for all requested time pointsIf only an assumption exists, this assumption will be returned for all requested time points
- Otherwise, arrays will be formed with all finite time values
If no finite time values remain, an error will be raised (in general, a TimeSeries should not store such values anyway)
If only one finite time value remains, then that value will be returned for all requested time points
Otherwise, the specified interpolation method will be used
- Parameters
t2 (
array
) – float, list, or array, with timesmethod – A string ‘linear’, ‘pchip’ or ‘previous’ OR a callable item that returns an Interpolator
- Return type
array
- Returns
array the same length as t2, with interpolated values
- remove(t)[source]¶
Remove single time point
- Parameters
t – Time value to remove. Set to
None
to remove the assumption- Return type
- remove_after(t_remove)[source]¶
Remove times from start
- Parameters
tval – Remove times up to but not including this time
- Return type
- remove_before(t_remove)[source]¶
Remove times from start
- Parameters
tval – Remove times up to but not including this time
- Return type
- remove_between(t_remove)[source]¶
Remove a range of times
Note that the endpoints are not included
- Parameters
t_remove – two element iterable e.g. array, with [min,max] times
- Return type
- sample(constant=True)[source]¶
Return a sampled copy of the TimeSeries
This method returns a copy of the TimeSeries in which the values have been perturbed based on the uncertainty value.
- Parameters
constant – If True, time series will be perturbed by a single constant offset. If False, an different perturbation will be applied to each time specific value independently.
- Returns
A copied
TimeSeries
with perturbed values
- sigma¶
Uncertainty value, assumed to be a standard deviation
- units¶
The units of the quantity
- vals¶
Time-specific values - indices correspond to
self.t