Timeseries¶

TimeSeries is the main class in darts. It represents a univariate or multivariate time series, deterministic or stochastic.

The values are stored in an array of shape (time, dimensions, samples), where dimensions are the dimensions (or “components”, or “columns”) of multivariate series, and samples are samples of stochastic series.

Definitions:

A series with dimensions = 1 is univariate and a series with dimensions > 1 is multivariate.
A series with samples = 1 is deterministic and a series with samples > 1 is

stochastic (or probabilistic).

Each series also stores a time_index, which contains either datetimes (pandas.DateTimeIndex) or integer indices (pandas.RangeIndex).

TimeSeries are guaranteed to:

Have a monotonically increasing time index, without holes (without missing dates)
Contain numeric types only
Have distinct components/columns names
Have a well-defined frequency (date offset aliases for DateTimeIndex, or step size for RangeIndex)
Have static covariates consistent with their components, or no static covariates
Have a hierarchy consistent with their components, or no hierarchy

TimeSeries can contain global or component-specific static covariate data. Static covariates in darts refers to external time-invariant data that can be used by some models to help improve predictions. Read our user guide on covariates and the TimeSeries documentation for more information on covariates.

class darts.timeseries.TimeSeries(xa, copy=True)[source]¶

Bases: object

Create a TimeSeries from a (well-formed) DataArray. It is recommended to use the factory methods to create TimeSeries instead.

See also

TimeSeries.from_dataframe: Create from a DataFrame (pandas.DataFrame, polars.DataFrame, and other backends).
TimeSeries.from_group_dataframe: Create multiple TimeSeries by groups from a pandas.DataFrame.
TimeSeries.from_series: Create from a Series (pandas.Series, polars.Series, and other backends).
TimeSeries.from_values: Create from a numpy.ndarray.
TimeSeries.from_times_and_values: Create from a time index and a numpy.ndarray.
TimeSeries.from_csv: Create from a CSV file.
TimeSeries.from_json: Create from a JSON file.
TimeSeries.from_xarray: Create from an xarray.DataArray.

Attributes

`bottom_level_components`	The bottom level component names of this series, or None if the series has no hierarchy.
`bottom_level_series`	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.
`columns`	The names of the components, as a Pandas Index.
`components`	The names of the components, as a Pandas Index.
`dtype`	The dtype of the series' values.
`duration`	The duration of this time series (as a time delta or int).
`freq`	The frequency of the series.
`freq_str`	The frequency string representation of the series.
`has_datetime_index`	Whether this series is indexed with a DatetimeIndex (otherwise it is indexed with an RangeIndex).
`has_hierarchy`	Whether this series is hierarchical or not.
`has_metadata`	Whether this series contains metadata.
`has_range_index`	Whether this series is indexed with an RangeIndex (otherwise it is indexed with a DatetimeIndex).
`has_static_covariates`	Whether this series contains static covariates.
`hierarchy`	The hierarchy of this TimeSeries, if any.
`is_deterministic`	Whether this series is deterministic.
`is_probabilistic`	Whether this series is stochastic (= probabilistic).
`is_stochastic`	Whether this series is stochastic.
`is_univariate`	Whether this series is univariate.
`metadata`	The metadata of this TimeSeries, if any.
`n_components`	Number of components (dimensions) contained in the series.
`n_samples`	Number of samples contained in the series.
`n_timesteps`	Number of time steps in the series.
`shape`	The shape of the series (n_timesteps, n_components, n_samples).
`static_covariates`	Returns the static covariates contained in the series as a pandas DataFrame.
`time_dim`	The name of the time dimension for this time series.
`time_index`	The time index of this time series.
`top_level_component`	The top level component name of this series, or None if the series has no hierarchy.
`top_level_series`	The univariate series containing the single top-level component of this series, or None if the series has no hierarchy.
`width`	"Width" (= number of components) of the series.

Methods

