TimeSeries is the main class in darts. It represents a univariate or multivariate time series. It can represent a stochastic time series by storing several samples (trajectories).
darts.timeseries.
TimeSeries
Bases: object
object
Wrapper around a (well formed) DataArray. Use the static factory methods to build instances unless you know what you are doing.
_fill_missing_dates
Returns an xarray DataArray instance with missing dates inserted from an input xarray DataArray. The first dimension of the input DataArray xa has to be the time dimension.
This requires either a provided freq or the possibility to infer a unique frequency (see offset aliases for more info on supported frequencies) from the provided timestamps.
xa – The xarray DataArray
freq – Optionally, a string representing the frequency of the Pandas DateTimeIndex to fill in the missing dates.
ValueError – If xa’s DateTimeIndex contains less than 3 elements; if no unique frequency can be inferred from xa’s DateTimeIndex; if the resampled DateTimeIndex does not contain all dates from xa (see _restore_xarray_from_frequency())
_restore_xarray_from_frequency()
xarray DataArray with filled missing dates from xa
xarray DataArray
_restore_xarray_from_frequency
Returns an xarray DataArray instance that is resampled from an input xarray DataArray xa with frequency freq. freq should be the inferred or actual frequency of xa. All data from xa is maintained in the output DataArray at the corresponding dates. Any missing dates from xa will be inserted into the returned DataArray with np.nan values.
The first dimension of the input DataArray xa has to be the time dimension.
This requires a provided freq (see offset aliases for more info on supported frequencies).
freq – A string representing the actual or inferred frequency of the Pandas DateTimeIndex from xa.
ValueError – If the resampled DateTimeIndex does not contain all dates from xa
xarray DataArray resampled from xa with freq including all data from xa and inserted missing dates
add_datetime_attribute
Returns a new TimeSeries instance with one (or more) additional component(s) that contain an attribute of the time index of the current series specified with attribute, such as ‘weekday’, ‘day’ or ‘month’.
This works only for deterministic time series (i.e., made of 1 sample).
attribute – A pd.DatatimeIndex attribute which will serve as the basis of the new column(s).
one_hot – Boolean value indicating whether to add the specified attribute as a one hot encoding (results in more columns).
cyclic – Boolean value indicating whether to add the specified attribute as a cyclic encoding. Alternative to one_hot encoding, enable only one of the two. (adds 2 columns, corresponding to sin and cos transformation).
New TimeSeries instance enhanced by attribute.
add_holidays
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.
country_code – The country ISO code
prov – The province
state – The state
A new TimeSeries instance, enhanced with binary holiday component.
all_values
Returns a 3-D Numpy array of dimension (time, component, sample), containing this series’ values for all samples.
copy – Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing.
The values composing the time series.
numpy.ndarray
append
Appends another TimeSeries to this TimeSeries, along the time axis.
other – A second TimeSeries.
A new TimeSeries, obtained by appending the second TimeSeries to the first.
append_values
Appends values to current TimeSeries, to the given indices.
values – An array with the values to append.
A new TimeSeries with the new values appended
autocorr
columns
Same as components property
components
The names of the components (equivalent to DataFrame columns) as a Pandas Index
copy
Make a copy of this time series object
A copy of this time series.
data_array
Returns the xarray DataArray representation of this time series.
copy – Whether to return a copy of the series. Leave it to True unless you know what you are doing.
The xarray DataArray underlying this time series.
xarray.DataArray
describe
diff
Returns a differenced time series. This is often used to make a time series stationary.
n – Optionally, a positive integer indicating the number of differencing steps (default = 1). For instance, n=2 computes the second order differences.
periods – Optionally, periods to shift for calculating difference. For instance, periods=12 computes the difference between values at time t and times t-12.
dropna – Whether to drop the missing values after each differencing steps. If set to False, the corresponding first periods time steps will be filled with NaNs.
A TimeSeries constructed after differencing.
drop_after
Drops everything after the provided timestamp ts, included. The timestamp may not be in the TimeSeries. If it is, the timestamp will be dropped.
split_point – The timestamp that indicates cut-off time.
A new TimeSeries, after ts.
drop_before
Drops everything before the provided timestamp ts, included. The timestamp may not be in the TimeSeries. If it is, the timestamp will be dropped.
duration
and int otherwise.
Union[pandas.Timedelta, int]
end_time
A timestamp containing the last time of the TimeSeries (if indexed by DatetimeIndex), or an integer (if indexed by Int64Index/RangeIndex)
Union[pandas.Timestamp, int]
first_value
The first value of this univariate deterministic time series
float
first_values
The first values of every component of this deterministic time series
np.ndarray
freq
freq_str
from_csv
Returns 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 an Int64Index) and a list of columns value_cols can be used to indicate the values for this time series.
filepath_or_buffer – The path to the CSV file, or the file object; consistent with the argument of pandas.read_csv function
time_col – The time column name. If set, the column will be cast to a pandas DatetimeIndex. If not set, the pandas Int64Index will be used.
value_cols – A string or list of strings representing the value column(s) to be extracted from the CSV file. If set to None, all columns from the CSV file will be used (except for the time_col, if specified)
fill_missing_dates – Optionally, a boolean value indicating whether to fill missing dates 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.
_fill_missing_dates()
freq – 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 – Optionally, a numeric value to fill missing values (NaNs) with.
**kwargs – Optional arguments to be passed to pandas.read_csv function
A univariate or multivariate deterministic TimeSeries constructed from the inputs.
from_dataframe
Returns 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.
df – The DataFrame
time_col – 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 Int64Index (incl. 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 – 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.
from_json
Converts the JSON String representation of a TimeSeries object (produced using TimeSeries.to_json()) into a TimeSeries object
At the moment this only supports deterministic time series (i.e., made of 1 sample).
json_str – The JSON String to convert
The time series object converted from the JSON String
from_series
Returns a univariate and deterministic TimeSeries built from a pandas Series.
The series must contain an index that is either a pandas DatetimeIndex or a pandas Int64Index (incl. 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).
pd_series – The pandas Series instance.
A univariate and deterministic TimeSeries constructed from the inputs.
from_times_and_values
Returns a TimeSeries built from an index and value array.
times – A pandas.DateTimeIndex or pandas.Int64Index (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 – A Numpy array of values for the TimeSeries. Both 2-dimensional arrays, for deterministic series, and 3-dimensional arrays, for probabilistic series, are accepted. In the former case the dimensions should be (time, component), and in the latter case (time, component, sample).
columns – Columns to be used by the underlying pandas DataFrame.
A TimeSeries constructed from the inputs.
from_values
Returns a TimeSeries built from an array of values. The series will have an integer index (Int64Index).
from_xarray
Returns 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 Int64Index. 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”.
gaps
A function to compute and return gaps in the TimeSeries. Works only on deterministic time series (1 sample).
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).
pd.DataFrame
get_index_at_point
Converts a point into an integer index
point –
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.
get_timestamp_at_point
Converts a point into a pandas.Timestamp (if Datetime-indexed) or into an integer (if Int64-indexed).
point – This parameter supports 3 different data types: float, int and pandas.Timestamp. In case of a float, the parameter will be treated as the proportion of the time series that should lie before the point. In 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.
has_datetime_index
Whether this series is indexed with a DatetimeIndex (otherwise it is indexed with an Int64Index)
has_range_index
Whether this series is indexed with an Int64Index (otherwise it is indexed with a DatetimeIndex)
has_same_time_as
Checks whether this TimeSeries and another one have the same time index.
other – the other series
True if both TimeSeries have the same index, False otherwise.
bool
is_deterministic
is_probabilistic
is_stochastic
is_univariate
is_within_range
Check whether a given timestamp or integer is withing 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.
ts – The pandas.Timestamp (if indexed with DatetimeIndex) or integer (if indexed with Int64Index) to check.
Whether ts is contained within the interval of this time series.
kurtosis
last_value
The last value of this univariate deterministic time series
last_values
The last values of every component of this deterministic time series
longest_contiguous_slice
Returns the largest TimeSeries slice of this deterministic time series that contains no gaps (contigouse all-NaN rows) larger than max_gap_size.
This method is only applicable to deterministic series (i.e., having 1 sample).
a new series constituting the largest slice of the original with no or bounded gaps
map
Applies the function fn elementwise to all values in this TimeSeries. Returns a new TimeSeries instance. If fn takes 1 argument it is simply applied elementwise. If it takes 2 arguments, it is applied elementwise on the (timestamp, value) tuples.
At the moment this function works only on deterministic time series (i.e., made of 1 sample).
fn – Either a function which takes a value and returns a value ie. f(x) = y Or a function which takes a value and its timestamp and returns a value ie. f(timestamp, x) = y The type of timestamp is either pd.Timestamp (if the series is indexed with a DatetimeIndex), or an integer otherwise (if the series is indexed with an Int64Index).
A new TimeSeries instance
max
mean
median
min
n_components
n_samples
n_timesteps
pd_dataframe
Returns a Pandas DataFrame representation of this 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).
copy – Whether to return a copy of the dataframe. Leave it to True unless you know what you are doing.
The Pandas DataFrame representation of this time series
pandas.DataFrame
pd_series
Returns a Pandas Series representation of this time series. Works only for univariate series that are deterministic (i.e., made of 1 sample).
A Pandas Series representation of this univariate time series.
pandas.Series
plot
A wrapper method around xarray.DataArray.plot().
new_plot – whether to spawn a new Figure
central_quantile – The quantile (between 0 and 1) to plot as a “central” value, if the series is stochastic (i.e., if it has multiple samples). This will be applied on each component separately (i.e., to display quantiles of the components’ marginal distributions). For instance, setting central_quantile=0.5 will plot the median of each component. central_quantile can also be set to ‘mean’.
low_quantile – The quantile to use for the lower bound of the plotted confidence interval. Similar to central_quantile, this is applied to each component separately (i.e., displaying marginal distributions). No confidence interval is shown if confidence_low_quantile is None (default 0.05).
high_quantile – The quantile to use for the upper bound of the plotted confidence interval. Similar to central_quantile, this is applied to each component separately (i.e., displaying marginal distributions). No confidence interval is shown if high_quantile is None (default 0.95).
args – some positional arguments for the plot() method
kwargs – some keyword arguments for the plot() method
quantile_df
Returns 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)
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.
The Pandas DataFrame containing the desired quantile for each component.
quantile_timeseries
Returns 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.
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.
The TimeSeries containing the desired quantile for each component.
quantiles_df
Returns 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.
quantiles – 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.
The Pandas DataFrame containing the quantiles for each component.
resample
Creates an reindexed time series with a given frequency. Provided method is used to fill holes in reindexed TimeSeries, by default ‘pad’.
freq – The new time difference between two adjacent entries in the returned TimeSeries. A DateOffset alias is expected.
method –
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.
A reindexed TimeSeries with given frequency.
rescale_with_value
Returns a new TimeSeries, which is a multiple of this TimeSeries such that the first value is value_at_first_step. (Note: numerical errors can appear with value_at_first_step > 1e+24).
value_at_first_step – The new value for the first entry of the TimeSeries.
A new TimeSeries, where the first value is value_at_first_step and other values have been scaled accordingly.
shift
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.
n – The number of time steps (in self.freq unit) to shift by. Can be negative.
A new TimeSeries, with a shifted index.
skew
slice
Returns 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.
start_ts – The timestamp that indicates the left cut-off.
end_ts – The timestamp that indicates the right cut-off.
A new series, with indices greater or equal than start_ts and smaller or equal than end_ts.
slice_intersect
Returns a TimeSeries slice of this time series, where the time index has been intersected with the one provided in argument. Note that this method is in general not symmetric.
other – the other time series
a new series, containing the values of this series, over the time-span common to both time series.
slice_n_points_after
Returns a new TimeSeries, starting a start_ts and having at most n points.
The provided timestamps will be included in the series.
start_ts – The timestamp or index that indicates the splitting time.
n – The maximal length of the new TimeSeries.
A new TimeSeries, with length at most n, starting at start_ts
slice_n_points_before
Returns a new TimeSeries, ending at start_ts and having at most n points.
end_ts – The timestamp or index that indicates the splitting time.
A new TimeSeries, with length at most n, ending at start_ts
split_after
Splits the TimeSeries in two, after a provided split_point.
split_point – A timestamp, float or integer. If float, represents the proportion of the series to include in the first TimeSeries (must be between 0.0 and 1.0). If integer, represents the index position after which the split is performed. A 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.
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.
Tuple[TimeSeries, TimeSeries]
split_before
Splits the TimeSeries in two, before a provided split_point.
split_point – A timestamp, float or integer. If float, represents the proportion of the series to include in the first TimeSeries (must be between 0.0 and 1.0). If integer, represents the index position before which the split is performed. A 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.
stack
Stacks another univariate or multivariate TimeSeries with the same time index on top of the current one (along the component axis), and returns the newly formed multivariate 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.
other – A TimeSeries instance with the same index and the same number of samples as the current one.
A new multivariate TimeSeries instance.
start_time
A timestamp containing the first time of the TimeSeries (if indexed by DatetimeIndex), or an integer (if indexed by Int64Index/RangeIndex)
std
strip
Returns 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.
a new series based on the original where NaN-only entries at start and end have been removed
sum
time_index
returns: The time index of this time series. :rtype: Union[pd.DatetimeIndex, pd.Int64Index]
to_json
Converts the TimeSeries object to a JSON String
A JSON String representing the time series
str
univariate_component
Retrieves one of the components of the current TimeSeries instance and returns it as new univariate TimeSeries instance.
index – An zero-indexed integer indicating which component to retrieve. If components have names, this can be a string with the component’s name.
A new univariate TimeSeries instance.
univariate_values
Returns a 1-D Numpy array of dimension (time,), containing this univariate series’ values for one sample. If this series is deterministic, it contains only one sample and only sample=0 can be used.
copy – Whether to return a copy of the values. Leave it to True unless you know what you are doing.
The values composing the time series guaranteed to be univariate.
values
Returns a 2-D Numpy array of dimension (time, component), containing this series’ values for one sample. If this series is deterministic, it contains only one sample and only sample=0 can be used.
sample – For stochastic series, the sample for which to return values. Default: 0 (first sample).
var
width
with_columns_renamed
Changes ts column names and returns a new TimeSeries instance.
col_names – String or list of strings corresponding the the column names to be changed.
col_names_new – String or list of strings corresponding to the new column names. Must be the same length as col_names.
A new TimeSeries instance.