timeseries

Create a TimeSeries from an xarray.DataArray.

The dimensions of the DataArray have to be (time, component, sample), in this order. The time dimension can have an arbitrary name, but component and sample must be named "component" and "sample", respectively.

The first dimension (time), and second dimension (component) must be indexed (i.e., have coordinates). The time must be indexed either with a pandas DatetimeIndex, a pandas RangeIndex, or a pandas Index that can be converted to a RangeIndex. It is better if the index has no holes; alternatively setting fill_missing_dates can in some cases solve these issues (filling holes with NaN, or with the provided fillna_value numeric value, if any).

If two components have the same name or are not strings, this method will disambiguate the components names by appending a suffix of the form "<name>_N" to the N-th column with name "name". The component names in the static covariates and hierarchy (if any) are *not* disambiguated.

Parameters

xa

The xarray.DataArray

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

copy

Whether to copy the times (time index dimension) and values (data) objects. If copy=False, mutating the series data will affect the original data. Additionally, if times lack a frequency or step size, it will be assigned to the original object.

Returns

TimeSeries

The resulting series.

Examples

>>> import xarray as xr
>>> import numpy as np
>>> from anomx.data.timeseries import DIMS
>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>>
>>> # create values with the required dimensions (time, component, sample)
>>> vals = np.random.random((3, 1, 1))
>>> # create time index with daily frequency
>>> times = generate_index("2020-01-01", length=3, freq="D")
>>> columns = ["vals"]
>>>
>>> # create xarray with the required dimensions and coordinates
>>> xa = xr.DataArray(
>>>     vals,
>>>     dims=DIMS,
>>>     coords={DIMS[0]: times, DIMS[1]: columns}
>>> )
>>> series = TimeSeries.from_xarray(xa)
>>> series.shape
(3, 1, 1)

Create a TimeSeries from a CSV file.

One column can be used to represent the time (if not present, the time index will be a RangeIndex) and a list of columns value_cols can be used to indicate the values for this time series.

Parameters

filepath_or_buffer

The path to the CSV file, or the file object; consistent with the argument of pandas.read_csv function

time_col

The time column name. If set, the column will be cast to a pandas DatetimeIndex (if it contains timestamps) or a RangeIndex (if it contains integers). If not set, the pandas RangeIndex will be used.

value_cols

A string or list of strings representing the value column(s) to be extracted from the CSV file. If set to None, all columns from the CSV file will be used (except for the time_col, if specified)

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

static_covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series or a pandas DataFrame. If a Series, the index represents the static variables. The covariates are globally 'applied' to all components of the TimeSeries. If a DataFrame, the columns represent the static variables and the rows represent the components of the uni/multivariate TimeSeries. If a single-row DataFrame, the covariates are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of rows must match the number of components of the TimeSeries (in this case, the number of columns in the CSV file). This adds control for component-specific static covariates.

hierarchy

Optionally, a dictionary describing the grouping(s) of the time series. The keys are component names, and for a given component name c, the value is a list of component names that c "belongs" to. For instance, if there is a total component, split both in two divisions d1 and d2 and in two regions r1 and r2, and four products d1r1 (in division d1 and region r1), d2r1, d1r2 and d2r2, the hierarchy would be encoded as follows.

hierarchy={ "d1r1": ["d1", "r1"], "d1r2": ["d1", "r2"], "d2r1": ["d2", "r1"], "d2r2": ["d2", "r2"], "d1": ["total"], "d2": ["total"], "r1": ["total"], "r2": ["total"] } ..

The hierarchy can be used to reconcile forecasts (so that the sums of the forecasts at different levels are consistent), see hierarchical reconciliation.

metadata

Optionally, a dictionary with metadata to be added to the TimeSeries.

**kwargs

Optional arguments to be passed to pandas.read_csv function

Returns

TimeSeries

The resulting series.

Examples

>>> from anomx.data.timeseries import TimeSeries
>>> TimeSeries.from_csv("data.csv", time_col="time")

Create a TimeSeries from a selection of columns of a DataFrame.

One column (or the DataFrame index) has to represent the time, and a list of columns value_cols has to represent the values for this time series.

Parameters

df

The DataFrame, or anything which can be converted to a narwhals DataFrame (e.g. pandas.DataFrame, polars.DataFrame, ...). See the narwhals documentation for more information.

time_col

The time column name. If set, the column will be cast to a pandas DatetimeIndex (if it contains timestamps) or a RangeIndex (if it contains integers). If not set, the DataFrame index will be used. In this case the DataFrame must contain an index that is either a pandas DatetimeIndex, a pandas RangeIndex, or a pandas Index that can be converted to a RangeIndex. It is better if the index has no holes; alternatively setting fill_missing_dates can in some cases solve these issues (filling holes with NaN, or with the provided fillna_value numeric value, if any).

value_cols

A string or list of strings representing the value column(s) to be extracted from the DataFrame. If set to None, the whole DataFrame will be used.

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

static_covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series or a pandas DataFrame. If a Series, the index represents the static variables. The covariates are globally 'applied' to all components of the TimeSeries. If a DataFrame, the columns represent the static variables and the rows represent the components of the uni/multivariate TimeSeries. If a single-row DataFrame, the covariates are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of rows must match the number of components of the TimeSeries (in this case, the number of columns in value_cols). This adds control for component-specific static covariates.

hierarchy

Optionally, a dictionary describing the grouping(s) of the time series. The keys are component names, and for a given component name c, the value is a list of component names that c "belongs" to. For instance, if there is a total component, split both in two divisions d1 and d2 and in two regions r1 and r2, and four products d1r1 (in division d1 and region r1), d2r1, d1r2 and d2r2, the hierarchy would be encoded as follows.

hierarchy={ "d1r1": ["d1", "r1"], "d1r2": ["d1", "r2"], "d2r1": ["d2", "r1"], "d2r2": ["d2", "r2"], "d1": ["total"], "d2": ["total"], "r1": ["total"], "r2": ["total"] } ..

The hierarchy can be used to reconcile forecasts (so that the sums of the forecasts at different levels are consistent), see hierarchical reconciliation.

metadata

Optionally, a dictionary with metadata to be added to the TimeSeries.

copy

Whether to copy the times (DataFrame index or the time_col column) and DataFrame values. If copy=False, mutating the series data will affect the original data. Additionally, if times lack a frequency or step size, it will be assigned to the original object.

Returns

TimeSeries

The resulting series.

Examples

>>> import pandas as pd
>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>> # create values and times with daily frequency
>>> data = {"vals": range(3), "time": generate_index("2020-01-01", length=3, freq="D")}
>>> # create from `pandas.DataFrame`
>>> df = pd.DataFrame(data)
>>> series = TimeSeries.from_dataframe(df, time_col="time")
>>> # shape (n time steps, n components, n samples)
>>> series.shape
(3, 1, 1)

>>> # or from `polars.DataFrame` (make sure Polars is installed)
>>> import polars as pl
>>> df = pl.DataFrame(data)
>>> series = TimeSeries.from_dataframe(df, time_col="time")
>>> series.shape
(3, 1, 1)

Create a list of TimeSeries grouped by a selection of columns from a DataFrame.

One column (or the DataFrame index) has to represent the time, a list of columns group_cols must be used for extracting the individual TimeSeries by groups, and a list of columns value_cols has to represent the values for the individual time series. Values from columns group_cols and static_cols are added as static covariates to the resulting TimeSeries objects. These can be viewed with my_series.static_covariates. Different to group_cols, static_cols only adds the static values but are not used to extract the TimeSeries groups.

Parameters

df

The DataFrame, or anything which can be converted to a narwhals DataFrame (e.g. pandas.DataFrame, polars.DataFrame, ...). See the narwhals documentation for more information.

