docstr: Abstract class for invertible transformers.
  
  All the deriving classes have to implement the static methods :func:`ts_transform()` and
  :func:`ts_inverse_transform()`. For information on how to implement the :func:`ts_transform` method,
  please refer to the :class:`.BaseDataTransformer` documentation.
  
  The :func:`ts_inverse_transform()` method should be implemented in a virtually identical way to the
  :func:`ts_transform()` method: it should accept a ``TimeSeries`` as a first argument, and a dictionary
  of fixed parameters (as well as fitted parameters if the transformation also inherits from
  `FittableDataTransformer`) as a second argument. Additionally, :func:`ts_inverse_transform()` should
  also accept `*args` and `**kwargs` if additional positional/keyword arguments are expected to be
  passed. The only difference between :func:`ts_inverse_transform()` and :func:`ts_transform()`
  is that the former should 'undo' the transformation made to a `TimeSeries` by the latter. Please
  refer to the :func:`ts_inverse_transform()` documentation for further information.
  
  This class takes care of parallelizing the transformation on multiple ``TimeSeries`` when possible.
  
  Parameters
  ----------
  name
      The data transformer's name
  n_jobs
      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
      Optionally, whether to print operations progress
  parallel_params
      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
      Optionally, whether 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.
  
  Notes
  -----
  Note: the :func:`ts_transform()` and :func:`ts_inverse_transform()` 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 InvertibleDataTransformer
  >>> from darts.utils.timeseries_generation import linear_timeseries
  >>>
  >>> class SimpleTransform(InvertibleDataTransformer):
  >>>
  >>>         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
  >>>
  >>>         @staticmethod
  >>>         def ts_inverse_transform(series, params, **kwargs):
  >>>             a = params['fixed']['_a']
  >>>             b = kwargs.pop('b')
  >>>             return (series - b) / a
  >>>
  >>> 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
  Attributes:
      static_covariates:  None
      hierarchy:          None
  >>> transform = SimpleTransform(a=2)
  >>> series = transform.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
  Attributes:
      static_covariates:  None
      hierarchy:          None
  >>> series = transform.inverse_transform(series, b=3)
  >>> 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
  Attributes:
      static_covariates:  None
      hierarchy:          None
code: def __init__(
      self,
      name: str = "InvertibleDataTransformer",
      n_jobs: int = 1,
      verbose: bool = False,
      parallel_params: Union[bool, Sequence[str]] = False,
      mask_components: bool = True,
  ):
      """Abstract class for invertible transformers.
  
      All the deriving classes have to implement the static methods :func:`ts_transform()` and
      :func:`ts_inverse_transform()`. For information on how to implement the :func:`ts_transform` method,
      please refer to the :class:`.BaseDataTransformer` documentation.
  
      The :func:`ts_inverse_transform()` method should be implemented in a virtually identical way to the
      :func:`ts_transform()` method: it should accept a ``TimeSeries`` as a first argument, and a dictionary
      of fixed parameters (as well as fitted parameters if the transformation also inherits from
      `FittableDataTransformer`) as a second argument. Additionally, :func:`ts_inverse_transform()` should
      also accept `*args` and `**kwargs` if additional positional/keyword arguments are expected to be
      passed. The only difference between :func:`ts_inverse_transform()` and :func:`ts_transform()`
      is that the former should 'undo' the transformation made to a `TimeSeries` by the latter. Please
      refer to the :func:`ts_inverse_transform()` documentation for further information.
  
      This class takes care of parallelizing the transformation on multiple ``TimeSeries`` when possible.
  
      Parameters
      ----------
      name
          The data transformer's name
      n_jobs
          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
          Optionally, whether to print operations progress
      parallel_params
          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
          Optionally, whether 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.
  
      Notes
      -----
      Note: the :func:`ts_transform()` and :func:`ts_inverse_transform()` 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 InvertibleDataTransformer
      >>> from darts.utils.timeseries_generation import linear_timeseries
      >>>
      >>> class SimpleTransform(InvertibleDataTransformer):
      >>>
      >>>         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
      >>>
      >>>         @staticmethod
      >>>         def ts_inverse_transform(series, params, **kwargs):
      >>>             a = params['fixed']['_a']
      >>>             b = kwargs.pop('b')
      >>>             return (series - b) / a
      >>>
      >>> 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
      Attributes:
          static_covariates:  None
          hierarchy:          None
      >>> transform = SimpleTransform(a=2)
      >>> series = transform.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
      Attributes:
          static_covariates:  None
          hierarchy:          None
      >>> series = transform.inverse_transform(series, b=3)
      >>> 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
      Attributes:
          static_covariates:  None
          hierarchy:          None
      """
      super().__init__(
          name=name,
          n_jobs=n_jobs,
          verbose=verbose,
          parallel_params=parallel_params,
          mask_components=mask_components,
      )
  
file_path: darts/darts/dataprocessing/transformers/invertible_data_transformer.py
imports: from abc import abstractmethod
  from typing import Any, List, Mapping, Optional, Sequence, Union
  import numpy
  from darts import TimeSeries
  from darts.logging import get_logger, raise_if_not
  from darts.utils import _build_tqdm_iterator, _parallel_apply
  from .base_data_transformer import BaseDataTransformer
label_desc: Use image node_id 1 to create a new InvertibleDataTransformer object from inherited base classes: BaseDataTransformer with example: obj = InvertibleDataTransformer(name, n_jobs, verbose, parallel_params, mask_components)