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 monotically increasing time index, without holes (without missing dates)

  • Contain numeric types only

  • Have distinct components/columns names

  • Have a well defined frequency (for DateTimeIndex)

  • Be non-empty.

class darts.timeseries.TimeSeries(xa)[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 pandas.DataFrame.

TimeSeries.from_series

Create from a pandas.Series.

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

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_range_index

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

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.

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.

time_dim

The name of the time dimension for this time series.

time_index

The time index of this time series.

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

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

Concatenate another timeseries to the current one along given axis.

copy()

Make a copy of this series.

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.

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_json(json_str)

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 series from a pandas 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()

A function to compute and return gaps in the TimeSeries.

get_index_at_point(point[, after])

Converts a point along the time axis into an integer index.

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

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.

pd_dataframe([copy])

Return a Pandas DataFrame representation of this deterministic time series.

pd_series([copy])

Return a Pandas Series representation of this univariate deterministic time series.

plot([new_plot, central_quantile, ...])

Plot the series.

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

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, inclusive on both ends.

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

std([ddof])

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

strip()

Return a TimeSeries slice of this deterministic time series, where NaN-only 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_json()

Return a JSON string representation of this deterministic series.

to_pickle(path[, protocol])

Save this series in pickle format.

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.

with_columns_renamed(col_names, col_names_new)

Return a new TimeSeries instance with new columns/components names.

with_values(values)

Return a new TimeSeries with new specified values.

add_datetime_attribute(attribute, one_hot=False, cyclic=False)[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).

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

Returns

New TimeSeries instance enhanced by attribute.

Return type

TimeSeries

add_holidays(country_code, prov=None, state=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]) – The province

  • state (Optional[str]) – The state

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 – 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 (TimeSeries) – 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.

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 columns

The names of the components, as a Pandas Index.

property components

The names of the components, as a Pandas Index.

concatenate(other, axis=0, ignore_time_axes=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_axes (bool, default False) – Ignore errors when time axis varies for some timeseries. Note that this may yield unexpected results

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

data_array(copy=True)[source]

Return the xarray.DataArray representation underlying this series.

Parameters

copy – 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]) – Optionally, a positive integer indicating the number of differencing steps (default = 1). For instance, n=2 computes the second order differences.

  • periods (Optional[int]) – 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]) – 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 TimeSeries constructed after differencing.

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

property dtype

The dtype of the series’ values.

property duration: Union[pandas._libs.tslibs.timedeltas.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

The frequency of the series.

property freq_str

The frequency string representation of the series.

classmethod from_csv(filepath_or_buffer, time_col=None, value_cols=None, fill_missing_dates=False, freq=None, fillna_value=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]) – The time column name. If set, the column will be cast to a pandas DatetimeIndex. If not set, the pandas RangeIndex will be used.

  • value_cols (Union[List[str], 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]) – Optionally, a boolean value indicating whether to fill missing dates 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 (Optional[str]) – Optionally, a string representing the frequency of the Pandas DateTimeIndex. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True.

  • fillna_value (Optional[float]) – Optionally, a numeric value to fill missing values (NaNs) with.

  • **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