group_cols

A string or list of strings representing the columns from the DataFrame by which to extract the individual TimeSeries groups.

time_col

The time column name. If set, the column will be cast to a pandas DatetimeIndex (if it contains timestamps) or a RangeIndex (if it contains integers). If not set, the DataFrame index will be used. In this case the DataFrame must contain an index that is either a pandas DatetimeIndex, a pandas RangeIndex, or a pandas Index that can be converted to a RangeIndex. Be aware that the index must represents the actual index of each individual time series group (can contain non-unique values). It is better if the index has no holes; alternatively setting fill_missing_dates can in some cases solve these issues (filling holes with NaN, or with the provided fillna_value numeric value, if any).

value_cols

A string or list of strings representing the value column(s) to be extracted from the DataFrame. If set to None, the whole DataFrame will be used.

static_cols

A string or list of strings representing static variable columns from the DataFrame that should be appended as static covariates to the resulting TimeSeries groups. Different to group_cols, the DataFrame is not grouped by these columns. Uses the first encountered value per group and column (assumes that there is only one unique value). Static covariates can be used as input features to all Anomx models that support it.

metadata_cols

Same as static_cols but appended as metadata to the resulting TimeSeries groups. Metadata will never be used by the underlying Anomx models.

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

drop_group_cols

Optionally, a string or list of strings with group_cols column(s) to exclude from the static covariates.

n_jobs

Optionally, an integer representing the number of parallel jobs to run. Behavior is the same as in the joblib.Parallel class.

verbose

Optionally, a boolean value indicating whether to display a progress bar.

copy

Whether to copy the times (DataFrame index or the time_col column) and DataFrame values. If copy=False, mutating the series data will affect the original data. Additionally, if times lack a frequency or step size, it will be assigned to the original object.

Returns

List[TimeSeries]

A list of series, where each series represents one group from the DataFrame.

Examples

>>> import pandas as pd
>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>>
>>> # create a DataFrame with two series that have different ids,
>>> # values, and frequencies
>>> df_1 = pd.DataFrame({
>>>     "ID": [0] * 3,
>>>     "vals": range(3),
>>>     "time": generate_index("2020-01-01", length=3, freq="D")}
>>> )
>>> df_2 = pd.DataFrame({
>>>     "ID": [1] * 6,
>>>     "vals": range(6),
>>>     "time": generate_index("2020-01-01", length=6, freq="h")}
>>> )
>>> df = pd.concat([df_1, df_2], axis=0)
>>>
>>> # extract the series by "ID" groups from the DataFrame
>>> series_multi = TimeSeries.from_group_dataframe(
>>>     df,
>>>     group_cols="ID",
>>>     time_col="time"
>>> )
>>> len(series_multi), series_multi[0].shape, series_multi[1].shape
(2, (3, 1, 1), (6, 1, 1))

Create a TimeSeries from a Series.

The series must contain an index that is either a pandas DatetimeIndex, a pandas RangeIndex, or a pandas Index that can be converted into a RangeIndex. It is better if the index has no holes; alternatively setting fill_missing_dates can in some cases solve these issues (filling holes with NaN, or with the provided fillna_value numeric value, if any).

Parameters

pd_series

The Series, or anything which can be converted to a narwhals Series (e.g. pandas.Series, ...). See the narwhals documentation for more information.

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

static_covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series or a single-row pandas DataFrame. If a Series, the index represents the static variables. If a DataFrame, the columns represent the static variables and the single row represents the univariate TimeSeries component.

metadata

Optionally, a dictionary with metadata to be added to the TimeSeries.

copy

Whether to copy the Series' values. If copy=False, mutating the series data will affect the original data.

Returns

TimeSeries

The resulting series.

Examples

>>> import pandas as pd
>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>> # create values and times with daily frequency
>>> vals, times = range(3), generate_index("2020-01-01", length=3, freq="D")
>>>
>>> # create from `pandas.Series`
>>> pd_series = pd.Series(vals, index=times)
>>> series = TimeSeries.from_series(pd_series)
>>> series.shape
(3, 1, 1)

Create a TimeSeries from a time index and value array.

Parameters

times

A pandas DateTimeIndex, RangeIndex, or Index that can be converted to a RangeIndex representing the time axis for the time series. It is better if the index has no holes; alternatively setting fill_missing_dates can in some cases solve these issues (filling holes with NaN, or with the provided fillna_value numeric value, if any).

values

A Numpy array, or array-like of values for the TimeSeries. Both 2-dimensional arrays, for deterministic series, and 3-dimensional arrays, for probabilistic series, are accepted. In the former case the dimensions should be (time, component), and in the latter case (time, component, sample).

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

columns

Optionally, some column names to use for the second values dimension.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

static_covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series or a pandas DataFrame. If a Series, the index represents the static variables. The covariates are globally 'applied' to all components of the TimeSeries. If a DataFrame, the columns represent the static variables and the rows represent the components of the uni/multivariate TimeSeries. If a single-row DataFrame, the covariates are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of rows must match the number of components of the TimeSeries (in this case, the number of columns in values). This adds control for component-specific static covariates.

hierarchy

Optionally, a dictionary describing the grouping(s) of the time series. The keys are component names, and for a given component name c, the value is a list of component names that c "belongs" to. For instance, if there is a total component, split both in two divisions d1 and d2 and in two regions r1 and r2, and four products d1r1 (in division d1 and region r1), d2r1, d1r2 and d2r2, the hierarchy would be encoded as follows.

hierarchy={ "d1r1": ["d1", "r1"], "d1r2": ["d1", "r2"], "d2r1": ["d2", "r1"], "d2r2": ["d2", "r2"], "d1": ["total"], "d2": ["total"], "r1": ["total"], "r2": ["total"] } ..

The hierarchy can be used to reconcile forecasts (so that the sums of the forecasts at different levels are consistent), see hierarchical reconciliation.

metadata

Optionally, a dictionary with metadata to be added to the TimeSeries.

copy

Whether to copy the times and values objects. If copy=False, mutating the series data will affect the original data. Additionally, if times lack a frequency or step size, it will be assigned to the original object.

Returns

TimeSeries

The resulting series.

Examples

>>> import numpy as np
>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>> # create values and times with daily frequency
>>> vals, times = np.arange(3), generate_index("2020-01-01", length=3, freq="D")
>>> series = TimeSeries.from_times_and_values(times=times, values=vals)
>>> series.shape
(3, 1, 1)

Create an TimeSeries from an array of values.

The series will have an integer time index (RangeIndex).

Parameters

values

A Numpy array of values for the TimeSeries. Both 2-dimensional arrays, for deterministic series, and 3-dimensional arrays, for probabilistic series, are accepted. In the former case the dimensions should be (time, component), and in the latter case (time, component, sample).

columns

Columns to be used by the underlying pandas DataFrame.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

static_covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series or a pandas DataFrame. If a Series, the index represents the static variables. The covariates are globally 'applied' to all components of the TimeSeries. If a DataFrame, the columns represent the static variables and the rows represent the components of the uni/multivariate TimeSeries. If a single-row DataFrame, the covariates are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of rows must match the number of components of the TimeSeries (in this case, the number of columns in values). This adds control for component-specific static covariates.

hierarchy

Optionally, a dictionary describing the grouping(s) of the time series. The keys are component names, and for a given component name c, the value is a list of component names that c "belongs" to. For instance, if there is a total component, split both in two divisions d1 and d2 and in two regions r1 and r2, and four products d1r1 (in division d1 and region r1), d2r1, d1r2 and d2r2, the hierarchy would be encoded as follows.

hierarchy={ "d1r1": ["d1", "r1"], "d1r2": ["d1", "r2"], "d2r1": ["d2", "r1"], "d2r2": ["d2", "r2"], "d1": ["total"], "d2": ["total"], "r1": ["total"], "r2": ["total"] } ..

