Hierarchical Reconciliation¶
A set of posthoc hierarchical reconciliation transformers. These transformers
work on any TimeSeries
(e.g., a forecast) that contain a hierarchy
.
A hierarchy
is a dict that maps each component to their parent(s) in the hierarchy.
It can be added to a TimeSeries
using e.g., the TimeSeries.with_hierarchy()
method.
- class darts.dataprocessing.transformers.reconciliation.BottomUpReconciliator(name='BaseDataTransformer', n_jobs=1, verbose=False, parallel_params=False, mask_components=True)[source]¶
Bases:
darts.dataprocessing.transformers.base_data_transformer.BaseDataTransformer
Performs bottom up reconciliation, as defined here.
Attributes
Name of the data transformer.
Methods
apply_component_mask
(series[, ...])Extracts components specified by component_mask from series
set_n_jobs
(value)Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.set_verbose
(value)Set the verbosity status.
stack_samples
(vals)Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
transform
(series, *args[, component_mask])Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
ts_transform
(series, params, *args, **kwargs)The function that will be applied to each series when
transform()
is called.unapply_component_mask
(series, vals[, ...])Adds back components previously removed by component_mask in apply_component_mask method.
unstack_samples
(vals[, n_timesteps, ...])Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this 'undoes' the reshaping of stack_samples.
get_projection_matrix
Abstract class for data transformers.
All the deriving classes have to implement the static method
ts_transform()
; this implemented method can then be applied toTimeSeries
orSequence[TimeSeries]
inputs by calling thetransform()
method. Internally,transform()
parallelizes func:ts_transform over all of theTimeSeries
inputs passed to it. See the func:ts_transform method documentation for further details on how to implement this method in a user-defined class.Data transformers requiring to be fit first before calling
transform()
should derive fromFittableDataTransformer
instead. Data transformers that are invertible should derive fromInvertibleDataTransformer
instead. Transformers which are both fittable and invertible should inherit from bothFittableDataTransformer
andInvertibleDataTransformer
.All Data Transformers can store fixed parameters that are automatically passed to func:ts_transform; the fixed parameters of a data transformer object are taken to be all those attributes defined in the __init__ method of the child-most class before super().__init__ is called. The fixed parameter values can then be accessed within the func:ts_transform method through the params dictionary argument. More specifically, params[‘fixed’] stores a dictionary with all of the fixed parameter values, where the keys are simply the attribute names of each fixed parameter (e.g. the self._my_param fixed parameter attribute is accessed through params[‘fixed’][‘_my_param’]).
Data Transformers which inherit from
FittableDataTransformer
can also store fitted parameters alongside fixed parameters; please refer to theFittableDataTransformer
documentation for further details.Note: the
ts_transform()
method is designed to be a static method instead of a instance method to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using an instance method would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.- Parameters
name (
str
) – The data transformer’s namen_jobs (
int
) – The number of jobs to run in parallel. Parallel jobs are created only when aSequence[TimeSeries]
is passed as input to a method, parallelising operations regarding different TimeSeries. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available processors. Note: for a small amount of data, the parallelisation overhead could end up increasing the total required amount of time.verbose (
bool
) – Optionally, whether to print operations progressparallel_params (
Union
[bool
,Sequence
[str
]]) – Optionally, specifies which fixed parameters (i.e. the attributes initialized in the child-most class’s __init__) take on different values for different parallel jobs. Fixed parameters specified by parallel_params are assumed to be a Sequence of values that should be used for that parameter in each parallel job; the length of this Sequence should equal the number of parallel jobs. If parallel_params=True, every fixed parameter will take on a different value for each parallel job. If parallel_params=False, every fixed parameter will take on the same value for each parallel job. If parallel_params is a Sequence of fixed attribute names, only those attribute names specified will take on different values between different parallel jobs.mask_components (
bool
) – Optionally, whether or not to automatically apply any provided component_mask`s to the `TimeSeries inputs passed to transform, fit, inverse_transform, or fit_transform. If True, any specified component_mask will be applied to each input timeseries before passing them to the called method; the masked components will also be automatically ‘unmasked’ in the returned TimeSeries. If False, then component_mask (if provided) will be passed as a keyword argument, but won’t automatically be applied to the input timeseries. See apply_component_mask for further details.
Example
>>> from darts.dataprocessing.transformers import BaseDataTransformer >>> from darts.utils.timeseries_generation import linear_timeseries >>> >>> class SimpleTransform(BaseDataTransformer): >>> >>> def __init__(self, a): >>> self._a = a >>> super().__init__() >>> >>> @staticmethod >>> def ts_transform(series, params, **kwargs): >>> a = params['fixed']['_a'] >>> b = kwargs.pop('b') >>> return a*series + b >>> >>> series = linear_timeseries(length=5) >>> print(series) <TimeSeries (DataArray) (time: 5, component: 1, sample: 1)> array([[[0. ]],
[[0.25]],
[[0.5 ]],
[[0.75]],
[[1. ]]])
Coordinates: * time (time) datetime64[ns] 2000-01-01 2000-01-02 … 2000-01-05 * component (component) object ‘linear’ Dimensions without coordinates: sample .. attribute:: static_covariates
None
- hierarchy¶
None
>>> series = SimpleTransform(a=2).transform(series, b=3) >>> print(series) <TimeSeries (DataArray) (time: 5, component: 1, sample: 1)> array([[[3. ]],
[[3.5]],
[[4. ]],
[[4.5]],
[[5. ]]])
Coordinates: * time (time) datetime64[ns] 2000-01-01 2000-01-02 … 2000-01-05 * component (component) object ‘linear’ Dimensions without coordinates: sample .. attribute:: static_covariates
None
- hierarchy¶
None
Attributes
Name of the data transformer.
Methods
apply_component_mask
(series[, ...])Extracts components specified by component_mask from series
set_n_jobs
(value)Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.set_verbose
(value)Set the verbosity status.
stack_samples
(vals)Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
transform
(series, *args[, component_mask])Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
ts_transform
(series, params, *args, **kwargs)The function that will be applied to each series when
transform()
is called.unapply_component_mask
(series, vals[, ...])Adds back components previously removed by component_mask in apply_component_mask method.
unstack_samples
(vals[, n_timesteps, ...])Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this 'undoes' the reshaping of stack_samples.
get_projection_matrix
- static apply_component_mask(series, component_mask=None, return_ts=False)¶
Extracts components specified by component_mask from series
- Parameters
series (
TimeSeries
) – input TimeSeries to be fed into transformer.component_mask (
Optional
[ndarray
]) – Optionally, np.ndarray boolean mask of shape (n_components, 1) specifying which components to extract from series. The i`th component of `series is kept only if component_mask[i] = True. If not specified, no masking is performed.return_ts – Optionally, specifies that a TimeSeries should be returned, rather than an np.ndarray.
- Returns
TimeSeries (if return_ts = True) or np.ndarray (if return_ts = False) with only those components specified by component_mask remaining.
- Return type
masked
- property name¶
Name of the data transformer.
- set_n_jobs(value)¶
Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.- Parameters
value (
int
) – New n_jobs value. Set to -1 for using all the available cores.
- set_verbose(value)¶
Set the verbosity status.
True for enabling the detailed report about scaler’s operation progress, False for no additional information.
- Parameters
value (
bool
) – New verbosity status
- static stack_samples(vals)¶
Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
Each column of the returned array corresponds to a component (dimension) of the series and is formed by concatenating all of the samples associated with that component together. More specifically, the i`th column is formed by concatenating `[component_i_sample_1, component_i_sample_2, …, component_i_sample_n].
Stacking is useful when implementing a transformation that applies the exact same change to every timestep in the timeseries. In such cases, the samples of each component can be stacked together into a single column, and the transformation can then be applied to each column, thereby ‘vectorising’ the transformation over all samples of that component; the unstack_samples method can then be used to reshape the output. For transformations that depend on the time_index or the temporal ordering of the observations, stacking should not be employed.
- Parameters
vals (
Union
[ndarray
,TimeSeries
]) – Timeseries or np.ndarray of shape (n_timesteps, n_components, n_samples) to be ‘stacked’.- Returns
np.ndarray of shape (n_timesteps * n_samples, n_components), where the i`th column is formed by concatenating all of the samples of the `i`th component in `vals.
- Return type
stacked
- transform(series, *args, component_mask=None, **kwargs)¶
Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
In case a
Sequence[TimeSeries]
is passed as input data, this function takes care of parallelising the transformation of multiple series in the sequence at the same time. Additionally, if the mask_components attribute was set to True when instantiating BaseDataTransformer, then any provided component_mask`s will be automatically applied to each input `TimeSeries; please refer to ‘Notes’ for further details on component masking.Any additionally specified *args and **kwargs are automatically passed to ts_transform.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – (sequence of) series to be transformed.args – Additional positional arguments for each
ts_transform()
method callcomponent_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should consider. If the mask_components attribute was set to True when instantiating BaseDataTransformer, then the component mask will be automatically applied to each TimeSeries input. Otherwise, component_mask will be provided as an addition keyword argument to ts_transform. See ‘Notes’ for further details.kwargs – Additional keyword arguments for each
ts_transform()
method call
- Returns
Transformed data.
- Return type
Union[TimeSeries, List[TimeSeries]]
Notes
If the mask_components attribute was set to True when instantiating BaseDataTransformer, then any provided component_mask`s will be automatically applied to each `TimeSeries input to transform; component_mask`s are simply boolean arrays of shape `(series.n_components,) that specify which components of each series should be transformed using ts_transform and which components should not. If component_mask[i] is True, then the i`th component of each `series will be transformed by ts_transform. Conversely, if component_mask[i] is False, the i`th component will be removed from each `series before being passed to ts_transform; after transforming this masked series, the untransformed i`th component will be ‘added back’ to the output. Note that automatic `component_mask`ing can only be performed if the `ts_transform does not change the number of timesteps in each series; if this were to happen, then the transformed and untransformed components are unable to be concatenated back together along the component axis.
If mask_components was set to False when instantiating BaseDataTransformer, then any provided component_masks will be passed as a keyword argument ts_transform; the user can then manually specify how the component_mask should be applied to each series.
- static ts_transform(series, params, *args, **kwargs)[source]¶
The function that will be applied to each series when
transform()
is called.This method is not implemented in the base class and must be implemented in the deriving classes.
The function must take as first argument a
TimeSeries
object and, as a second argument, a dictionary containing the fixed and/or fitted parameters of the transformation; this function should then return a transformedTimeSeries
object.- The params dictionary can contain up to two keys:
1. params[‘fixed’] stores the fixed parameters of the transformation (i.e. attributed defined in the __init__ method of the child-most class before super().__init__ is called); params[‘fixed’] is a dictionary itself, whose keys are the names of the fixed parameter attributes. For example, if _my_fixed_param is defined as an attribute in the child-most class, then this fixed parameter value can be accessed through params[‘fixed’][‘_my_fixed_param’]. 2. If the transform inherits from the
FittableDataTransformer
class, then params[‘fitted’] will store the fitted parameters of the transformation; the fitted parameters are simply the output(s) returned by the ts_fit function, whatever those output(s) may be. SeeFittableDataTransformer
for further details about fitted parameters.
Any positional/keyword argument supplied to the transform method are passed as positional/keyword arguments to ts_transform; hence, ts_transform should also accept *args and/or **kwargs if positional/keyword arguments are passed to transform. Note that if the mask_components attribute of BaseDataTransformer is set to False, then the component_mask provided to transform will be passed as an additional keyword argument to ts_transform.
The BaseDataTransformer class includes some helper methods which may prove useful when implementing a ts_transform function:
1. The apply_component_mask and unapply_component_mask methods, which apply and ‘unapply’ component_mask`s to a `TimeSeries respectively; these methods are automatically called in transform if the mask_component attribute of BaseDataTransformer is set to True, but you may want to manually call them if you set mask_components to False and wish to manually specify how component_mask`s are applied to a `TimeSeries. 2. The stack_samples method, which stacks all the samples in a TimeSeries along the component axis, so that the TimeSeries goes from shape (n_timesteps, n_components, n_samples) to shape (n_timesteps, n_components * n_samples). This stacking is useful if a pointwise transform is being implemented (i.e. transforming the value at time t depends only on the value of the series at that time t). Once transformed, the stacked TimeSeries can be ‘unstacked’ using the unstack_samples method.
- Parameters
series (
TimeSeries
) – series to be transformed.params (
Mapping
[str
,Any
]) – Dictionary containing the parameters of the transformation function. Fixed parameters (i.e. attributes defined in the child-most class of the transformation prior to calling super.__init__()) are stored under the ‘fixed’ key. If the transformation inherits from the FittableDataTransformer class, then the fitted parameters of the transformation (i.e. the values returned by ts_fit) are stored under the ‘fitted’ key.args – Any poisitional arguments provided in addition to series when
kwargs – Any additional keyword arguments provided to transform. Note that if the mask_component attribute of BaseDataTransformer is set to False, then component_mask will be passed as a keyword argument.
Notes
This method is designed to be a static method instead of instance method to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using instance methods would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.
- Return type
- static unapply_component_mask(series, vals, component_mask=None)¶
Adds back components previously removed by component_mask in apply_component_mask method.
- Parameters
series (
TimeSeries
) – input TimeSeries that was fed into transformer.vals (
Union
[ndarray
,TimeSeries
]) – np.ndarray or TimeSeries to ‘unmask’component_mask (
Optional
[ndarray
]) – Optionally, np.ndarray boolean mask of shape (n_components, 1) specifying which components were extracted from series. If given, insert vals back into the columns of the original array. If not specified, nothing is ‘unmasked’.
- Returns
TimeSeries (if vals is a TimeSeries) or np.ndarray (if vals is an np.ndarray) with those components previously removed by component_mask now ‘added back’.
- Return type
unmasked
- static unstack_samples(vals, n_timesteps=None, n_samples=None, series=None)¶
Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this ‘undoes’ the reshaping of stack_samples. Either n_components, n_samples, or series must be specified.
- Parameters
vals (
ndarray
) – np.ndarray of shape (n_timesteps * n_samples, n_components) to be ‘unstacked’.n_timesteps (
Optional
[int
]) – Optionally, the number of timesteps in the array originally passed to stack_samples. Does not need to be provided if series is specified.n_samples (
Optional
[int
]) – Optionally, the number of samples in the array originally passed to stack_samples. Does not need to be provided if series is specified.series (
Optional
[TimeSeries
]) – Optionally, the TimeSeries object used to create vals; n_samples is inferred from this.
- Returns
np.ndarray of shape (n_timesteps, n_components, n_samples).
- Return type
unstacked
- class darts.dataprocessing.transformers.reconciliation.MinTReconciliator(method='ols')[source]¶
Bases:
darts.dataprocessing.transformers.fittable_data_transformer.FittableDataTransformer
MinT Reconcilator.
This implements the MinT reconciliation approach presented in [1] and summarised in [2].
- Parameters
method –
This parameter can take four different values, determining how the covariance matrix
W
of the forecast errors is estimated (corresponding toWh
in [2]):ols
usesW = I
. This option looks only at the hierarchy but ignores the values of the series provided tofit()
.wls_struct
usesW = diag(S1)
, whereS1
is a vector of size n with values between 0 and m, representing the number of base components composing each of the n components. This options looks only at the hierarchy but ignores the values of the series provided tofit()
.wls_var
usesW = diag(W1)
, whereW1
is the temporal average of the variance of the forecasting residuals. This method assumes that the series provided tofit()
contain the forecast residuals (deterministic series).mint_cov
computesW
as the empirical covariance matrix of the residuals for each component, with residuals samples taken over time. This method assumes that the series provided tofit()
contain the forecast residuals (deterministic series), and it requires the residuals to be linearly independent.wls_val
usesW = diag(V1)
, whereV1
is the temporal average of the component values. This method assumes that the series provided tofit()
contains an example of the actual values (e.g., either the training series or the forecasts). This method is not presented in [2].
References
- 1
Optimal forecast reconciliation for hierarchical and grouped time series through trace minimization
- 2(1,2,3)
https://otexts.com/fpp3/reconciliation.html#the-mint-optimal-reconciliation-approach
Attributes
Name of the data transformer.
Methods
apply_component_mask
(series[, ...])Extracts components specified by component_mask from series
fit
(series, *args[, component_mask])Fits transformer to a (sequence of) TimeSeries by calling the user-implemented ts_fit method.
fit_transform
(series, *args[, component_mask])Fit the transformer to the (sequence of) series and return the transformed input.
get_matrices
(series, method)Returns the G matrix given a specified reconciliation method.
set_n_jobs
(value)Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.set_verbose
(value)Set the verbosity status.
stack_samples
(vals)Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
transform
(series, *args[, component_mask])Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
ts_fit
(series, params, *args, **kwargs)The function that will be applied to each series when
fit()
is called.ts_transform
(series, params, *args, **kwargs)The function that will be applied to each series when
transform()
is called.unapply_component_mask
(series, vals[, ...])Adds back components previously removed by component_mask in apply_component_mask method.
unstack_samples
(vals[, n_timesteps, ...])Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this 'undoes' the reshaping of stack_samples.
- static apply_component_mask(series, component_mask=None, return_ts=False)¶
Extracts components specified by component_mask from series
- Parameters
series (
TimeSeries
) – input TimeSeries to be fed into transformer.component_mask (
Optional
[ndarray
]) – Optionally, np.ndarray boolean mask of shape (n_components, 1) specifying which components to extract from series. The i`th component of `series is kept only if component_mask[i] = True. If not specified, no masking is performed.return_ts – Optionally, specifies that a TimeSeries should be returned, rather than an np.ndarray.
- Returns
TimeSeries (if return_ts = True) or np.ndarray (if return_ts = False) with only those components specified by component_mask remaining.
- Return type
masked
- fit(series, *args, component_mask=None, **kwargs)¶
Fits transformer to a (sequence of) TimeSeries by calling the user-implemented ts_fit method.
The fitted parameters returned by ts_fit are stored in the
self._fitted_params
attribute. If a Sequence[TimeSeries] is passed as the series data, then one of two outcomes will occur:1. If the global_fit attribute was set to False, then a different set of parameters will be individually fitted to each TimeSeries in the Sequence. In this case, this function automatically parallelises this fitting process over all of the multiple TimeSeries that have been passed. 2. If the global_fit attribute was set to True, then all of the TimeSeries objects will be used fit a single set of parameters.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – (sequence of) series to fit the transformer on.args – Additional positional arguments for the
ts_fit()
methodcomponent_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should be fitted to.kwargs – Additional keyword arguments for the
ts_fit()
method
- Returns
Fitted transformer.
- Return type
- fit_transform(series, *args, component_mask=None, **kwargs)¶
Fit the transformer to the (sequence of) series and return the transformed input.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – the (sequence of) series to transform.args – Additional positional arguments passed to the
ts_transform()
andts_fit()
methods.component_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should be fitted and applied to.kwargs – Additional keyword arguments passed to the
ts_transform()
andts_fit()
methods.
- Returns
Transformed data.
- Return type
Union[TimeSeries, Sequence[TimeSeries]]
- static get_matrices(series, method)[source]¶
Returns the G matrix given a specified reconciliation method.
- property name¶
Name of the data transformer.
- set_n_jobs(value)¶
Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.- Parameters
value (
int
) – New n_jobs value. Set to -1 for using all the available cores.
- set_verbose(value)¶
Set the verbosity status.
True for enabling the detailed report about scaler’s operation progress, False for no additional information.
- Parameters
value (
bool
) – New verbosity status
- static stack_samples(vals)¶
Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
Each column of the returned array corresponds to a component (dimension) of the series and is formed by concatenating all of the samples associated with that component together. More specifically, the i`th column is formed by concatenating `[component_i_sample_1, component_i_sample_2, …, component_i_sample_n].
Stacking is useful when implementing a transformation that applies the exact same change to every timestep in the timeseries. In such cases, the samples of each component can be stacked together into a single column, and the transformation can then be applied to each column, thereby ‘vectorising’ the transformation over all samples of that component; the unstack_samples method can then be used to reshape the output. For transformations that depend on the time_index or the temporal ordering of the observations, stacking should not be employed.
- Parameters
vals (
Union
[ndarray
,TimeSeries
]) – Timeseries or np.ndarray of shape (n_timesteps, n_components, n_samples) to be ‘stacked’.- Returns
np.ndarray of shape (n_timesteps * n_samples, n_components), where the i`th column is formed by concatenating all of the samples of the `i`th component in `vals.
- Return type
stacked
- transform(series, *args, component_mask=None, **kwargs)¶
Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
In case a
Sequence[TimeSeries]
is passed as input data, this function takes care of parallelising the transformation of multiple series in the sequence at the same time. Additionally, if the mask_components attribute was set to True when instantiating BaseDataTransformer, then any provided component_mask`s will be automatically applied to each input `TimeSeries; please refer to ‘Notes’ for further details on component masking.Any additionally specified *args and **kwargs are automatically passed to ts_transform.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – (sequence of) series to be transformed.args – Additional positional arguments for each
ts_transform()
method callcomponent_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should consider. If the mask_components attribute was set to True when instantiating BaseDataTransformer, then the component mask will be automatically applied to each TimeSeries input. Otherwise, component_mask will be provided as an addition keyword argument to ts_transform. See ‘Notes’ for further details.kwargs – Additional keyword arguments for each
ts_transform()
method call
- Returns
Transformed data.
- Return type
Union[TimeSeries, List[TimeSeries]]
Notes
If the mask_components attribute was set to True when instantiating BaseDataTransformer, then any provided component_mask`s will be automatically applied to each `TimeSeries input to transform; component_mask`s are simply boolean arrays of shape `(series.n_components,) that specify which components of each series should be transformed using ts_transform and which components should not. If component_mask[i] is True, then the i`th component of each `series will be transformed by ts_transform. Conversely, if component_mask[i] is False, the i`th component will be removed from each `series before being passed to ts_transform; after transforming this masked series, the untransformed i`th component will be ‘added back’ to the output. Note that automatic `component_mask`ing can only be performed if the `ts_transform does not change the number of timesteps in each series; if this were to happen, then the transformed and untransformed components are unable to be concatenated back together along the component axis.
If mask_components was set to False when instantiating BaseDataTransformer, then any provided component_masks will be passed as a keyword argument ts_transform; the user can then manually specify how the component_mask should be applied to each series.
- static ts_fit(series, params, *args, **kwargs)[source]¶
The function that will be applied to each series when
fit()
is called.If the global_fit attribute is set to False, then ts_fit should accept a TimeSeries as a first argument and return a set of parameters that are fitted to this individual TimeSeries. Conversely, if the global_fit attribute is set to True, then ts_fit should accept a Sequence[TimeSeries] and return a set of parameters that are fitted to all of the provided TimeSeries. All these parameters will be stored in
self._fitted_params
, which can be later used during the transformation step.Regardless of whether the global_fit attribute is set to True or False, ts_fit should also accept a dictionary of fixed parameter values as a second argument (i.e. `params[‘fixed’] contains the fixed parameters of the data transformer).
Any additional positional and/or keyword arguments passed to the fit method will be passed as positional/keyword arguments to ts_fit.
This method is not implemented in the base class and must be implemented in the deriving classes.
If more parameters are added as input in the derived classes,
_fit_iterator()
should be redefined accordingly, to yield the necessary arguments to this function (See_fit_iterator()
for further details)- Parameters
(Union[TimeSeries (series) – TimeSeries against which the scaler will be fit.
Sequence[TimeSeries]]) – TimeSeries against which the scaler will be fit.
Notes
This method is designed to be a static method instead of instance methods to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using instance methods would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.
- Return type
ndarray
- static ts_transform(series, params, *args, **kwargs)[source]¶
The function that will be applied to each series when
transform()
is called.This method is not implemented in the base class and must be implemented in the deriving classes.
The function must take as first argument a
TimeSeries
object and, as a second argument, a dictionary containing the fixed and/or fitted parameters of the transformation; this function should then return a transformedTimeSeries
object.- The params dictionary can contain up to two keys:
1. params[‘fixed’] stores the fixed parameters of the transformation (i.e. attributed defined in the __init__ method of the child-most class before super().__init__ is called); params[‘fixed’] is a dictionary itself, whose keys are the names of the fixed parameter attributes. For example, if _my_fixed_param is defined as an attribute in the child-most class, then this fixed parameter value can be accessed through params[‘fixed’][‘_my_fixed_param’]. 2. If the transform inherits from the
FittableDataTransformer
class, then params[‘fitted’] will store the fitted parameters of the transformation; the fitted parameters are simply the output(s) returned by the ts_fit function, whatever those output(s) may be. SeeFittableDataTransformer
for further details about fitted parameters.
Any positional/keyword argument supplied to the transform method are passed as positional/keyword arguments to ts_transform; hence, ts_transform should also accept *args and/or **kwargs if positional/keyword arguments are passed to transform. Note that if the mask_components attribute of BaseDataTransformer is set to False, then the component_mask provided to transform will be passed as an additional keyword argument to ts_transform.
The BaseDataTransformer class includes some helper methods which may prove useful when implementing a ts_transform function:
1. The apply_component_mask and unapply_component_mask methods, which apply and ‘unapply’ component_mask`s to a `TimeSeries respectively; these methods are automatically called in transform if the mask_component attribute of BaseDataTransformer is set to True, but you may want to manually call them if you set mask_components to False and wish to manually specify how component_mask`s are applied to a `TimeSeries. 2. The stack_samples method, which stacks all the samples in a TimeSeries along the component axis, so that the TimeSeries goes from shape (n_timesteps, n_components, n_samples) to shape (n_timesteps, n_components * n_samples). This stacking is useful if a pointwise transform is being implemented (i.e. transforming the value at time t depends only on the value of the series at that time t). Once transformed, the stacked TimeSeries can be ‘unstacked’ using the unstack_samples method.
- Parameters
series (
TimeSeries
) – series to be transformed.params (
Mapping
[str
,Any
]) – Dictionary containing the parameters of the transformation function. Fixed parameters (i.e. attributes defined in the child-most class of the transformation prior to calling super.__init__()) are stored under the ‘fixed’ key. If the transformation inherits from the FittableDataTransformer class, then the fitted parameters of the transformation (i.e. the values returned by ts_fit) are stored under the ‘fitted’ key.args – Any poisitional arguments provided in addition to series when
kwargs – Any additional keyword arguments provided to transform. Note that if the mask_component attribute of BaseDataTransformer is set to False, then component_mask will be passed as a keyword argument.
Notes
This method is designed to be a static method instead of instance method to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using instance methods would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.
- Return type
- static unapply_component_mask(series, vals, component_mask=None)¶
Adds back components previously removed by component_mask in apply_component_mask method.
- Parameters
series (
TimeSeries
) – input TimeSeries that was fed into transformer.vals (
Union
[ndarray
,TimeSeries
]) – np.ndarray or TimeSeries to ‘unmask’component_mask (
Optional
[ndarray
]) – Optionally, np.ndarray boolean mask of shape (n_components, 1) specifying which components were extracted from series. If given, insert vals back into the columns of the original array. If not specified, nothing is ‘unmasked’.
- Returns
TimeSeries (if vals is a TimeSeries) or np.ndarray (if vals is an np.ndarray) with those components previously removed by component_mask now ‘added back’.
- Return type
unmasked
- static unstack_samples(vals, n_timesteps=None, n_samples=None, series=None)¶
Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this ‘undoes’ the reshaping of stack_samples. Either n_components, n_samples, or series must be specified.
- Parameters
vals (
ndarray
) – np.ndarray of shape (n_timesteps * n_samples, n_components) to be ‘unstacked’.n_timesteps (
Optional
[int
]) – Optionally, the number of timesteps in the array originally passed to stack_samples. Does not need to be provided if series is specified.n_samples (
Optional
[int
]) – Optionally, the number of samples in the array originally passed to stack_samples. Does not need to be provided if series is specified.series (
Optional
[TimeSeries
]) – Optionally, the TimeSeries object used to create vals; n_samples is inferred from this.
- Returns
np.ndarray of shape (n_timesteps, n_components, n_samples).
- Return type
unstacked
- class darts.dataprocessing.transformers.reconciliation.TopDownReconciliator(name='FittableDataTransformer', n_jobs=1, verbose=False, parallel_params=False, mask_components=True, global_fit=False)[source]¶
Bases:
darts.dataprocessing.transformers.fittable_data_transformer.FittableDataTransformer
Performs top down reconciliation, as defined here.
This estimator computes the proportions (of the base components w.r.t. the top component) based on the TimeSeries provided to the method
fit()
. If the historical series is provided, then the historical proportions will be used.Attributes
Name of the data transformer.
Methods
apply_component_mask
(series[, ...])Extracts components specified by component_mask from series
fit
(series, *args[, component_mask])Fits transformer to a (sequence of) TimeSeries by calling the user-implemented ts_fit method.
fit_transform
(series, *args[, component_mask])Fit the transformer to the (sequence of) series and return the transformed input.
set_n_jobs
(value)Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.set_verbose
(value)Set the verbosity status.
stack_samples
(vals)Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
transform
(series, *args[, component_mask])Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
ts_fit
(series, params, *args, **kwargs)The function that will be applied to each series when
fit()
is called.ts_transform
(series, params, *args, **kwargs)The function that will be applied to each series when
transform()
is called.unapply_component_mask
(series, vals[, ...])Adds back components previously removed by component_mask in apply_component_mask method.
unstack_samples
(vals[, n_timesteps, ...])Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this 'undoes' the reshaping of stack_samples.
get_projection_matrix
Base class for fittable transformers.
All the deriving classes have to implement the static methods
ts_transform()
andts_fit()
. The fitting and transformation functions must be passed during the transformer’s initialization. This class takes care of parallelizing operations involving multipleTimeSeries
when possible.- Parameters
name (
str
) – The data transformer’s namen_jobs (
int
) – The number of jobs to run in parallel. Parallel jobs are created only when a Sequence[TimeSeries] is passed as input to a method, parallelising operations regarding different TimeSeries. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available processors. Note: for a small amount of data, the parallelisation overhead could end up increasing the total required amount of time.verbose (
bool
) – Optionally, whether to print operations progressparallel_params (
Union
[bool
,Sequence
[str
]]) – Optionally, specifies which fixed parameters (i.e. the attributes initialized in the child-most class’s __init__) take on different values for different parallel jobs. Fixed parameters specified by parallel_params are assumed to be a Sequence of values that should be used for that parameter in each parallel job; the length of this Sequence should equal the number of parallel jobs. If parallel_params=True, every fixed parameter will take on a different value for each parallel job. If parallel_params=False, every fixed parameter will take on the same value for each parallel job. If parallel_params is a Sequence of fixed attribute names, only those attribute names specified will take on different values between different parallel jobs.mask_components (
bool
) – Optionally, whether or not to automatically apply any provided component_mask`s to the `TimeSeries inputs passed to transform, fit, inverse_transform, or fit_transform. If True, any specified component_mask will be applied to each input timeseries before passing them to the called method; the masked components will also be automatically ‘unmasked’ in the returned TimeSeries. If False, then component_mask (if provided) will be passed as a keyword argument, but won’t automatically be applied to the input timeseries. See apply_component_mask method of BaseDataTransformer for further details.global_fit (
bool
) – Optionally, whether all of the TimeSeries passed to the fit() method should be used to fit a single set of parameters, or if a different set of parameters should be independently fitted to each provided TimeSeries. If True, then a Sequence[TimeSeries] is passed to ts_fit and a single set of parameters is fitted using all of the provided TimeSeries. If False, then each TimeSeries is individually passed to ts_fit, and a different set of fitted parameters if yielded for each of these fitting operations. See ts_fit for further details.
Notes
If global_fit is False and fit is called with a Sequence containing n different TimeSeries, then n sets of parameters will be fitted. When transform and/or inverse_transform is subsequently called with a Series[TimeSeries], the i`th set of fitted parameter values will be passed to `ts_transform/ts_inverse_transform to transform the i`th `TimeSeries in this sequence. Conversely, if global_fit is True, then only a single set of fitted values will be produced when fit is provided with a Sequence[TimeSeries]. Consequently, if a Sequence[TimeSeries] is then passed to transform/inverse_transform, each of these TimeSeries will be transformed using the exact same set of fitted parameters.
Note that if an invertible and fittable data transformer is to be globally fitted, the data transformer class should first inherit from FittableDataTransformer and then from InveritibleDataTransformer. In other words, MyTransformer(FittableDataTransformer, InveritibleDataTransformer) is correct, but MyTransformer(InveritibleDataTransformer, FittableDataTransformer) is not. If this is not implemented correctly, then the global_fit parameter will not be correctly passed to FittableDataTransformer’s constructor.
The
ts_transform()
andts_fit()
methods are designed to be static methods instead of instance methods to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using instance methods would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.Example
>>> from darts.dataprocessing.transformers import FittableDataTransformer >>> from darts.utils.timeseries_generation import linear_timeseries >>> >>> class SimpleRangeScaler(FittableDataTransformer): >>> >>> def __init__(self, scale, position): >>> self._scale = scale >>> self._position = position >>> super().__init__() >>> >>> @staticmethod >>> def ts_transform(series, params): >>> vals = series.all_values(copy=False) >>> fit_params = params['fitted'] >>> unit_scale = (vals - fit_params['position'])/fit_params['scale'] >>> fix_params = params['fixed'] >>> rescaled = fix_params['_scale'] * unit_scale + fix_params['_position'] >>> return series.from_values(rescaled) >>> >>> @staticmethod >>> def ts_fit(series, params): >>> vals = series.all_values(copy=False) >>> scale = vals.max() - vals.min() >>> position = vals[0] >>> return {'scale': scale, 'position': position} >>> >>> series = linear_timeseries(length=5, start_value=1, end_value=5) >>> print(series) <TimeSeries (DataArray) (time: 5, component: 1, sample: 1)> array([[[1.]],
[[2.]],
[[3.]],
[[4.]],
[[5.]]])
Coordinates: * time (time) datetime64[ns] 2000-01-01 2000-01-02 … 2000-01-05 * component (component) object ‘linear’ Dimensions without coordinates: sample .. attribute:: static_covariates
None
- hierarchy¶
None
>>> series = SimpleRangeScaler(scale=2, position=-1).fit_transform(series) >>> print(series) <TimeSeries (DataArray) (time: 5, component: 1, sample: 1)> array([[[-1. ]],
[[-0.5]],
[[ 0. ]],
[[ 0.5]],
[[ 1. ]]])
Coordinates: * time (time) int64 0 1 2 3 4 * component (component) <U1 ‘0’ Dimensions without coordinates: sample .. attribute:: static_covariates
None
- hierarchy¶
None
Attributes
Name of the data transformer.
Methods
apply_component_mask
(series[, ...])Extracts components specified by component_mask from series
fit
(series, *args[, component_mask])Fits transformer to a (sequence of) TimeSeries by calling the user-implemented ts_fit method.
fit_transform
(series, *args[, component_mask])Fit the transformer to the (sequence of) series and return the transformed input.
set_n_jobs
(value)Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.set_verbose
(value)Set the verbosity status.
stack_samples
(vals)Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
transform
(series, *args[, component_mask])Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
ts_fit
(series, params, *args, **kwargs)The function that will be applied to each series when
fit()
is called.ts_transform
(series, params, *args, **kwargs)The function that will be applied to each series when
transform()
is called.unapply_component_mask
(series, vals[, ...])Adds back components previously removed by component_mask in apply_component_mask method.
unstack_samples
(vals[, n_timesteps, ...])Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this 'undoes' the reshaping of stack_samples.
get_projection_matrix
- static apply_component_mask(series, component_mask=None, return_ts=False)¶
Extracts components specified by component_mask from series
- Parameters
series (
TimeSeries
) – input TimeSeries to be fed into transformer.component_mask (
Optional
[ndarray
]) – Optionally, np.ndarray boolean mask of shape (n_components, 1) specifying which components to extract from series. The i`th component of `series is kept only if component_mask[i] = True. If not specified, no masking is performed.return_ts – Optionally, specifies that a TimeSeries should be returned, rather than an np.ndarray.
- Returns
TimeSeries (if return_ts = True) or np.ndarray (if return_ts = False) with only those components specified by component_mask remaining.
- Return type
masked
- fit(series, *args, component_mask=None, **kwargs)¶
Fits transformer to a (sequence of) TimeSeries by calling the user-implemented ts_fit method.
The fitted parameters returned by ts_fit are stored in the
self._fitted_params
attribute. If a Sequence[TimeSeries] is passed as the series data, then one of two outcomes will occur:1. If the global_fit attribute was set to False, then a different set of parameters will be individually fitted to each TimeSeries in the Sequence. In this case, this function automatically parallelises this fitting process over all of the multiple TimeSeries that have been passed. 2. If the global_fit attribute was set to True, then all of the TimeSeries objects will be used fit a single set of parameters.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – (sequence of) series to fit the transformer on.args – Additional positional arguments for the
ts_fit()
methodcomponent_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should be fitted to.kwargs – Additional keyword arguments for the
ts_fit()
method
- Returns
Fitted transformer.
- Return type
- fit_transform(series, *args, component_mask=None, **kwargs)¶
Fit the transformer to the (sequence of) series and return the transformed input.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – the (sequence of) series to transform.args – Additional positional arguments passed to the
ts_transform()
andts_fit()
methods.component_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should be fitted and applied to.kwargs – Additional keyword arguments passed to the
ts_transform()
andts_fit()
methods.
- Returns
Transformed data.
- Return type
Union[TimeSeries, Sequence[TimeSeries]]
- property name¶
Name of the data transformer.
- set_n_jobs(value)¶
Set the number of processors to be used by the transformer while processing multiple
TimeSeries
.- Parameters
value (
int
) – New n_jobs value. Set to -1 for using all the available cores.
- set_verbose(value)¶
Set the verbosity status.
True for enabling the detailed report about scaler’s operation progress, False for no additional information.
- Parameters
value (
bool
) – New verbosity status
- static stack_samples(vals)¶
Creates an array of shape (n_timesteps * n_samples, n_components) from either a TimeSeries or the array_values of a TimeSeries.
Each column of the returned array corresponds to a component (dimension) of the series and is formed by concatenating all of the samples associated with that component together. More specifically, the i`th column is formed by concatenating `[component_i_sample_1, component_i_sample_2, …, component_i_sample_n].
Stacking is useful when implementing a transformation that applies the exact same change to every timestep in the timeseries. In such cases, the samples of each component can be stacked together into a single column, and the transformation can then be applied to each column, thereby ‘vectorising’ the transformation over all samples of that component; the unstack_samples method can then be used to reshape the output. For transformations that depend on the time_index or the temporal ordering of the observations, stacking should not be employed.
- Parameters
vals (
Union
[ndarray
,TimeSeries
]) – Timeseries or np.ndarray of shape (n_timesteps, n_components, n_samples) to be ‘stacked’.- Returns
np.ndarray of shape (n_timesteps * n_samples, n_components), where the i`th column is formed by concatenating all of the samples of the `i`th component in `vals.
- Return type
stacked
- transform(series, *args, component_mask=None, **kwargs)¶
Transforms a (sequence of) of series by calling the user-implemeneted ts_transform method.
In case a
Sequence[TimeSeries]
is passed as input data, this function takes care of parallelising the transformation of multiple series in the sequence at the same time. Additionally, if the mask_components attribute was set to True when instantiating BaseDataTransformer, then any provided component_mask`s will be automatically applied to each input `TimeSeries; please refer to ‘Notes’ for further details on component masking.Any additionally specified *args and **kwargs are automatically passed to ts_transform.
- Parameters
series (
Union
[TimeSeries
,Sequence
[TimeSeries
]]) – (sequence of) series to be transformed.args – Additional positional arguments for each
ts_transform()
method callcomponent_mask (Optional[np.ndarray] = None) – Optionally, a 1-D boolean np.ndarray of length
series.n_components
that specifies which components of the underlying series the transform should consider. If the mask_components attribute was set to True when instantiating BaseDataTransformer, then the component mask will be automatically applied to each TimeSeries input. Otherwise, component_mask will be provided as an addition keyword argument to ts_transform. See ‘Notes’ for further details.kwargs – Additional keyword arguments for each
ts_transform()
method call
- Returns
Transformed data.
- Return type
Union[TimeSeries, List[TimeSeries]]
Notes
If the mask_components attribute was set to True when instantiating BaseDataTransformer, then any provided component_mask`s will be automatically applied to each `TimeSeries input to transform; component_mask`s are simply boolean arrays of shape `(series.n_components,) that specify which components of each series should be transformed using ts_transform and which components should not. If component_mask[i] is True, then the i`th component of each `series will be transformed by ts_transform. Conversely, if component_mask[i] is False, the i`th component will be removed from each `series before being passed to ts_transform; after transforming this masked series, the untransformed i`th component will be ‘added back’ to the output. Note that automatic `component_mask`ing can only be performed if the `ts_transform does not change the number of timesteps in each series; if this were to happen, then the transformed and untransformed components are unable to be concatenated back together along the component axis.
If mask_components was set to False when instantiating BaseDataTransformer, then any provided component_masks will be passed as a keyword argument ts_transform; the user can then manually specify how the component_mask should be applied to each series.
- static ts_fit(series, params, *args, **kwargs)[source]¶
The function that will be applied to each series when
fit()
is called.If the global_fit attribute is set to False, then ts_fit should accept a TimeSeries as a first argument and return a set of parameters that are fitted to this individual TimeSeries. Conversely, if the global_fit attribute is set to True, then ts_fit should accept a Sequence[TimeSeries] and return a set of parameters that are fitted to all of the provided TimeSeries. All these parameters will be stored in
self._fitted_params
, which can be later used during the transformation step.Regardless of whether the global_fit attribute is set to True or False, ts_fit should also accept a dictionary of fixed parameter values as a second argument (i.e. `params[‘fixed’] contains the fixed parameters of the data transformer).
Any additional positional and/or keyword arguments passed to the fit method will be passed as positional/keyword arguments to ts_fit.
This method is not implemented in the base class and must be implemented in the deriving classes.
If more parameters are added as input in the derived classes,
_fit_iterator()
should be redefined accordingly, to yield the necessary arguments to this function (See_fit_iterator()
for further details)- Parameters
(Union[TimeSeries (series) – TimeSeries against which the scaler will be fit.
Sequence[TimeSeries]]) – TimeSeries against which the scaler will be fit.
Notes
This method is designed to be a static method instead of instance methods to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using instance methods would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.
- Return type
ndarray
- static ts_transform(series, params, *args, **kwargs)[source]¶
The function that will be applied to each series when
transform()
is called.This method is not implemented in the base class and must be implemented in the deriving classes.
The function must take as first argument a
TimeSeries
object and, as a second argument, a dictionary containing the fixed and/or fitted parameters of the transformation; this function should then return a transformedTimeSeries
object.- The params dictionary can contain up to two keys:
1. params[‘fixed’] stores the fixed parameters of the transformation (i.e. attributed defined in the __init__ method of the child-most class before super().__init__ is called); params[‘fixed’] is a dictionary itself, whose keys are the names of the fixed parameter attributes. For example, if _my_fixed_param is defined as an attribute in the child-most class, then this fixed parameter value can be accessed through params[‘fixed’][‘_my_fixed_param’]. 2. If the transform inherits from the
FittableDataTransformer
class, then params[‘fitted’] will store the fitted parameters of the transformation; the fitted parameters are simply the output(s) returned by the ts_fit function, whatever those output(s) may be. SeeFittableDataTransformer
for further details about fitted parameters.
Any positional/keyword argument supplied to the transform method are passed as positional/keyword arguments to ts_transform; hence, ts_transform should also accept *args and/or **kwargs if positional/keyword arguments are passed to transform. Note that if the mask_components attribute of BaseDataTransformer is set to False, then the component_mask provided to transform will be passed as an additional keyword argument to ts_transform.
The BaseDataTransformer class includes some helper methods which may prove useful when implementing a ts_transform function:
1. The apply_component_mask and unapply_component_mask methods, which apply and ‘unapply’ component_mask`s to a `TimeSeries respectively; these methods are automatically called in transform if the mask_component attribute of BaseDataTransformer is set to True, but you may want to manually call them if you set mask_components to False and wish to manually specify how component_mask`s are applied to a `TimeSeries. 2. The stack_samples method, which stacks all the samples in a TimeSeries along the component axis, so that the TimeSeries goes from shape (n_timesteps, n_components, n_samples) to shape (n_timesteps, n_components * n_samples). This stacking is useful if a pointwise transform is being implemented (i.e. transforming the value at time t depends only on the value of the series at that time t). Once transformed, the stacked TimeSeries can be ‘unstacked’ using the unstack_samples method.
- Parameters
series (
TimeSeries
) – series to be transformed.params (
Mapping
[str
,Any
]) – Dictionary containing the parameters of the transformation function. Fixed parameters (i.e. attributes defined in the child-most class of the transformation prior to calling super.__init__()) are stored under the ‘fixed’ key. If the transformation inherits from the FittableDataTransformer class, then the fitted parameters of the transformation (i.e. the values returned by ts_fit) are stored under the ‘fitted’ key.args – Any poisitional arguments provided in addition to series when
kwargs – Any additional keyword arguments provided to transform. Note that if the mask_component attribute of BaseDataTransformer is set to False, then component_mask will be passed as a keyword argument.
Notes
This method is designed to be a static method instead of instance method to allow an efficient parallelisation also when the scaler instance is storing a non-negligible amount of data. Using instance methods would imply copying the instance’s data through multiple processes, which can easily introduce a bottleneck and nullify parallelisation benefits.
- Return type
- static unapply_component_mask(series, vals, component_mask=None)¶
Adds back components previously removed by component_mask in apply_component_mask method.
- Parameters
series (
TimeSeries
) – input TimeSeries that was fed into transformer.vals (
Union
[ndarray
,TimeSeries
]) – np.ndarray or TimeSeries to ‘unmask’component_mask (
Optional
[ndarray
]) – Optionally, np.ndarray boolean mask of shape (n_components, 1) specifying which components were extracted from series. If given, insert vals back into the columns of the original array. If not specified, nothing is ‘unmasked’.
- Returns
TimeSeries (if vals is a TimeSeries) or np.ndarray (if vals is an np.ndarray) with those components previously removed by component_mask now ‘added back’.
- Return type
unmasked
- static unstack_samples(vals, n_timesteps=None, n_samples=None, series=None)¶
Reshapes the 2D array returned by stack_samples back into an array of shape (n_timesteps, n_components, n_samples); this ‘undoes’ the reshaping of stack_samples. Either n_components, n_samples, or series must be specified.
- Parameters
vals (
ndarray
) – np.ndarray of shape (n_timesteps * n_samples, n_components) to be ‘unstacked’.n_timesteps (
Optional
[int
]) – Optionally, the number of timesteps in the array originally passed to stack_samples. Does not need to be provided if series is specified.n_samples (
Optional
[int
]) – Optionally, the number of samples in the array originally passed to stack_samples. Does not need to be provided if series is specified.series (
Optional
[TimeSeries
]) – Optionally, the TimeSeries object used to create vals; n_samples is inferred from this.
- Returns
np.ndarray of shape (n_timesteps, n_components, n_samples).
- Return type
unstacked