`add_datetime_attribute`(attribute[, one_hot, ...])	Build a new series with one (or more) additional component(s) that contain an attribute of the time index of the series.
`add_holidays`(country_code[, prov, state, tz])	Adds a binary univariate component to the current series that equals 1 at every index that corresponds to selected country's holiday, and 0 otherwise.
`all_values`([copy])	Return a 3-D array of dimension (time, component, sample), containing this series' values for all samples.
`append`(other)	Appends another series to this series along the time axis.
`append_values`(values)	Appends new values to current TimeSeries, extending its time index.
`astype`(dtype)	Converts this series to a new series with desired dtype.
`concatenate`(other[, axis, ignore_time_axis, ...])	Concatenate another timeseries to the current one along given axis.
`copy`()	Make a copy of this series.
`cumsum`()	Returns the cumulative sum of the time series along the time axis.
`data_array`([copy])	Return the `xarray.DataArray` representation underlying this series.
`diff`([n, periods, dropna])	Return a differenced time series.
`drop_after`(split_point)	Drops everything after the provided time split_point, included.
`drop_before`(split_point)	Drops everything before the provided time split_point, included.
`drop_columns`(col_names)	Return a new `TimeSeries` instance with dropped columns/components.
`end_time`()	End time of the series.
`first_value`()	First value of this univariate series.
`first_values`()	First values of this potentially multivariate series.
`from_csv`(filepath_or_buffer[, time_col, ...])	Build a deterministic TimeSeries instance built from a single CSV file.
`from_dataframe`(df[, time_col, value_cols, ...])	Build a deterministic TimeSeries instance built from a selection of columns of a DataFrame.
`from_group_dataframe`(df, group_cols[, ...])	Build a list of TimeSeries instances grouped by a selection of columns from a DataFrame.
`from_json`(json_str[, static_covariates, ...])	Build a series from the JSON String representation of a `TimeSeries` (produced using `TimeSeries.to_json()`).
`from_pickle`(path)	Read a pickled `TimeSeries`.
`from_series`(pd_series[, fill_missing_dates, ...])	Build a univariate deterministic TimeSeries from a Series.
`from_times_and_values`(times, values[, ...])	Build a series from a time index and value array.
`from_values`(values[, columns, fillna_value, ...])	Build an integer-indexed series from an array of values.
`from_xarray`(xa[, fill_missing_dates, freq, ...])	Return a TimeSeries instance built from an xarray DataArray.
`gaps`([mode])	A function to compute and return gaps in the TimeSeries.
`get_index_at_point`(point[, after])	Converts a point along the time axis index into an integer index ranging in (0, len(series)-1).
`get_timestamp_at_point`(point)	Converts a point into a pandas.Timestamp (if Datetime-indexed) or into an integer (if Int64-indexed).
`has_same_time_as`(other)	Checks whether this series has the same time index as other.
`head`([size, axis])	Return a TimeSeries containing the first size points.
`is_within_range`(ts)	Check whether a given timestamp or integer is within the time interval of this time series.
`kurtosis`(**kwargs)	Return a deterministic `TimeSeries` containing the kurtosis of each component (over the samples) of this stochastic `TimeSeries`.
`last_value`()	Last value of this univariate series.
`last_values`()	Last values of this potentially multivariate series.
`longest_contiguous_slice`([max_gap_size, mode])	Return the largest TimeSeries slice of this deterministic series that contains no gaps (contiguous all-NaN values) larger than max_gap_size.
`map`(fn)	Applies the function fn to the underlying NumPy array containing this series' values.
`max`([axis])	Return a `TimeSeries` containing the max calculated over the specified axis.
`mean`([axis])	Return a `TimeSeries` containing the mean calculated over the specified axis.
`median`([axis])	Return a `TimeSeries` containing the median calculated over the specified axis.
`min`([axis])	Return a `TimeSeries` containing the min calculated over the specified axis.
`plot`([new_plot, central_quantile, ...])	Plot the series.
`prepend`(other)	Prepends (i.e.
`prepend_values`(values)	Prepends (i.e.
`quantile`(quantile, **kwargs)	Return a deterministic `TimeSeries` containing the single desired quantile of each component (over the samples) of this stochastic `TimeSeries`.
`quantile_df`([quantile])	Return a Pandas DataFrame containing the single desired quantile of each component (over the samples).
`quantile_timeseries`([quantile])	Return a deterministic `TimeSeries` containing the single desired quantile of each component (over the samples) of this stochastic `TimeSeries`.
`quantiles_df`([quantiles])	Return a Pandas DataFrame containing the desired quantiles of each component (over the samples).
`random_component_values`([copy])	Return a 2-D array of shape (time, component), containing the values for one sample taken uniformly at random among this series' samples.
`resample`(freq[, method, method_kwargs])	Build a reindexed `TimeSeries` with a given frequency.
`rescale_with_value`(value_at_first_step)	Return a new `TimeSeries`, which is a multiple of this series such that the first value is value_at_first_step.
`shift`(n)	Shifts the time axis of this TimeSeries by n time steps.
`skew`(**kwargs)	Return a deterministic `TimeSeries` containing the skew of each component (over the samples) of this stochastic `TimeSeries`.
`slice`(start_ts, end_ts)	Return a new TimeSeries, starting later than start_ts and ending before end_ts.
`slice_intersect`(other)	Return a `TimeSeries` slice of this series, where the time index has been intersected with the one of the other series.
`slice_intersect_times`(other[, copy])	Return time index of this series, where the time index has been intersected with the one of the other series.
`slice_intersect_values`(other[, copy])	Return the sliced values of this series, where the time index has been intersected with the one of the other series.
`slice_n_points_after`(start_ts, n)	Return a new TimeSeries, starting a start_ts (inclusive) and having at most n points.
`slice_n_points_before`(end_ts, n)	Return a new TimeSeries, ending at end_ts (inclusive) and having at most n points.
`split_after`(split_point)	Splits the series in two, after a provided split_point.
`split_before`(split_point)	Splits the series in two, before a provided split_point.
`stack`(other)	Stacks another univariate or multivariate TimeSeries with the same time index on top of the current one (along the component axis).
`start_time`()	Start time of the series.
`static_covariates_values`([copy])	Return a 2-D array of dimension (component, static variable), containing the static covariate values of the TimeSeries.
`std`([ddof])	Return a deterministic `TimeSeries` containing the standard deviation of each component (over the samples) of this stochastic `TimeSeries`.
`strip`([how])	Return a `TimeSeries` slice of this deterministic time series, where NaN-containing entries at the beginning and the end of the series are removed.
`sum`([axis])	Return a `TimeSeries` containing the sum calculated over the specified axis.
`tail`([size, axis])	Return last size points of the series.
`to_csv`(args, *kwargs)	Writes this deterministic series to a CSV file.
`to_dataframe`([copy, backend, time_as_index, ...])	Return a DataFrame representation of this time series in a given backend.
`to_json`()	Return a JSON string representation of this deterministic series.
`to_pickle`(path[, protocol])	Save this series in pickle format.
`to_series`([copy, backend])	Return a Series representation of this time series in a given backend.
`univariate_component`(index)	Retrieve one of the components of the series and return it as new univariate `TimeSeries` instance.
`univariate_values`([copy, sample])	Return a 1-D Numpy array of shape (time,), containing this univariate series' values for one sample.
`values`([copy, sample])	Return a 2-D array of shape (time, component), containing this series' values for one sample.
`var`([ddof])	Return a deterministic `TimeSeries` containing the variance of each component (over the samples) of this stochastic `TimeSeries`.
`window_transform`(transforms[, treat_na, ...])	Applies a moving/rolling, expanding or exponentially weighted window transformation over this `TimeSeries`.
`with_columns_renamed`(col_names, col_names_new)	Return a new `TimeSeries` instance with new columns/components names.
`with_hierarchy`(hierarchy)	Adds a hierarchy to the TimeSeries.
`with_metadata`(metadata)	Adds metadata to the TimeSeries.
`with_static_covariates`(covariates)	Returns a new TimeSeries object with added static covariates.
`with_times_and_values`(times, values[, ...])	Return a new `TimeSeries` similar to this one but with new specified values.
`with_values`(values)	Return a new `TimeSeries` similar to this one but with new specified values.

add_datetime_attribute(attribute, one_hot=False, cyclic=False, tz=None)[source]¶

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

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 pd.DatatimeIndex attribute which will serve as the basis of the new column(s).
one_hot (bool) – Boolean value indicating whether to add the specified attribute as a one hot encoding (results in more columns).
cyclic (bool) – 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 (Optional[str, None]) – Optionally, a time zone to convert the time index to before computing the attributes.

Returns

New TimeSeries instance enhanced by attribute.

Return type

TimeSeries

add_holidays(country_code, prov=None, state=None, tz=None)[source]¶

Adds a binary univariate component to the current series that equals 1 at every index that corresponds to selected country’s holiday, and 0 otherwise.

The frequency of the TimeSeries is daily.

Available countries can be found here.

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

Parameters

country_code (str) – The country ISO code
prov (Optional[str, None]) – The province
state (Optional[str, None]) – The state
tz (Optional[str, None]) – Optionally, a time zone to convert the time index to before computing the attributes.

Returns

A new TimeSeries instance, enhanced with binary holiday component.

Return type

TimeSeries

all_values(copy=True)[source]¶

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

Parameters: copy (bool) – Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.
Returns: The values composing the time series.
Return type: numpy.ndarray

append(other)[source]¶

Appends another series to this series along the time axis.

Parameters: other (Self) – A second TimeSeries.
Returns: A new TimeSeries, obtained by appending the second TimeSeries to the first.
Return type: TimeSeries

See also

TimeSeries.concatenate: concatenate another series along a given axis.
TimeSeries.prepend: prepend (i.e. add to the beginning) another series along the time axis.

append_values(values)[source]¶

Appends new values to current TimeSeries, extending its time index.

Parameters: values (ndarray) – An array with the values to append.
Returns: A new TimeSeries with the new values appended
Return type: TimeSeries

astype(dtype)[source]¶

Converts this series to a new series with desired dtype.

Parameters: dtype (Union[str, dtype]) – A NumPy dtype (np.float32 or np.float64)
Returns: A TimeSeries having the desired dtype.
Return type: TimeSeries

property bottom_level_components: Optional[list[str]]¶

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

Return type: Optional[list[str], None]

property bottom_level_series: Optional[list[typing_extensions.Self]]¶

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 returned series is multivariate if there are multiple bottom components.

Return type: Optional[list[Self], None]

property columns: Index¶

The names of the components, as a Pandas Index.

Return type: Index

property components: Index¶

The names of the components, as a Pandas Index.

Return type: Index

concatenate(other, axis=0, ignore_time_axis=False, ignore_static_covariates=False, drop_hierarchy=True, drop_metadata=False)[source]¶

Concatenate another timeseries to the current one along 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

concatenated timeseries

Return type

TimeSeries

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.

copy()[source]¶

Make a copy of this series.

Returns: A copy of this time series.
Return type: TimeSeries

cumsum()[source]¶

Returns the cumulative sum of the time series along the time axis.

Returns: A new TimeSeries, with the cumulatively summed values.
Return type: TimeSeries

data_array(copy=True)[source]¶

Return the xarray.DataArray representation underlying this series.

Parameters: copy (bool) – Whether to return a copy of the series. Leave it to True unless you know what you are doing.
Returns: The xarray DataArray underlying this time series.
Return type: xarray.DataArray

diff(n=1, periods=1, dropna=True)[source]¶

Return a differenced time series. This is often used to make a time series stationary.

Parameters

n (Optional[int, None]) – Optionally, a positive integer indicating the number of differencing steps (default = 1). For instance, n=2 computes the second order differences.
periods (Optional[int, None]) – Optionally, periods to shift for calculating difference. For instance, periods=12 computes the difference between values at time t and times t-12.
dropna (Optional[bool, None]) – 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

A new TimeSeries, with the differenced values.

Return type

TimeSeries

drop_after(split_point)[source]¶

Drops everything after the provided time split_point, included. The timestamp may not be in the series. If it is, the timestamp will be dropped.

Parameters: split_point (Union[Timestamp, float, int]) – The timestamp that indicates cut-off time.
Returns: A new TimeSeries, after ts.
Return type: TimeSeries

drop_before(split_point)[source]¶

Drops everything before the provided time split_point, included. The timestamp may not be in the series. If it is, the timestamp will be dropped.

Parameters: split_point (Union[Timestamp, float, int]) – The timestamp that indicates cut-off time.
Returns: A new TimeSeries, after ts.
Return type: TimeSeries

drop_columns(col_names)[source]¶

Return a new TimeSeries instance with dropped columns/components.

Parameters: col_names (Union[list[str], str]) – String or list of strings corresponding to the columns to be dropped.
Returns: A new TimeSeries instance with specified columns dropped.
Return type: TimeSeries

property dtype¶: The dtype of the series’ values.

property duration: Union[Timedelta, int]¶

The duration of this time series (as a time delta or int).

Return type: Union[Timedelta, int]

end_time()[source]¶

End time of the series.

Returns: A timestamp containing the last time of the TimeSeries (if indexed by DatetimeIndex), or an integer (if indexed by RangeIndex)
Return type: Union[pandas.Timestamp, int]

first_value()[source]¶

First value of this univariate series.

Returns: The first value of this univariate deterministic time series
Return type: float

first_values()[source]¶

First values of this potentially multivariate series.

Returns: The first values of every component of this deterministic time series
Return type: np.ndarray

property freq: Union[DateOffset, int]¶

The frequency of the series. A pd.DateOffset if series is indexed with a pd.DatetimeIndex. An integer (step size) if series is indexed with a pd.RangeIndex.

Return type: Union[DateOffset, int]

property freq_str: str¶

The frequency string representation of the series.

Return type: str

classmethod from_csv(filepath_or_buffer, time_col=None, value_cols=None, fill_missing_dates=False, freq=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None, **kwargs)[source]¶

Build a deterministic TimeSeries instance built from a single 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 (Optional[str, None]) – 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 (Union[str, list[str], None]) – 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 (Optional[bool, None]) – 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 (Union[str, int, None]) – 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 (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.
static_covariates (Union[Series, DataFrame, None]) – 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 (Optional[dict, None]) –
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 (Optional[dict, None]) – Optionally, a dictionary with metadata to be added to the TimeSeries.
**kwargs – Optional arguments to be passed to pandas.read_csv function

Returns

A univariate or multivariate deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

Examples

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

classmethod from_dataframe(df, time_col=None, value_cols=None, fill_missing_dates=False, freq=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None)[source]¶

Build a deterministic TimeSeries instance built 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 (Union[ForwardRef, ForwardRef, ForwardRef]) – 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 (Optional[str, None]) – 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 (Union[list[str], str, None]) – 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 (Optional[bool, None]) – 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 (Union[str, int, None]) –
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 (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.
static_covariates (Union[Series, DataFrame, None]) – 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 (Optional[dict, None]) –
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 (Optional[dict, None]) – Optionally, a dictionary with metadata to be added to the TimeSeries.

Returns

A univariate or multivariate deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

Examples

>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.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)

classmethod from_group_dataframe(df, group_cols, time_col=None, value_cols=None, static_cols=None, metadata_cols=None, fill_missing_dates=False, freq=None, fillna_value=None, drop_group_cols=None, n_jobs=1, verbose=False)[source]¶

Build a list of TimeSeries instances 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 (DataFrame) – The DataFrame
group_cols (Union[list[str], str]) – A string or list of strings representing the columns from the DataFrame by which to extract the individual TimeSeries groups.
time_col (Optional[str, None]) – 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 (Union[str, list[str], None]) – 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 (Union[str, list[str], None]) – 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 Darts models that support it.
metadata_cols (Union[str, list[str], None]) – Same as static_cols but appended as metadata to the resulting TimeSeries groups. Metadata will never be used by the underlying Darts models.
fill_missing_dates (Optional[bool, None]) – 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 (Union[str, int, None]) –
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 (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.
drop_group_cols (Union[str, list[str], None]) – Optionally, a string or list of strings with group_cols column(s) to exclude from the static covariates.
n_jobs (Optional[int, None]) – Optionally, an integer representing the number of parallel jobs to run. Behavior is the same as in the joblib.Parallel class.
verbose (Optional[bool, None]) – Optionally, a boolean value indicating whether to display a progress bar.

Returns

A list containing a univariate or multivariate deterministic TimeSeries per group in the DataFrame.

Return type

List[TimeSeries]

Examples

>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.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))

classmethod from_json(json_str, static_covariates=None, hierarchy=None, metadata=None)[source]¶

Build a series from the JSON String representation of a TimeSeries (produced using TimeSeries.to_json()).

At the moment this only supports deterministic time series (i.e., made of 1 sample).

Parameters

json_str (str) – The JSON String to convert
static_covariates (Union[Series, DataFrame, None]) – 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 (Optional[dict, None]) –
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 (Optional[dict, None]) – Optionally, a dictionary with metadata to be added to the TimeSeries.

Returns

The time series object converted from the JSON String

Return type

TimeSeries

Examples

>>> from darts 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("data.csv")
>>> series.shape
(3, 1, 1)

classmethod from_pickle(path)[source]¶

Read a pickled TimeSeries.

Parameters: path (string) – path pointing to a pickle file that will be loaded
Returns: timeseries object loaded from file
Return type: TimeSeries

Notes

Xarray docs [1] suggest not using pickle as a long-term data storage.

References

1: http://xarray.pydata.org/en/stable/user-guide/io.html#pickle

classmethod from_series(pd_series, fill_missing_dates=False, freq=None, fillna_value=None, static_covariates=None, metadata=None)[source]¶

Build a univariate deterministic 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 (NativeSeries) –
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 (Optional[bool, None]) – 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 (Union[str, int, None]) –
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 (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.
static_covariates (Union[Series, DataFrame, None]) – 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 (Optional[dict, None]) – Optionally, a dictionary with metadata to be added to the TimeSeries.

Returns

A univariate and deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

Examples

>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.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)

classmethod from_times_and_values(times, values, fill_missing_dates=False, freq=None, columns=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None)[source]¶

Build a series from a time index and value array.

Parameters

times (Union[DatetimeIndex, RangeIndex, Index]) – 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 (ndarray) – 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).
fill_missing_dates (Optional[bool, None]) – 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 (Union[str, int, None]) –
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 (Union[ForwardRef, ndarray, ForwardRef, ForwardRef, SequenceNotStr, range, None]) – Columns to be used by the underlying pandas DataFrame.
fillna_value (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.
static_covariates (Union[Series, DataFrame, None]) – 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 (Optional[dict, None]) –
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 (Optional[dict, None]) – Optionally, a dictionary with metadata to be added to the TimeSeries.

Returns

A TimeSeries constructed from the inputs.

Return type

TimeSeries

Examples

>>> import numpy as np
>>> from darts import TimeSeries
>>> from darts.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)

classmethod from_values(values, columns=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None)[source]¶

Build an integer-indexed series from an array of values. The series will have an integer index (RangeIndex).

Parameters

values (ndarray) – 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 (Union[ForwardRef, ndarray, ForwardRef, ForwardRef, SequenceNotStr, range, None]) – Columns to be used by the underlying pandas DataFrame.
fillna_value (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.
static_covariates (Union[Series, DataFrame, None]) – 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 (Optional[dict, None]) –
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 (Optional[dict, None]) – Optionally, a dictionary with metadata to be added to the TimeSeries.

Returns

A TimeSeries constructed from the inputs.

Return type

TimeSeries

Examples

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

classmethod from_xarray(xa, fill_missing_dates=False, freq=None, fillna_value=None)[source]¶

Return a TimeSeries instance built 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 (DataArray) – The xarray DataArray
fill_missing_dates (Optional[bool, None]) – 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 (Union[str, int, None]) –
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 (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

A univariate or multivariate deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

Examples

>>> import xarray as xr
>>> import numpy as np
>>> from darts.timeseries import DIMS
>>> from darts import TimeSeries
>>> from darts.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)

gaps(mode='all')[source]¶

A function to compute and return gaps in the TimeSeries. Works only on deterministic time series (1 sample).

Parameters: mode (Literal[‘all’, ‘any’]) – 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: 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).
Return type: pd.DataFrame

get_index_at_point(point, after=True)[source]¶

Converts a point along the time axis index into an integer index ranging in (0, len(series)-1).

Parameters

point (Union[Timestamp, float, int]) –
This parameter supports 3 different data types: pd.Timestamp, float and int.

pd.Timestamp work only on series that are indexed with a pd.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.

Return type

int

get_timestamp_at_point(point)[source]¶

Converts a point into a pandas.Timestamp (if Datetime-indexed) or into an integer (if Int64-indexed).

Parameters: point (Union[Timestamp, float, int]) – 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.
Return type: Union[Timestamp, int]

property has_datetime_index: bool¶

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

Return type: bool

property has_hierarchy: bool¶

Whether this series is hierarchical or not.

Return type: bool

property has_metadata: bool¶

Whether this series contains metadata.

Return type: bool

property has_range_index: bool¶

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

Return type: bool

has_same_time_as(other)[source]¶

Checks whether this series has the same time index as other.

Parameters: other (Self) – the other series
Returns: True if both TimeSeries have the same index, False otherwise.
Return type: bool

property has_static_covariates: bool¶

Whether this series contains static covariates.

Return type: bool

head(size=5, axis=0)[source]¶

Return a TimeSeries containing 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

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

Return type

TimeSeries

property hierarchy: Optional[dict]¶

The hierarchy of this TimeSeries, if any. If set, the hierarchy is encoded as a dictionary, whose keys are individual components and values are the set of parent(s) of these components in the hierarchy.

Return type: Optional[dict, None]

property is_deterministic: bool¶

Whether this series is deterministic.

Return type: bool

property is_probabilistic: bool¶

Whether this series is stochastic (= probabilistic).

Return type: bool

property is_stochastic: bool¶

Whether this series is stochastic.

Return type: bool

property is_univariate: bool¶

Whether this series is univariate.

Return type: bool

is_within_range(ts)[source]¶

Check whether a given timestamp or integer is within the time interval of this time series. If a timestamp is provided, it does not need to be an element of the time index of the series.

Parameters: ts (Union[Timestamp, int]) – The pandas.Timestamp (if indexed with DatetimeIndex) or integer (if indexed with RangeIndex) to check.
Returns: Whether ts is contained within the interval of this time series.
Return type: bool

kurtosis(**kwargs)[source]¶

Return a deterministic TimeSeries containing the kurtosis of each component (over the samples) of this stochastic TimeSeries.

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: The TimeSeries containing the kurtosis for each component.
Return type: TimeSeries

last_value()[source]¶

Last value of this univariate series.

Returns: The last value of this univariate deterministic time series
Return type: float

last_values()[source]¶

Last values of this potentially multivariate series.

Returns: The last values of every component of this deterministic time series
Return type: np.ndarray

longest_contiguous_slice(max_gap_size=0, mode='all')[source]¶

Return the largest TimeSeries slice of this deterministic series that contains no gaps (contiguous all-NaN values) larger than max_gap_size.

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

Parameters

max_gap_size (int) – Indicate the maximum gap size that the TimeSerie can contain
mode (str) – 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

a new series constituting the largest slice of the original with no or bounded gaps

Return type

TimeSeries

See also

TimeSeries.gaps: return the gaps in the TimeSeries

map(fn)[source]¶

Applies the function fn to the underlying NumPy array containing this series’ values.

Return a new TimeSeries instance. If fn takes 1 argument it is simply applied on the backing array of shape (time, n_components, n_samples). If it takes 2 arguments, it is applied repeatedly on the (ts, value[ts]) tuples, where “ts” denotes a timestamp value, and “value[ts]” denote the array of values at this timestamp, of shape (n_components, n_samples).

Parameters: fn (Union[Callable[[number], number], Callable[[Union[Timestamp, int], number], number]]) – 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 pd.Timestamp (if the series is indexed with a DatetimeIndex), or an integer otherwise (if the series is indexed with an RangeIndex).
Returns: A new TimeSeries instance
Return type: TimeSeries

max(axis=2)[source]¶

Return a TimeSeries containing the max calculated over the specified axis.

If we reduce over time (axis=0), the resulting TimeSeries 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 TimeSeries is returned.

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

Parameters: axis (int) – The axis to reduce over. The default is to calculate over samples, i.e. axis=2.
Returns: A new TimeSeries with max applied to the indicated axis.
Return type: TimeSeries

mean(axis=2)[source]¶

Return a TimeSeries containing the mean calculated over the specified axis.

If we reduce over time (axis=0), the resulting TimeSeries 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 TimeSeries is returned.

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

Parameters: axis (int) – The axis to reduce over. The default is to calculate over samples, i.e. axis=2.
Returns: A new TimeSeries with mean applied to the indicated axis.
Return type: TimeSeries

median(axis=2)[source]¶

Return a TimeSeries containing the median calculated over the specified axis.

If we reduce over time (axis=0), the resulting TimeSeries 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 TimeSeries is returned.

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

Parameters: axis (int) – The axis to reduce over. The default is to calculate over samples, i.e. axis=2.
Returns: A new TimeSeries with median applied to the indicated axis.
Return type: TimeSeries

property metadata: Optional[dict]¶

The metadata of this TimeSeries, if any.

Return type: Optional[dict, None]

min(axis=2)[source]¶

Return a TimeSeries containing the min calculated over the specified axis.

If we reduce over time (axis=0), the resulting TimeSeries 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 TimeSeries is returned.

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

Parameters: axis (int) – The axis to reduce over. The default is to calculate over samples, i.e. axis=2.
Returns: A new TimeSeries with min applied to the indicated axis.
Return type: TimeSeries

property n_components: int¶

Number of components (dimensions) contained in the series.

Return type: int

property n_samples: int¶

Number of samples contained in the series.

Return type: int

property n_timesteps: int¶

Number of time steps in the series.

Return type: int

plot(new_plot=False, central_quantile=0.5, low_quantile=0.05, high_quantile=0.95, default_formatting=True, title=None, label='', max_nr_components=10, ax=None, alpha=None, color=None, c=None, *args, **kwargs)[source]¶

Plot the series.

This is a wrapper method around xarray.DataArray.plot().

Parameters

new_plot (bool) – Whether to spawn a new axis to plot on. See also parameter ax.
central_quantile (Union[float, str]) – 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 (Optional[float, None]) – 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 confidence_low_quantile is None (default 0.05).
high_quantile (Optional[float, None]) – 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 (bool) – Whether to use the darts default scheme.
title (Optional[str, None]) – Optionally, a custom plot title. If None, will use the name of the underlying xarray.DataArray.
label (Union[str, Sequence[str], None]) – 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 (int) – The maximum number of components of a series to plot. -1 means all components will be plotted.
ax (Optional[Axes, None]) – 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 (Optional[float, None]) – Optionally, set the line alpha for deterministic series, or the confidence interval alpha for probabilistic series.
color (Union[str, tuple, Sequence[str, tuple], None]) – 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 (Union[str, tuple, Sequence[str, tuple], None]) – An alias for color.
args – some positional arguments for the plot() method
kwargs – some keyword arguments for the plot() method

Returns

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

Return type

matplotlib.axes.Axes

prepend(other)[source]¶

Prepends (i.e. adds to the beginning) another series to this series along the time axis.

Parameters: other (Self) – A second TimeSeries.
Returns: A new TimeSeries, obtained by appending the second TimeSeries to the first.
Return type: TimeSeries

See also

Timeseries.append: append (i.e. add to the end) another series along the time axis.
TimeSeries.concatenate: concatenate another series along a given axis.

prepend_values(values)[source]¶

Prepends (i.e. adds to the beginning) new values to current TimeSeries, extending its time index into the past.

Parameters: values (ndarray) – An array with the values to prepend to the start.
Returns: A new TimeSeries with the new values prepended.
Return type: TimeSeries

quantile(quantile, **kwargs)[source]¶

Return a deterministic TimeSeries containing the single desired quantile of each component (over the samples) of this stochastic TimeSeries.

The components in the new series are named “<component>_X”, where “<component>” is the column name corresponding to this component, and “X” is the quantile value. The quantile columns represent the marginal distributions of the components of this series.

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

Parameters

quantile (float) – The desired quantile value. The value must be represented as a fraction (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

The TimeSeries containing the desired quantile for each component.

Return type

TimeSeries

quantile_df(quantile=0.5)[source]¶

Return a Pandas DataFrame containing the single desired quantile of each component (over the samples).

Each of the series components will appear as a column in the DataFrame. The column will be named “<component>_X”, where “<component>” is the column name corresponding to this component, and “X” is the quantile value. The quantile columns represent the marginal distributions of the components of this series.

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

Parameters: quantile – The desired quantile value. The value must be represented as a fraction (between 0 and 1 inclusive). For instance, 0.5 will return a DataFrame containing the median of the (marginal) distribution of each component.
Returns: The Pandas DataFrame containing the desired quantile for each component.
Return type: pandas.DataFrame

quantile_timeseries(quantile=0.5, **kwargs)[source]¶

Return a deterministic TimeSeries containing the single desired quantile of each component (over the samples) of this stochastic TimeSeries.

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

Parameters

quantile – The desired quantile value. The value must be represented as a fraction (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

The TimeSeries containing the desired quantile for each component.

Return type

TimeSeries

quantiles_df(quantiles=(0.1, 0.5, 0.9))[source]¶

Return a Pandas DataFrame containing the desired quantiles of each component (over the samples).

Each of the series components will appear as a column in the DataFrame. The column will be named “<component>_X”, where “<component>” is the column name corresponding to this component, and “X” is the quantile value. The quantiles represent the marginal distributions of the components of this series.

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

Parameters: quantiles (tuple[float]) – Tuple containing the desired quantiles. The values must be represented as fractions (between 0 and 1 inclusive). For instance, (0.1, 0.5, 0.9) will return a DataFrame containing the 10th-percentile, median and 90th-percentile of the (marginal) distribution of each component.
Returns: The Pandas DataFrame containing the quantiles for each component.
Return type: pandas.DataFrame

random_component_values(copy=True)[source]¶

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

Parameters: copy (bool) – Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.
Returns: The values composing one sample taken at random from the time series.
Return type: numpy.ndarray

resample(freq, method='pad', method_kwargs=None, **kwargs)[source]¶

Build a reindexed TimeSeries with a given frequency. Provided method is used to aggregate/fill holes in the reindexed TimeSeries, by default ‘pad’.

Parameters

freq (Union[str, DateOffset]) – The new time difference between two adjacent entries in the returned TimeSeries. Expects a pandas.DateOffset or DateOffset alias.
method (str) – 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 (Optional[dict[str, Any], None]) – 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

A reindexed TimeSeries with given frequency.

Return type

TimeSeries

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]]

rescale_with_value(value_at_first_step)[source]¶

Return a new TimeSeries, 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 (float) – The new value for the first entry of the TimeSeries.
Returns: A new TimeSeries, where the first value is value_at_first_step and other values have been scaled accordingly.
Return type: TimeSeries

property shape: tuple[int]¶

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

Return type: tuple[int]

shift(n)[source]¶

Shifts the time axis of this TimeSeries by n time steps.

If \(n > 0\), shifts in the future. If \(n < 0\), shifts in 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 (int) – The number of time steps (in self.freq unit) to shift by. Can be negative.
Returns: A new TimeSeries, with a shifted index.
Return type: TimeSeries

skew(**kwargs)[source]¶

Return a deterministic TimeSeries containing the skew of each component (over the samples) of this stochastic TimeSeries.

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: The TimeSeries containing the skew for each component.
Return type: TimeSeries

slice(start_ts, end_ts)[source]¶

Return a new TimeSeries, starting later than 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 (Union[Timestamp, int]) – The timestamp that indicates the left cut-off.
end_ts (Union[Timestamp, int]) – The timestamp that indicates the right cut-off.

Returns

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

Return type

TimeSeries

slice_intersect(other)[source]¶

Return a TimeSeries slice of this series, where the time index has been intersected with the one of the other series.

This method is in general not symmetric.

Parameters: other (Self) – the other time series
Returns: a new series, containing the values of this series, over the time-span common to both time series.
Return type: TimeSeries

slice_intersect_times(other, copy=True)[source]¶

Return time index of this series, where the time index has been intersected with the one of the other series.

This method is in general not symmetric.

Parameters

other (Self) – The other time series
copy (bool) – 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

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

Return type

Union[pd.DatetimeIndex, pd.RangeIndex]

slice_intersect_values(other, copy=False)[source]¶

Return the sliced values of this series, where the time index has been intersected with the one of the other series.

This method is in general not symmetric.

Parameters

other (Self) – The other time series
copy (bool) – Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.

Returns

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

Return type

np.ndarray

slice_n_points_after(start_ts, n)[source]¶

Return a new TimeSeries, starting a start_ts (inclusive) and having at most n points.

The provided timestamps will be included in the series.

Parameters

start_ts (Union[Timestamp, int]) – The timestamp or index that indicates the splitting time.
n (int) – The maximal length of the new TimeSeries.

Returns

A new TimeSeries, with length at most n, starting at start_ts

Return type

TimeSeries

slice_n_points_before(end_ts, n)[source]¶

Return a new TimeSeries, ending at end_ts (inclusive) and having at most n points.

The provided timestamps will be included in the series.

Parameters

end_ts (Union[Timestamp, int]) – The timestamp or index that indicates the splitting time.
n (int) – The maximal length of the new TimeSeries.

Returns

A new TimeSeries, with length at most n, ending at start_ts

Return type

TimeSeries

split_after(split_point)[source]¶

Splits the series in two, after a provided split_point.

Parameters: split_point (Union[Timestamp, float, int]) – 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 pd.Timestamp can be provided for TimeSeries that are indexed by a pd.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: A tuple of two time series. The first time series contains the first samples up to the split_point, and the second contains the remaining ones.
Return type: Tuple[TimeSeries, TimeSeries]

split_before(split_point)[source]¶

Splits the series in two, before a provided split_point.

Parameters: split_point (Union[Timestamp, float, int]) – 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 pd.Timestamp can be provided for TimeSeries that are indexed by a pd.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: A tuple of two time series. The first time series contains the first samples up to the split_point, and the second contains the remaining ones.
Return type: Tuple[TimeSeries, TimeSeries]

stack(other)[source]¶

Stacks another univariate or multivariate TimeSeries with the same time index on top of the current one (along the component axis).

Return a new TimeSeries that includes all the components of self and of other.

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

Parameters: other (Self) – A TimeSeries instance with the same index and the same number of samples as the current one.
Returns: A new multivariate TimeSeries instance.
Return type: TimeSeries

start_time()[source]¶

Start time of the series.

Returns: A timestamp containing the first time of the TimeSeries (if indexed by DatetimeIndex), or an integer (if indexed by RangeIndex)
Return type: Union[pandas.Timestamp, int]

property static_covariates: Optional[DataFrame]¶

Returns the static covariates contained in the series as a pandas DataFrame. The columns represent the static variables and the rows represent the components of the uni/multivariate series.

Return type: Optional[DataFrame, None]

static_covariates_values(copy=True)[source]¶

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

Parameters: copy (bool) – 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: The static covariate values if the series has static covariates, else None.
Return type: Optional[numpy.ndarray]

std(ddof=1)[source]¶

Return a deterministic TimeSeries containing the standard deviation of each component (over the samples) of this stochastic TimeSeries.

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

Parameters: ddof (int) – “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: The TimeSeries containing the standard deviation for each component.
Return type: TimeSeries

strip(how='all')[source]¶

Return a TimeSeries slice of this deterministic time series, where NaN-containing entries at the beginning and the end of the series are 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 (str) – Define if the entries containing NaN in all the components (‘all’) or in any of the components (‘any’) should be stripped. Default: ‘all’
Returns: a new series based on the original where NaN-containing entries at start and end have been removed
Return type: TimeSeries

sum(axis=2)[source]¶

Return a TimeSeries containing the sum calculated over the specified axis.

If we reduce over time (axis=0), the resulting TimeSeries 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 TimeSeries is returned.

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

Parameters: axis (int) – The axis to reduce over. The default is to calculate over samples, i.e. axis=2.
Returns: A new TimeSeries with sum applied to the indicated axis.
Return type: TimeSeries

tail(size=5, axis=0)[source]¶

Return last size points of the series.

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

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

Return type

TimeSeries

property time_dim: str¶

The name of the time dimension for this time series.

Return type: str

property time_index: Union[DatetimeIndex, RangeIndex]¶

The time index of this time series.

Return type: Union[DatetimeIndex, RangeIndex]

to_csv(*args, **kwargs)[source]¶

Writes this 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

to_dataframe(copy=True, backend=Implementation.PANDAS, time_as_index=True, suppress_warnings=False)[source]¶

Return a DataFrame representation of this time 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 (bool) – Whether to return a copy of the dataframe. Leave it to True unless you know what you are doing.
backend (Union[module, Implementation, str]) –
The backend to which to export the TimeSeries. See the narwhals documentation for all supported backends.
time_as_index (bool) – 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 (bool) – Whether to suppress the warnings for the DataFrame creation.

Returns

A DataFrame representation of this time series in the given backend.

Return type

DataFrame

to_json()[source]¶

Return a JSON string representation of this deterministic series.

At the moment this function works only on deterministic time series (i.e., made of 1 sample).

Notes

Static covariates are not returned in the JSON string. When using TimeSeries.from_json(), the static covariates can be added with input argument static_covariates.

Returns: A JSON String representing the time series
Return type: str

to_pickle(path, protocol=5)[source]¶

Save this 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

Notes

Xarray docs [1] suggest not using pickle as a long-term data storage.

References

1: http://xarray.pydata.org/en/stable/user-guide/io.html#pickle

to_series(copy=True, backend=Implementation.PANDAS)[source]¶

Return a Series representation of this time series in a given backend.

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

Parameters

copy (bool) – Whether to return a copy of the series. Leave it to True unless you know what you are doing.
backend (Union[module, Implementation, str]) –
The backend to which to export the TimeSeries. See the narwhals documentation for all supported backends.

Return type

A Series representation of this univariate time series in a given backend.

property top_level_component: Optional[str]¶

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

Return type: Optional[str, None]

property top_level_series: Optional[Self]¶

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

Return type: Optional[Self, None]

univariate_component(index)[source]¶

Retrieve one of the components of the series and return it as new univariate TimeSeries instance.

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

Parameters: index (Union[str, int]) – An zero-indexed integer indicating which component to retrieve. If components have names, this can be a string with the component’s name.
Returns: A new univariate TimeSeries instance.
Return type: TimeSeries

univariate_values(copy=True, sample=0)[source]¶

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

Parameters

copy (bool) – Whether to return a copy of the values. Leave it to True unless you know what you are doing.
sample (int) – For stochastic series, the sample for which to return values. Default: 0 (first sample).

Returns

The values composing the time series guaranteed to be univariate.

Return type

numpy.ndarray

values(copy=True, sample=0)[source]¶

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

Parameters

copy (bool) – Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.
sample (int) – For stochastic series, the sample for which to return values. Default: 0 (first sample).

Returns

The values composing the time series.

Return type

numpy.ndarray

var(ddof=1)[source]¶

Return a deterministic TimeSeries containing the variance of each component (over the samples) of this stochastic TimeSeries.

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

Parameters: ddof (int) – “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: The TimeSeries containing the variance for each component.
Return type: TimeSeries

property width: int¶

“Width” (= number of components) of the series.

Return type: int

window_transform(transforms, treat_na=None, forecasting_safe=True, keep_non_transformed=False, include_current=True, keep_names=False)[source]¶

Applies a moving/rolling, expanding or exponentially weighted window transformation over this TimeSeries.

Parameters

transforms (Union[dict, Sequence[dict]]) –
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, Darts 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 pandas.Timedelta representing a fixed duration.
- "min_periods"
  
  The minimum number of observations in the window required to have a value (otherwise NaN). Darts 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.
- "center"
  
  True/False to set the observation at the current timestep at the center of the window (when forecasting_safe is True, Darts 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. Darts defaults to pandas default of "right".
More information on the available functions and their parameters can be found in the Pandas documentation.

For user-provided functions, extra keyword arguments in the transformation dictionary are passed to the user-defined function. By default, Darts 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 and pandas.DataFrame.expanding().apply() documentation.
treat_na (Union[str, int, float, None]) –
Specifies how to treat missing values that were added by the window transformations at the beginning of the resulting TimeSeries. By default, Darts 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 (Optional[bool, None]) – If True, Darts 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 (Optional[bool, None]) – 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 (Optional[bool, None]) – True to include the current time step in the window, False to exclude it. Default is True.
keep_names (Optional[bool, None]) – 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

Returns a new TimeSeries instance with the transformed components. If keep_non_transformed is True, the resulting TimeSeries 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 type

TimeSeries

with_columns_renamed(col_names, col_names_new)[source]¶

Return a new TimeSeries instance with new columns/components names. It also adapts the names in the hierarchy, if any.

Parameters

col_names (Union[list[str], str]) – String or list of strings corresponding the the column names to be changed.
col_names_new (Union[list[str], str]) – String or list of strings corresponding to the new column names. Must be the same length as col_names.

Returns

A new TimeSeries instance.

Return type

TimeSeries

with_hierarchy(hierarchy)[source]¶

Adds a hierarchy to the TimeSeries.

Parameters

hierarchy (dict[str, Union[str, list[str]]]) –

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

A new TimeSeries with the given hierarchy.

Return type

TimeSeries

with_metadata(metadata)[source]¶

Adds metadata to the TimeSeries.

Parameters: metadata (Optional[dict, None]) – A dictionary with metadata to be added to the TimeSeries.
Returns: A new TimeSeries with the given metadata.
Return type: TimeSeries

Examples

>>> from darts.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'}

with_static_covariates(covariates)[source]¶

Returns a new TimeSeries object with added static covariates.

Static covariates contain data attached to the time series, but which are not varying with time.

Parameters: covariates (Union[Series, DataFrame, None]) – 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: A new TimeSeries with the given static covariates.
Return type: TimeSeries

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 objects, unless the covariates already have the same dtype as the series data.

Examples

>>> import pandas as pd
>>> from darts.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

with_times_and_values(times, values, fill_missing_dates=False, freq=None, fillna_value=None)[source]¶

Return a new TimeSeries similar to this one but with new specified values.

Parameters

times (Union[DatetimeIndex, RangeIndex, Index]) – 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 (ndarray) – 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 (Optional[bool, None]) – 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 (Union[str, int, None]) –
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 (Optional[float, None]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

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

Return type

TimeSeries

with_values(values)[source]¶

Return a new TimeSeries similar to this one but with new specified values.

Parameters: values (ndarray) – A Numpy array with new values. It must have the dimensions for time and componentns, but may contain a different number of samples.
Returns: A new TimeSeries with the new values and same index, static covariates and hierarchy
Return type: TimeSeries

darts.timeseries.concatenate(series, axis=0, ignore_time_axis=False, ignore_static_covariates=False, drop_hierarchy=True, drop_metadata=False)[source]¶

Concatenates multiple TimeSeries along a given axis.

axis can be an integer in (0, 1, 2) to denote (time, component, sample) or, alternatively, a string denoting the corresponding dimension of the underlying DataArray.

Parameters

series (Sequence[TimeSeries]) – Sequence of TimeSeries to concatenate
axis (Union[str, int]) – Axis along which the series will be concatenated.
ignore_time_axis (bool) – Allow concatenation even when some series do not have matching time axes. When done along component or sample dimensions, concatenation will work as long as the series have the same lengths (in this case the resulting series will have the time axis of the first provided series). When done along time dimension, concatenation will work even if the time axes are not contiguous (in this case, the resulting series will have a start time matching the start time of the first provided series). Default: False.
ignore_static_covariates (bool) – Whether to ignore all requirements for static covariate concatenation and only transfer the static covariates of the first TimeSeries element in series 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 series. False by default. When False, the concatenated series will inherit the metadata from the first TimeSeries element in series.

Returns

concatenated series

Return type

TimeSeries

darts.timeseries.slice_intersect(series)[source]¶

Returns a list of TimeSeries, where all series have been intersected along the time index.

Parameters: series (Sequence[TimeSeries]) – sequence of TimeSeries to intersect
Returns: Intersected series.
Return type: Sequence[TimeSeries]

Additional util functions

Examples