The hierarchy can be used to reconcile forecasts (so that the sums of the forecasts at different levels are consistent), see hierarchical reconciliation.

metadata

Optionally, a dictionary with metadata to be added to the TimeSeries.

copy

Whether to copy the values. If copy=False, mutating the series data will affect the original data.

Returns

TimeSeries

The resulting series.

Examples

>>> import numpy as np
>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>> vals = np.arange(3)
>>> series = TimeSeries.from_times_and_values(times=times, values=vals)
>>> series.shape
(3, 1, 1)

Create a TimeSeries from the JSON String representation of a TimeSeries.

The JSON String representation can be generated with TimeSeries.to_json().

If the JSON string contains static covariates, hierarchy, or metadata, they will be automatically loaded. The optional parameters static_covariates, hierarchy, and metadata can be used to override or provide these values if they are not present in the JSON string.

Parameters

json_str

The JSON String to convert.

static_covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series or a pandas DataFrame. If a Series, the index represents the static variables. The covariates are globally 'applied' to all components of the TimeSeries. If a DataFrame, the columns represent the static variables and the rows represent the components of the uni/multivariate TimeSeries. If a single-row DataFrame, the covariates are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of rows must match the number of components of the TimeSeries (in this case, the number of columns in value_cols). This adds control for component-specific static covariates. If the JSON string already contains static covariates, this parameter will override them.

hierarchy

Optionally, a dictionary describing the grouping(s) of the time series. The keys are component names, and for a given component name c, the value is a list of component names that c "belongs" to. For instance, if there is a total component, split both in two divisions d1 and d2 and in two regions r1 and r2, and four products d1r1 (in division d1 and region r1), d2r1, d1r2 and d2r2, the hierarchy would be encoded as follows.

hierarchy={ "d1r1": ["d1", "r1"], "d1r2": ["d1", "r2"], "d2r1": ["d2", "r1"], "d2r2": ["d2", "r2"], "d1": ["total"], "d2": ["total"], "r1": ["total"], "r2": ["total"] } ..

The hierarchy can be used to reconcile forecasts (so that the sums of the forecasts at different levels are consistent), see hierarchical reconciliation. If the JSON string already contains a hierarchy, this parameter will override it.

metadata

Optionally, a dictionary with metadata to be added to the TimeSeries. If the JSON string already contains metadata, this parameter will override it.

Returns

TimeSeries

The resulting series.

Examples

>>> from anomx.data.timeseries import TimeSeries
>>> json_str = (
>>>     '{"columns":["vals"],"index":["2020-01-01","2020-01-02","2020-01-03"],"data":[[0.0],[1.0],[2.0]]}'
>>> )
>>> series = TimeSeries.from_json(json_str)
>>> series.shape
(3, 1, 1)

Read a pickled TimeSeries.

Parameters

path : string

path pointing to a pickle file that will be loaded.

Returns

TimeSeries

The resulting series.

The static covariates of this series.

If defined, the static covariates are given as a pandas.DataFrame. The columns represent the static variables and the rows represent the components of the series.

The hierarchy of this series.

If defined, the hierarchy is given as a dictionary. The keys are the individual components and values are the set of parent(s) of these components in the hierarchy.

The metadata of this series.

If defined, the metadata is given as a dictionary.

The top level component name of this series, or None if the series has no hierarchy.

The bottom level component names of this series, or None if the series has no hierarchy.

The univariate series containing the single top-level component of this series, or None if the series has no hierarchy.

The series containing the bottom-level components of this series in the same order as they appear in the series, or None if the series has no hierarchy.

The shape of the series (n_timesteps, n_components, n_samples).

The number of time steps in the series.

The number of samples contained in the series.

The number of components (columns) in the series.

The width (number of components) of the series.

Whether the series is deterministic.

Whether the series is stochastic (probabilistic).

Whether the series is stochastic (probabilistic).

Whether the series is univariate.

The frequency of the series.

A pandas.DateOffset if the series is indexed with a pandas.DatetimeIndex. An integer (step size) if the series is indexed with a pandas.RangeIndex.

The string representation of the series' frequency.

The dtype of the series' values.

The component (column) names of the series, as a pandas.Index.

The component (column) names of the series, as a pandas.Index.

The time index of the series.

The time dimension name of the series.

Whether the series is indexed with a pandas.DatetimeIndex (otherwise it is indexed with an pandas.RangeIndex).

Whether the series is indexed with an pandas.RangeIndex (otherwise it is indexed with a pandas.DatetimeIndex).

Whether the series contains a hierarchy.

Whether the series contains static covariates.

Whether the series contains metadata.

The duration of the series (as a pandas.Timedelta or int).

Return an xarray.DataArray representation of the series.

Parameters

copy

Whether to return a copy of the series. Leave it to True unless you know what you are doing.

Returns

xarray.DataArray

An xarray.DataArray representation of represents the time series.

Return a Series representation of the series in a given backend.

Works only for univariate series that are deterministic (i.e., made of 1 sample).

Parameters

copy

Whether to return a copy of the series. Leave it to True unless you know what you are doing.

backend

The backend to which to export the TimeSeries. See the narwhals documentation for all supported backends.

Returns

A Series representation of the series in a given backend.

Return a DataFrame representation of the series in a given backend.

Each of the series components will appear as a column in the DataFrame. If the series is stochastic, the samples are returned as columns of the DataFrame with column names as 'component_s#' (e.g. with two components and two samples: 'comp0_s0', 'comp0_s1' 'comp1_s0' 'comp1_s1').

Parameters

copy

Whether to return a copy of the DataFrame. Leave it to True unless you know what you are doing.

backend

The backend to which to export the TimeSeries. See the narwhals documentation for all supported backends.

time_as_index

Whether to set the time index as the index of the DataFrame or in the left-most column. Only effective with the pandas backend.

suppress_warnings

Whether to suppress the warnings for the DataFrame creation.

add_static_covariates

Whether to add the series' static covariates to the resulting DataFrame (one column per component-static covariate pair). If a bool, controls whether to add all static covariates or none. If a string, or list of strings, specifies the subset of static covariate columns / names to add.

add_metadata

Whether to add the series' metadata to the resulting DataFrame (one column per metadata entry). If a bool, controls whether to add all metadata entries or none. If a string, or list of strings, specifies the subset of metadata keys / names to add.

Returns

DataFrame

A DataFrame representation of the series in a given backend.

Return the schema of the series as a dictionary.

Can be used to create new TimeSeries with the same schema.

The keys and values are:

• "time_freq": the frequency (or step size) of the time (or range) index
• "time_name": the name of the time index
• "columns": the columns / components
• "static_covariates": the static covariates
• "hierarchy": the hierarchy
• "metadata": the metadata

Return a new series with the values have been converted to the desired dtype.

Parameters

dtype

A NumPy dtype (numpy.float32 or numpy.float64)

Returns

TimeSeries

A series having the desired dtype.

Start time of the series.

Returns

pandas.Timestamp | int

A timestamp containing the first time of the TimeSeries (if indexed by DatetimeIndex), or an integer (if indexed by RangeIndex)

End time of the series.

Returns

pandas.Timestamp | int

A timestamp containing the last time of the TimeSeries (if indexed by DatetimeIndex), or an integer (if indexed by RangeIndex)

First value of the univariate series.

Returns

float

The first value of this univariate deterministic time series

Last value of the univariate series.

Returns

float

The last value of this univariate deterministic time series

First values of the potentially multivariate series.

Returns

numpy.ndarray

The first values of every component of this deterministic time series

Last values of the potentially multivariate series.

Returns

numpy.ndarray

The last values of every component of this deterministic time series