classmethod from_dataframe(df, time_col=None, value_cols=None, fill_missing_dates=False, freq=None, fillna_value=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 (DataFrame) – The DataFrame

  • time_col (Optional[str]) – The time column name. If set, the column will be cast to a pandas DatetimeIndex. If not set, the DataFrame index will be used. In this case the DataFrame must contain an index that is either a pandas DatetimeIndex or a pandas RangeIndex. If a DatetimeIndex is used, it is better if it has no holes; alternatively setting fill_missing_dates can in some casees 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]) – Optionally, a boolean value indicating whether to fill missing dates 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 (Optional[str]) – Optionally, a string representing the frequency of the Pandas DateTimeIndex. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True.

  • fillna_value (Optional[float]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

A univariate or multivariate deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

classmethod from_json(json_str)[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

Returns

The time series object converted from the JSON String

Return type

TimeSeries

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)[source]

Build a univariate deterministic series from a pandas Series.

The series must contain an index that is either a pandas DatetimeIndex or a pandas RangeIndex. If a DatetimeIndex is used, it is better if it 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 (Series) – The pandas Series instance.

  • fill_missing_dates (Optional[bool]) – Optionally, a boolean value indicating whether to fill missing dates 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 (Optional[str]) – Optionally, a string representing the frequency of the Pandas DateTimeIndex. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True.

  • fillna_value (Optional[float]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

A univariate and deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

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

Build a series from a time index and value array.

Parameters
  • times (Union[DatetimeIndex, RangeIndex]) – A pandas.DateTimeIndex or pandas.RangeIndex representing the time axis for the time series. If a DatetimeIndex is used, it is better if it 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]) – Optionally, a boolean value indicating whether to fill missing dates 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 (Optional[str]) – Optionally, a string representing the frequency of the Pandas DateTimeIndex. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True.

  • columns (Optional[Collection[Any]]) – Columns to be used by the underlying pandas DataFrame.

  • fillna_value (Optional[float]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

A TimeSeries constructed from the inputs.

Return type

TimeSeries

classmethod from_values(values, columns=None, fillna_value=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 (Optional[Collection[Any]]) – Columns to be used by the underlying pandas DataFrame.

  • fillna_value (Optional[float]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

A TimeSeries constructed from the inputs.

Return type

TimeSeries

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 or a pandas RangeIndex. If a DatetimeIndex is used, it is better if it 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”.

Parameters
  • xa (DataArray) – The xarray DataArray

  • fill_missing_dates (Optional[bool]) – Optionally, a boolean value indicating whether to fill missing dates 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 (Optional[str]) – Optionally, a string representing the frequency of the Pandas DateTimeIndex. This is useful in order to fill in missing values if some dates are missing and fill_missing_dates is set to True.

  • fillna_value (Optional[float]) – Optionally, a numeric value to fill missing values (NaNs) with.

Returns

A univariate or multivariate deterministic TimeSeries constructed from the inputs.

Return type

TimeSeries

gaps()[source]

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

Returns

A 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 into an integer index.

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

    In the case of int, the parameter will returned as such, provided that it is in the series. Otherwise it will raise a ValueError.

  • 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 the 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

Timestamp

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_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 (TimeSeries) – the other series

Returns

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

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 is_deterministic

Whether this series is deterministic.

property is_probabilistic

Whether this series is stochastic (= probabilistic).

property is_stochastic

Whether this series is stochastic.

property is_univariate

Whether this series is univariate.

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)[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).

Returns

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

Return type

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 repeteadly 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=1), 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.

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=1), 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.

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=1), 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.

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

min(axis=2)[source]

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

If we reduce over time (axis=1), 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.

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

Number of components (dimensions) contained in the series.

property n_samples

Number of samples contained in the series.

property n_timesteps

Number of time steps in the series.

pd_dataframe(copy=True)[source]

Return a Pandas DataFrame representation of this deterministic time series.

Each of the series components will appear as a column in the DataFrame. Works only for deterministic series (i.e., made of 1 sample).

Parameters

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

Returns

The Pandas DataFrame representation of this time series

Return type

pandas.DataFrame

pd_series(copy=True)[source]

Return a Pandas Series representation of this univariate deterministic time series.

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

Parameters

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

Returns

A Pandas Series representation of this univariate time series.

Return type

pandas.Series

plot(new_plot=False, central_quantile=0.5, low_quantile=0.05, high_quantile=0.95, *args, **kwargs)[source]

Plot the series.

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

Parameters
  • new_plot (bool) – whether to spawn a new Figure

  • 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]) – 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]) – 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).

  • args – some positional arguments for the plot() method

  • kwargs – some keyword arguments for the plot() method

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.

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 – 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 – 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')[source]

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

Parameters
  • freq (str) – The new time difference between two adjacent entries in the returned TimeSeries. A DateOffset alias is expected.

  • method (str) –

    Method to fill holes in reindexed TimeSeries (note this does not fill NaNs that already were present):

    ’pad’: propagate last valid observation forward to next valid

    ’backfill’: use NEXT valid observation to fill.

Returns

A reindexed TimeSeries with given frequency.

Return type

TimeSeries

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

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, inclusive on both ends. The timestamps 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 (TimeSeries) – 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_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 (TimeSeries) – 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]

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()[source]

Return a TimeSeries slice of this deterministic time series, where NaN-only 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).

Returns

a new series based on the original where NaN-only 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=1), 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.

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[pandas.core.indexes.datetimes.DatetimeIndex, pandas.core.indexes.range.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_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).

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

univariate_component(index)[source]

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

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 – Whether to return a copy of the values. Leave it to True unless you know what you are doing.

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 – Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.

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

Returns

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

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

with_columns_renamed(col_names, col_names_new)[source]

Return a new TimeSeries instance with new columns/components names.

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_values(values)[source]

Return a new TimeSeries with new specified values.

Parameters

values (ndarray) – A Numpy array with new values. It must have the same shape as the present series (time, components, samples)

Returns

A new TimeSeries with the new values and same index

Return type

TimeSeries

darts.timeseries.concatenate(series, axis=0, ignore_time_axis=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.

Returns

concatenated series

Return type

TimeSeries