Return a 2-D array of shape (time, component), containing the series' values for one sample.

Parameters

copy

Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.

sample

For stochastic series, the sample for which to return values. Default: 0 (first sample).

Returns

numpy.ndarray

The values composing the time series.

Return a 2-D array of shape (time, component), containing the series' values for one sample taken uniformly at random from all samples.

Parameters

copy

Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.

Returns

numpy.ndarray

The values composing one sample taken at random from the time series.

Return a 3-D array of dimension (time, component, sample) containing the series' values for all samples.

Parameters

copy

Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.

Returns

numpy.ndarray

The values composing the time series.

Return a 1-D Numpy array of shape (time,) containing the univariate series' values for one sample.

Parameters

copy

Whether to return a copy of the values. Leave it to True unless you know what you are doing.

sample

For stochastic series, the sample for which to return values. Default: 0 (first sample).

Returns

numpy.ndarray

The values composing the time series guaranteed to be univariate.

Return a 2-D array of dimension (component, static variable) containing the series' static covariate values.

Parameters

copy

Whether to return a copy of the values, otherwise returns a view. Can only return a view if all values have the same dtype. Leave it to True unless you know what you are doing.

Returns

numpy.ndarray | None

The static covariate values if the series has static covariates, else None.

Return a new series with the first size points.

Parameters

size : int, default 5

number of points to retain

axis : str or int, optional, default: 0

axis along which to slice the series

Returns

TimeSeries

The series made of the first size points along the desired axis.

Return a new series with the last size points.

Parameters

size : int, default: 5

number of points to retain

axis : str or int, optional, default: 0 (time dimension)

axis along which we intend to display records

Returns

TimeSeries

The series made of the last size points along the desired axis.

Return a new series where this series is concatenated with the other series along a given axis.

Parameters

other : TimeSeries

another timeseries to concatenate to this one

axis : str or int

axis along which timeseries will be concatenated. ['time', 'component' or 'sample'; Default: 0 (time)]

ignore_time_axis : bool, default False

Ignore errors when time axis varies for some timeseries. Note that this may yield unexpected results

ignore_static_covariates : bool

whether to ignore all requirements for static covariate concatenation and only transfer the static covariates of the current (self) timeseries to the concatenated timeseries. Only effective when axis=1.

drop_hierarchy : bool

When axis=1, whether to drop hierarchy information. True by default. When False, the hierarchies will be "concatenated" as well (by merging the hierarchy dictionaries), which may cause issues if the component names of the resulting series and that of the merged hierarchy do not match. When axis=0 or axis=2, the hierarchy of the first series is always kept.

drop_metadata : bool

Whether to drop the metadata information of the concatenated timeseries. False by default. When False, the concatenated series will inherit the metadata from the current (self) timeseries.

Returns

TimeSeries

The concatenated series.

See Also

concatenate : a function to concatenate multiple series along a given axis.

Notes

When concatenating along the time dimension, the current series marks the start date of the resulting series, and the other series will have its time index ignored.

Compute and return gaps in the series.

Works only on deterministic time series (1 sample).

Parameters

mode

Only relevant for multivariate time series. The mode defines how gaps are defined. Set to 'any' if a NaN value in any columns should be considered as as gaps. 'all' will only consider periods where all columns' values are NaN. Defaults to 'all'.

Returns

pandas.DataFrame

A pandas.DataFrame containing a row for every gap (rows with all-NaN values in underlying DataFrame) in this time series. The DataFrame contains three columns that include the start and end time stamps of the gap and the integer length of the gap (in self.freq units if the series is indexed by a DatetimeIndex).

Create a copy of the series.

Returns

TimeSeries

A copy of the series.

Convert a point along the time index into an integer index ranging from (0, len(series)-1) inclusive.

Parameters

point

This parameter supports 3 different data types: pandas.Timestamp, float and int.

pandas.Timestamp work only on series that are indexed with a pandas.DatetimeIndex. In such cases, the returned point will be the index of this timestamp if it is present in the series time index. If it's not present in the time index, the index of the next timestamp is returned if after=True (if it exists in the series), otherwise the index of the previous timestamp is returned (if it exists in the series).

In case of a float, the parameter will be treated as the proportion of the time series that should lie before the point.

If an int and series is datetime-indexed, the value of point is returned. If an int and series is integer-indexed, the index position of point in the RangeIndex is returned (accounting for steps).

after

If the provided pandas Timestamp is not in the time series index, whether to return the index of the next timestamp or the index of the previous one.

Returns

int

The index position corresponding to the provided point in the series.

Convert a point into a pandas.Timestamp (if datetime-indexed) or integer (if integer-indexed).

Parameters

point

This parameter supports 3 different data types: float, int and pandas.Timestamp. In case of a float, the parameter will be treated as the proportion of the time series that should lie before the point. In case of int, the parameter will be treated as an integer index to the time index of series. Will raise a ValueError if not a valid index in series. In case of a pandas.Timestamp, point will be returned as is provided that the timestamp is present in the series time index, otherwise will raise a ValueError.

Returns

pandas.Timestamp | int

The index value corresponding to the provided point in the series. If the series is indexed by a pandas.DatetimeIndex, returns a pandas.Timestamp. If the series is indexed by a pandas.RangeIndex, returns an integer.

Split the series in two, after a provided split_point.

Parameters

split_point

A timestamp, float or integer. If float, represents the proportion of the series to include in the first TimeSeries (must be between 0.0 and 1.0). If integer, represents the index position after which the split is performed. A pandas.Timestamp can be provided for TimeSeries that are indexed by a pandas.DatetimeIndex. In such cases, the timestamp will be contained in the first TimeSeries, but not in the second one. The timestamp itself does not have to appear in the original TimeSeries index.

Returns

Tuple[TimeSeries, TimeSeries]

A tuple of two series. The first time series contains the first entries up to the split_point (inclusive), and the second contains the remaining ones.

Split the series in two, before a provided split_point.

Parameters

split_point

A timestamp, float or integer. If float, represents the proportion of the series to include in the first TimeSeries (must be between 0.0 and 1.0). If integer, represents the index position before which the split is performed. A pandas.Timestamp can be provided for TimeSeries that are indexed by a pandas.DatetimeIndex. In such cases, the timestamp will be contained in the second TimeSeries, but not in the first one. The timestamp itself does not have to appear in the original TimeSeries index.

Returns

Tuple[TimeSeries, TimeSeries]

A tuple of two series. The first time series contains the first entries up to the split_point (exclusive), and the second contains the remaining ones.

Return a new series where everything after (and in-/excluding) the provided time split_point was dropped.

The timestamp may not be in the series. If it is, the timestamp will be dropped.

Parameters

split_point

The timestamp that indicates cut-off time.

keep_point

Whether the provided split_point should be included in the returned series (if it exists in the series).

Returns

TimeSeries

A series that contains all entries until split_point (exclusive).

Return a new series where everything before (and in-/excluding) the provided time split_point was dropped.

The timestamp may not be in the series. If it is, the timestamp will be dropped.

Parameters

split_point

The timestamp that indicates cut-off time.

keep_point

Whether the provided split_point should be included in the returned series (if it exists in the series).

Returns

TimeSeries

A series that contains all entries starting after split_point (exclusive).

Return a slice of the series starting at start_ts and ending before end_ts.

For series having DatetimeIndex, this is inclusive on both ends. For series having a RangeIndex, end_ts is exclusive.

start_ts and end_ts don't have to be in the series.

Parameters

start_ts

The timestamp that indicates the left cut-off.

end_ts

The timestamp that indicates the right cut-off.

Returns

TimeSeries

A new series, with indices greater or equal than start_ts and smaller or equal than end_ts.

Return a slice of the series starting at start_ts (inclusive) and having at most n points.

Parameters

start_ts

The timestamp or index that indicates the splitting time.

n

The maximal length of the new TimeSeries.

Returns

TimeSeries

A new series, with length at most n, starting at start_ts.

Return a slice of the series ending at end_ts (inclusive) and having at most n points.

Parameters

end_ts

The timestamp or index that indicates the splitting time.

n

The maximal length of the new TimeSeries.

Returns

TimeSeries

A new series, with length at most n, ending at end_ts.

Return a slice of the series where the time index was intersected with the other series.

This method is in general *not* symmetric.

Parameters

other

the other time series

Returns

TimeSeries

A new series, containing the values of this series, over the time-span common to both series.

Return the sliced values of the series where the time index was intersected with the other series.

This method is in general *not* symmetric.

Parameters

other

The other time series

copy

Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.

Returns

numpy.ndarray

The values of this series, over the time-span common to both series.

Return the time index of the series where the time index was intersected with the other series.

This method is in general *not* symmetric.

Parameters

other

The other time series

copy

Whether to return a copy of the time index, otherwise returns a view. Leave it to True unless you know what you are doing.

Returns

pandas.DatetimeIndex | pandas.RangeIndex

The time index of this series, over the time-span common to both series.

Return a slice of the deterministic time series where NaN-containing entries at the beginning and the end were removed.

No entries after (and including) the first non-NaN entry and before (and including) the last non-NaN entry are removed.

This method is only applicable to deterministic series (i.e., having 1 sample).

Parameters

how

Define if the entries containing NaN in all the components ('all') or in any of the components ('any') should be stripped. Default: 'all'

Returns

TimeSeries

A new series where NaN-containing entries at start and end were removed.

Return the largest slice of the deterministic series without any gaps (contiguous all-NaN value entries) larger than max_gap_size.

This method is only applicable to deterministic series (i.e., having 1 sample).

Parameters

max_gap_size

Indicate the maximum gap size that the series can contain.

mode

Only relevant for multivariate time series. The mode defines how gaps are defined. Set to 'any' if a NaN value in any columns should be considered as as gaps. 'all' will only consider periods where all columns' values are NaN. Defaults to 'all'.

Returns

TimeSeries

A new series with the largest slice of the original that has no gaps longer than max_gap_size.

See Also

TimeSeries.gaps : return the gaps in the TimeSeries

Return a new series, which is a multiple of this series such that the first value is value_at_first_step.

Note: Numerical errors can appear with value_at_first_step > 1e+24.

Parameters

value_at_first_step

The new value for the first entry of the TimeSeries.

Returns

TimeSeries

A new series, where the first value is value_at_first_step and other values have been scaled accordingly.

Return a new series where the time index was shifted by n steps.

If n > 0, shifts into the future. If n < 0, shifts into the past.

For example, with n=2 and freq='M', March 2013 becomes May 2013. With n=-2, March 2013 becomes Jan 2013.

Parameters

n

The number of time steps (in self.freq unit) to shift by. Can be negative.

Returns

TimeSeries

A new series, with a shifted time index.

Return a new series with differenced values.

This is often used to make a time series stationary.

Parameters

n

Optionally, a positive integer indicating the number of differencing steps (default = 1). For instance, n=2 computes the second order differences.

periods

Optionally, periods to shift for calculating difference. For instance, periods=12 computes the difference between values at time t and times t-12.

dropna

Whether to drop the missing values after each differencing steps. If set to False, the corresponding first periods time steps will be filled with NaNs.

Returns

TimeSeries

A new series, with the differenced values.

Return a new series with the cumulative sum along the time axis.

Returns

TimeSeries

A new series, with the cumulatively summed values.

Whether the series has the same time index as the other series.

Parameters

other

the other series

Returns

bool

True if both series have the same index, False otherwise.

Return a new series with the other series appended to this series along the time axis (added to the end).

Parameters

other

A second TimeSeries.

Returns

TimeSeries

A new series, obtained by appending the second series to the first.

See Also

TimeSeries.concatenate : concatenate another series along a given axis. TimeSeries.prepend : prepend another series along the time axis.

Return a new series with values appended to this series along the time axis (added to the end).

This adds time steps to the end of the new series.

Parameters

values

An array with the values to append.

Returns

TimeSeries

A new series with the new values appended.

See Also

TimeSeries.prepend_values : prepend the values of another series along the time axis.

Return a new series with the other series prepended to this series along the time axis (added to the beginning).

Parameters

other

A second TimeSeries.

Returns

TimeSeries

A new series, obtained by prepending the second series to the first.

See Also

TimeSeries.concatenate : concatenate another series along a given axis. TimeSeries.append : append another series along the time axis.

Return a new series with values prepended to this series along the time axis (added to the beginning).

This adds time steps to the beginning of the new series.

Parameters

values

An array with the values to prepend to the start.

Returns

TimeSeries

A new series with the new values prepended.

See Also

TimeSeries.append_values : append the values of another series along the time axis.

Return a new series similar to this one but with new times and values.

Parameters

times

A pandas DateTimeIndex, RangeIndex (or Index that can be converted to a RangeIndex) representing the new time axis for the time series. It is better if the index has no holes; alternatively setting fill_missing_dates can in some cases solve these issues (filling holes with NaN, or with the provided fillna_value numeric value, if any).

values

A Numpy array with new values. It must have the dimensions for times and components, but may contain a different number of samples.

fill_missing_dates

Optionally, a boolean value indicating whether to fill missing dates (or indices in case of integer index) with NaN values. This requires either a provided freq or the possibility to infer the frequency from the provided timestamps. See _fill_missing_dates() for more info.

freq

Optionally, a string or integer representing the frequency of the underlying index. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True. If a string, represents the frequency of the pandas DatetimeIndex (see offset aliases for more info on supported frequencies). If an integer, represents the step size of the pandas Index or pandas RangeIndex.

fillna_value

Optionally, a numeric value to fill missing values (NaNs) with.

Returns

TimeSeries

A new series with the new time index and values but identical static covariates and hierarchy.

Return a new series similar to this one but with new values.

Parameters

values

A Numpy array with new values. It must have the dimensions for time and components, but may contain a different number of samples.

Returns

TimeSeries

A new series with the new values but same index, static covariates and hierarchy

Return a new series with added static covariates.

Static covariates hold information / data about the time series which does not vary over time.

Parameters

covariates

Optionally, a set of static covariates to be added to the TimeSeries. Either a pandas Series, a pandas DataFrame, or None. If None, will set the static covariates to None. If a Series, the index represents the static variables. The covariates are then globally 'applied' to all components of the TimeSeries. If a DataFrame, the columns represent the static variables and the rows represent the components of the uni/multivariate TimeSeries. If a single-row DataFrame, the covariates are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of rows must match the number of components of the TimeSeries. This adds component-specific static covariates.

Returns

TimeSeries

A new series with the given static covariates.

Notes

If there are a large number of static covariates variables (i.e., the static covariates have a very large dimension), there might be a noticeable performance penalty for creating TimeSeries, unless the covariates already have the same dtype as the series data.

Examples

>>> import pandas as pd
>>> from anomx._series_utils.timeseries_generation import linear_timeseries
>>> # add global static covariates
>>> static_covs = pd.Series([0., 1.], index=["static_cov_1", "static_cov_2"])
>>> series = linear_timeseries(length=3)
>>> series_new1 = series.with_static_covariates(static_covs)
>>> series_new1.static_covariates
                   static_cov_1  static_cov_2
component
linear              0.0           1.0

>>> # add component specific static covariates
>>> static_covs_multi = pd.DataFrame([[0., 1.], [2., 3.]], columns=["static_cov_1", "static_cov_2"])
>>> series_multi = series.stack(series)
>>> series_new2 = series_multi.with_static_covariates(static_covs_multi)
>>> series_new2.static_covariates
                   static_cov_1  static_cov_2
component
linear              0.0           1.0
linear_1            2.0           3.0

Return a new series with added hierarchy.

Parameters

hierarchy

A dictionary mapping components to a list of their parent(s) in the hierarchy. Single parents may be specified as string or list containing one string. For example, assume the series contains the components ["total", "a", "b", "x", "y", "ax", "ay", "bx", "by"], the following dictionary would encode the groupings shown on this figure:

hierarchy = {'ax': ['a', 'x'], 'ay': ['a', 'y'], 'bx': ['b', 'x'], 'by': ['b', 'y'], 'a': ['total'], 'b': ['total'], 'x': 'total', # or use a single string 'y': 'total'} ..

Returns

TimeSeries

A new series with the given hierarchy.

Return a new series with added metadata.

Parameters

metadata

A dictionary with metadata to be added to the TimeSeries.

Returns

TimeSeries

A new series with the given metadata.

Examples

>>> from anomx._series_utils.timeseries_generation import linear_timeseries
>>> series = linear_timeseries(length=3)
>>> # add metadata
>>> metadata = {'name': 'my_series'}
>>> series = series.with_metadata(metadata)
>>> series.metadata
{'name': 'my_series'}

Return a new series with the other series stacked to this series along the component axis.

The resulting TimeSeries will have the same name for its time dimension as this TimeSeries, and the same number of samples.

Parameters

other

A TimeSeries instance with the same index and the same number of samples as the current one.

Returns

TimeSeries

A new series with the components of the other series added to the original.

Return a new series with dropped components (columns).

Parameters

col_names

String or list of strings corresponding to the columns to be dropped.

Returns

TimeSeries

A new series with the specified columns dropped.

Return a new univariate series with a selected component.

This drops the hierarchy (if any), and retains only the relevant static covariates column.

Parameters

index

If a string, the name of the component to retrieve. If an integer, the positional index of the component.

Returns

TimeSeries

A new series with a selected component.

Return a new series with one (or more) additional component(s) that contain an attribute of the series' time index.

The additional components are specified with attribute, such as 'weekday', 'day' or 'month'.

This works only for deterministic time series (i.e., made of 1 sample).

Notes

0-indexing is enforced across all the encodings, see datetime_attribute_timeseries() for more information.

Parameters

attribute

A pandas.DatatimeIndex attribute which will serve as the basis of the new column(s).

one_hot

Boolean value indicating whether to add the specified attribute as a one hot encoding (results in more columns).

cyclic

Boolean value indicating whether to add the specified attribute as a cyclic encoding. Alternative to one_hot encoding, enable only one of the two. (adds 2 columns, corresponding to sin and cos transformation).

tz

Optionally, a time zone to convert the time index before computing attributes. Supports any type handled by pandas tz_convert.

Returns

TimeSeries

A new series with an added datetime attribute component(s).

Return a new series with an added holiday component.

The holiday component is binary where 1 corresponds to a time step falling on a holiday.

Available countries can be found here.

This works only for deterministic time series (i.e., made of 1 sample).

Parameters

country_code

The country ISO code

prov

The province

state

The state

tz

Optionally, a time zone to convert the time index before computing attributes. Supports any type handled by pandas tz_convert.

Returns

TimeSeries

A new series with an added holiday component.

Return a new series where the time index and values were resampled with a given frequency.

The provided method is used to aggregate/fill holes in the resampled series, by default 'pad'.

Parameters

freq

The new time difference between two adjacent entries in the returned TimeSeries. Expects a pandas.DateOffset or DateOffset alias.

method

A method to either aggregate grouped values (for down-sampling) or fill holes (for up-sampling) in the reindexed TimeSeries. For more information, see the xarray DataArrayResample documentation. Supported methods: ["all", "any", "asfreq", "backfill", "bfill", "count", "ffill", "first", "interpolate", "last", "max", "mean", "median", "min", "nearest", "pad", "prod", "quantile", "reduce", "std", "sum", "var"].

method_kwargs

Additional keyword arguments for the specified method. Some methods require additional arguments. Xarray's errors will be raised on invalid keyword arguments.

kwargs

some keyword arguments for the xarray.resample method, notably offset or base to indicate where to start the resampling and avoid nan at the first value of the resampled TimeSeries For more information, see the xarray resample() documentation.

Returns

TimeSeries

A resampled series with given frequency.

Examples

>>> times = pd.date_range(start=pd.Timestamp("20200101233000"), periods=6, freq="15min")
>>> pd_series = pd.Series(range(6), index=times)
>>> ts = TimeSeries.from_series(pd_series)
>>> print(ts.time_index)
DatetimeIndex(['2020-01-01 23:30:00', '2020-01-01 23:45:00',
               '2020-01-02 00:00:00', '2020-01-02 00:15:00',
               '2020-01-02 00:30:00', '2020-01-02 00:45:00'],
               dtype='datetime64[ns]', name='time', freq='15T')
>>> resampled_nokwargs_ts = ts.resample(freq="1h")
>>> print(resampled_nokwargs_ts.time_index)
DatetimeIndex(['2020-01-01 23:00:00', '2020-01-02 00:00:00'],
              dtype='datetime64[ns]', name='time', freq='H')
>>> print(resampled_nokwargs_ts.values())
[[nan]
[ 2.]]
>>> resampled_ts = ts.resample(freq="1h", offset=pd.Timedelta("30min"))
>>> print(resampled_ts.time_index)
DatetimeIndex(['2020-01-01 23:30:00', '2020-01-02 00:30:00'],
              dtype='datetime64[ns]', name='time', freq='H')
>>> print(resampled_ts.values())
[[0.]
[4.]]
>>> resampled_ts = ts.resample(freq="1h", offset=pd.Timedelta("30min"))
>>> downsampled_mean_ts = ts.resample(freq="30min", method="mean")
>>> print(downsampled_mean_ts.values())
[[0.5]
[2.5]
[4.5]]
>>> downsampled_reduce_ts = ts.resample(freq="30min", method="reduce", method_args={"func": np.mean})
>>> print(downsampled_reduce_ts.values())
[[0.5]
[2.5]
[4.5]]

Whether the given timestamp or integer is within the time interval of the series.

ts does not need to be an element of the series' time index.

Parameters

ts

The pandas.Timestamp (if indexed with DatetimeIndex) or integer (if indexed with RangeIndex) to check.

Returns

bool

Whether ts is contained within the interval of this series.

Return a new series with the function fn applied to the values of this series.

If fn takes 1 argument it is simply applied on the values array of shape (time, n_components, n_samples). If fn takes 2 arguments, it is applied on the (ts, values) tuple, where ts denotes the series' time index, and values denotes the series' array of values, of shape (n_timestamps, n_components, n_samples). Timestamp index's shape should be (n, 1, 1);

Parameters

fn

Either a function which takes a NumPy array and returns a NumPy array of same shape; e.g., lambda x: x ** 2, lambda x: x / x.shape[0] or np.log. It can also be a function which takes a timestamp and array, and returns a new array of same shape; e.g., lambda ts, x: x / ts.days_in_month. The type of ts is either pandas.Timestamp (if the series is indexed with a DatetimeIndex), or an integer otherwise (if the series is indexed with an RangeIndex).

Returns

TimeSeries

A new series with the function fn applied to the values.

Examples

>>> from anomx.data.timeseries import TimeSeries
>>> from anomx._series_utils.utils import generate_index
>>> # create a simple TimeSeries
>>> series = TimeSeries.from_times_and_values(
>>>     times=generate_index("2020-01-01", length=3, freq="D"),
>>>     values=range(3),
>>> )
>>> # map function on values only
>>> def fn1(values):
>>>     return values / 3.
>>>
>>> series.map(fn1).values()
array([[0.        ],
       [0.33333333],
       [0.66666667]])
>>>
>>> # map function on time index and values
>>> def fn2(times, values):
>>>     return values / times.days_in_month.values.reshape(-1, 1, 1)
>>>
>>> series.map(fn2).values()
array([[0.        ],
       [0.03225806],
       [0.06451613]])

Return a new series with the specified window transformations applied.

Supports moving/rolling, expanding or exponentially weighted window transformations.

Parameters

transforms

A dictionary or a list of dictionaries. Each dictionary specifies a different window transform.

The dictionaries can contain the following keys:

:"function": Mandatory. The name of one of the pandas builtin transformation functions, or a callable function that can be applied to the input series. Pandas' functions can be found in the documentation.

:"mode": Optional. The name of the pandas windowing mode on which the "function" is going to be applied. The options are "rolling", "expanding" and "ewm". If not provided, Anomx defaults to "expanding". User defined functions can use either "rolling" or "expanding" modes. More information on pandas windowing operations can be found in the documentation.

:"components": Optional. A string or list of strings specifying the TimeSeries components on which the transformation should be applied. If not specified, the transformation will be applied on all components.

:"function_name": Optional. A string specifying the function name referenced as part of the transformation output name. For example, given a user-provided function transformation on rolling window size of 5 on the component "comp", the default transformation output name is "rolling_udf_5_comp" whereby "udf" refers to "user defined function". If specified, the "function_name" will replace the default name "udf". Similarly, the "function_name" will replace the name of the pandas builtin transformation function name in the output name.

All other dictionary items provided will be treated as keyword arguments for the windowing mode (i.e., rolling/ewm/expanding) or for the specific function in that mode (i.e., pandas.DataFrame.rolling.mean/std/max/min... or pandas.DataFrame.ewm.mean/std/sum). This allows for more flexibility in configuring the transformation, by providing for

example

* :``"window"``: Size of the moving window for the "rolling" mode.
                If an integer, the fixed number of observations used for each window.
                If an offset, the time period of each window with data type :class:`pandas.Timedelta`
                representing a fixed duration.
* :``"min_periods"``: The minimum number of observations in the window required to have a value (otherwise
    NaN). Anomx reuses pandas defaults of 1 for "rolling" and "expanding" modes and of 0 for "ewm" mode.
* :``"win_type"``: The type of weigthing to apply to the window elements.
    If provided, it should be one of `scipy.signal.windows
    <https://docs.scipy.org/doc/scipy/reference/signal.windows.html#module-scipy.signal.windows>`__.
* :``"center"``: ``True``/``False`` to set the observation at the current timestep at the center of the
    window (when ``forecasting_safe`` is `True`, Anomx enforces ``"center"`` to ``False``).
* :``"closed"``: ``"right"``/``"left"``/``"both"``/``"neither"`` to specify whether the right,
    left or both ends of the window are included in the window, or neither of them.
    Anomx defaults to pandas default of ``"right"``.

More information on the available functions and their parameters can be found in the
`Pandas documentation <https://pandas.pydata.org/docs/reference/window.html>`__.

For user-provided functions, extra keyword arguments in the transformation dictionary are passed to the
user-defined function.
By default, Anomx expects user-defined functions to receive numpy arrays as input.
This can be modified by adding item ``"raw": False`` in the transformation dictionary.
It is expected that the function returns a single
value for each window. Other possible configurations can be found in the
`pandas.DataFrame.rolling().apply()
documentation <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.rolling.html>`__
and `pandas.DataFrame.expanding().apply()
documentation <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.expanding.html>`__.

treat_na Specifies how to treat missing values that were added by the window transformations at the beginning of the resulting TimeSeries. By default, Anomx will leave NaNs in the resulting TimeSeries. This parameter can be one of the following:

* :``"dropna"``: to truncate the TimeSeries and drop rows containing missing values.
    If multiple columns contain different numbers of missing values, only the minimum number
    of rows is dropped. This operation might reduce the length of the resulting TimeSeries.

* :``"bfill"`` or ``"backfill"``: to specify that NaNs should be filled with the last transformed
    and valid observation. If the original TimeSeries starts with NaNs, those are kept.
    When ``forecasting_safe`` is ``True``, this option returns an exception to avoid future observation
    contaminating the past.

* :an integer or float: in which case NaNs will be filled with this value.
    All columns will be filled with the same provided value.

forecasting_safe If True, Anomx enforces that the resulting TimeSeries is safe to be used in forecasting models as target or as feature. The window transformation will not allow future values to be included in the computations at their corresponding current timestep. Default is True. "ewm" and "expanding" modes are forecasting safe by default. "rolling" mode is forecasting safe if "center": False is guaranteed.

keep_non_transformed False to return the transformed components only, True to return all original components along the transformed ones. Default is False. If the series has a hierarchy, must be set to False.

include_current True to include the current time step in the window, False to exclude it. Default is True.

keep_names Whether the transformed components should keep the original component names or. Must be set to False if keep_non_transformed = True or the number of transformation is greater than 1.

Returns

TimeSeries

Returns a new series with the transformed components. If keep_non_transformed is True, the series will contain the original non-transformed components along the transformed ones. If the input series is stochastic, all samples are identically transformed. The naming convention for the transformed components is as follows: [window_mode]_[function_name]_[window_size if provided]_[min_periods if not default]_[original_comp_name], e.g., rolling_sum_3_comp_0 (i.e., window_mode= rolling, function_name = sum, window_size=3, original_comp_name=comp_0) ; ewm_mean_comp_1 (i.e., window_mode= ewm, function_name = mean, original_comp_name=comp_1); expanding_sum_3_comp_2 (i.e., window_mode= expanding, function_name = sum, window_size=3, original_comp_name=comp_2). For user-defined functions, function_name = udf.

Return a JSON string representation of the series.

The JSON string includes the series values, time index, component names, as well as static covariates, hierarchy, and metadata (if any).

Returns

str

A JSON String representing the series

See Also

TimeSeries.from_json : Create a TimeSeries from a JSON string.

Write the deterministic series to a CSV file.

For a list of parameters, refer to the documentation of pandas.DataFrame.to_csv() [1]_.

References

.. [1] https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_csv.html?highlight=to_csv

Save the series in pickle format.

Parameters

path : string

path to a file where current object will be pickled

protocol : integer, default highest

pickling protocol. The default is best in most cases, use it only if having backward compatibility issues

Plot the series using Matplotlib.

Parameters

new_plot

Whether to spawn a new axis to plot on. See also parameter ax.

central_quantile

The quantile (between 0 and 1) to plot as a "central" value, if the series is stochastic (i.e., if it has multiple samples). This will be applied on each component separately (i.e., to display quantiles of the components' marginal distributions). For instance, setting central_quantile=0.5 will plot the median of each component. central_quantile can also be set to 'mean'.

low_quantile

The quantile to use for the lower bound of the plotted confidence interval. Similar to central_quantile, this is applied to each component separately (i.e., displaying marginal distributions). No confidence interval is shown if low_quantile is None (default 0.05).

high_quantile

The quantile to use for the upper bound of the plotted confidence interval. Similar to central_quantile, this is applied to each component separately (i.e., displaying marginal distributions). No confidence interval is shown if high_quantile is None (default 0.95).

default_formatting

Whether to use the Anomx default scheme.

title

Optionally, a plot title.

label

Can either be a string or list of strings. If a string and the series only has a single component, it is used as the label for that component. If a string and the series has multiple components, it is used as a prefix for each component name. If a list of strings with length equal to the number of components in the series, the labels will be mapped to the components in order.

max_nr_components

The maximum number of components of a series to plot. -1 means all components will be plotted.

ax

Optionally, an axis to plot on. If None, and new_plot=False, will use the current axis. If new_plot=True, will create a new axis.

alpha

Optionally, set the line alpha for deterministic series, or the confidence interval alpha for probabilistic series.

color

Can either be a single color or list of colors. Any matplotlib color is accepted (string, hex string, RGB/RGBA tuple). If a single color and the series only has a single component, it is used as the color for that component. If a single color and the series has multiple components, it is used as the color for each component. If a list of colors with length equal to the number of components in the series, the colors will be mapped to the components in order.

c

An alias for color.

args

some positional arguments for the plot() method

kwargs

some keyword arguments for the plot() method

Returns

matplotlib.axes.Axes

Either the passed ax axis, a newly created one if new_plot=True, or the existing one.

Plot the series using Plotly.

Parameters

fig

Optionally, a Plotly go.Figure object to plot on. If provided, the series will be added to this figure. If None, a new figure will be created.

central_quantile

The quantile (between 0 and 1) to plot as a "central" value, if the series is stochastic (i.e., if it has multiple samples). This will be applied on each component separately (i.e., to display quantiles of the components' marginal distributions). For instance, setting central_quantile=0.5 will plot the median of each component. central_quantile can also be set to 'mean'.

low_quantile

The quantile to use for the lower bound of the plotted confidence interval. Similar to central_quantile, this is applied to each component separately (i.e., displaying marginal distributions). No confidence interval is shown if low_quantile is None (default 0.05).

high_quantile

The quantile to use for the upper bound of the plotted confidence interval. Similar to central_quantile, this is applied to each component separately (i.e., displaying marginal distributions). No confidence interval is shown if high_quantile is None (default 0.95).

title

Optionally, a plot title.

label

Can either be a string or list of strings. If a string and the series only has a single component, it is used as the label for that component. If a string and the series has multiple components, it is used as a prefix for each component name. If a list of strings with length equal to the number of components in the series, the labels will be mapped to the components in order.

max_nr_components

The maximum number of components of a series to plot. -1 means all components will be plotted.

alpha

Optionally, set the line alpha for deterministic series, or the confidence interval alpha for probabilistic series.

color

Set the line color(s). Can be a single color string (name or hex), or a sequence of strings (one per component). If a sequence, it must match the number of components. By default, colors are pulled from the active Plotly template.

c

An alias for color.

downsample_threshold

The maximum number of total data points (time steps * components * traces) to plot. If exceeded, the series will be automatically downsampled using a constant step size to avoid rendering crashes. Set to -1 to disable downsampling. Defaults to 100,000.

**kwargs

Additional keyword arguments to pass to plotly.graph_objects.Scatter() for trace customization (e.g., line_dash, line_width, marker_symbol, opacity, or hovertemplate).

Returns

plotly.graph_objects.Figure

The Plotly figure object containing the plot. Call .show() on the returned figure to display it.

Return a new series with new columns/components names.

It also adapts the names in the hierarchy, if any.

Parameters

col_names

String or list of strings corresponding the the column names to be changed.

col_names_new

String or list of strings corresponding to the new column names. Must be the same length as col_names.

Returns

TimeSeries

A new series with renamed columns.

Return a new series with the mean computed over the specified axis.

If we reduce over time (axis=0), the series will have length one and will use the first entry of the original time_index. If we perform the calculation over the components (axis=1), the resulting single component will be renamed to "components_mean". When applied to the samples (axis=2), a deterministic series is returned.

If axis=1, the static covariates and the hierarchy are discarded from the series.

Parameters

axis

The axis to reduce over. The default is to calculate over samples, i.e. axis=2.

Returns

TimeSeries

A new series with mean applied to the indicated axis.

Return a new series with the median computed over the specified axis.

If we reduce over time (axis=0), the series will have length one and will use the first entry of the original time_index. If we perform the calculation over the components (axis=1), the resulting single component will be renamed to "components_median". When applied to the samples (axis=2), a deterministic series is returned.

If axis=1, the static covariates and the hierarchy are discarded from the series.

Parameters

axis

The axis to reduce over. The default is to calculate over samples, i.e. axis=2.

Returns

TimeSeries

A new series with median applied to the indicated axis.

Return a new series with the sum computed over the specified axis.

If we reduce over time (axis=0), the series will have length one and will use the first entry of the original time_index. If we perform the calculation over the components (axis=1), the resulting single component will be renamed to "components_sum". When applied to the samples (axis=2), a deterministic series is returned.

If axis=1, the static covariates and the hierarchy are discarded from the series.

Parameters

axis

The axis to reduce over. The default is to calculate over samples, i.e. axis=2.

Returns

TimeSeries

A new series with sum applied to the indicated axis.

Return a new series with the minimum computed over the specified axis.

If we reduce over time (axis=0), the series will have length one and will use the first entry of the original time_index. If we perform the calculation over the components (axis=1), the resulting single component will be renamed to "components_min". When applied to the samples (axis=2), a deterministic series is returned.

If axis=1, the static covariates and the hierarchy are discarded from the series.

Parameters

axis

The axis to reduce over. The default is to calculate over samples, i.e. axis=2.

Returns

TimeSeries

A new series with min applied to the indicated axis.

Return a new series with the maximum computed over the specified axis.

If we reduce over time (axis=0), the series will have length one and will use the first entry of the original time_index. If we perform the calculation over the components (axis=1), the resulting single component will be renamed to "components_max". When applied to the samples (axis=2), a deterministic series is returned.

If axis=1, the static covariates and the hierarchy are discarded from the series.

Parameters

axis

The axis to reduce over. The default is to calculate over samples, i.e. axis=2.

Returns

TimeSeries

A new series with max applied to the indicated axis.

Return a deterministic series with the desired quantile(s) q of each component computed over the samples of the stochastic series.

The component quantiles in the new series are named "<component>_q<quantile>", where "<component>" is the column name, and "<quantile>" is the quantile value.

The order of the component quantiles is: [<c_1>_q<q_1>, ... <c_1>_q<q_2>, ..., <c_n>_q<q_n>].

This works only on stochastic series (i.e., with more than 1 sample).

Parameters

q

The desired quantile value or sequence of quantile values. Each value must be between 0. and 1. inclusive. For instance, 0.5 will return a TimeSeries containing the median of the (marginal) distribution of each component.

kwargs

Other keyword arguments are passed down to numpy.quantile().

Returns

TimeSeries

A new series containing the desired quantile(s) of each component.

Return a deterministic series with the variance of each component computed over the samples of the stochastic series.

This works only on stochastic series (i.e., with more than 1 sample)

Parameters

ddof

"Delta Degrees of Freedom": the divisor used in the calculation is N - ddof where N represents the number of elements. By default, ddof is 1.

Returns

TimeSeries

A new series containing the variance of each component.

Return a deterministic series with the standard deviation of each component computed over the samples of the stochastic series.

This works only on stochastic series (i.e., with more than 1 sample)

Parameters

ddof

"Delta Degrees of Freedom": the divisor used in the calculation is N - ddof where N represents the number of elements. By default, ddof is 1.

Returns

TimeSeries

A new series containing the standard deviation of each component.

Return a deterministic series with the skew of each component computed over the samples of the stochastic series.

This works only on stochastic series (i.e., with more than 1 sample)

Parameters

kwargs

Other keyword arguments are passed down to scipy.stats.skew()

Returns

TimeSeries

A new series containing the skew of each component.

Return a deterministic series with the kurtosis of each component computed over the samples of the stochastic series.

This works only on stochastic series (i.e., with more than 1 sample)

Parameters

kwargs

Other keyword arguments are passed down to scipy.stats.kurtosis()

Returns

TimeSeries

A new series containing the kurtosis of each component.