Skip to content

timeseries

startorch.timeseries

Contain time series generators.

startorch.timeseries.BaseTimeSeriesGenerator

Bases: ABC

Define the base class to implement a time series generator.

Example usage:

>>> import torch
>>> from startorch.sequence import RandUniform
>>> from startorch.timeseries import SequenceTimeSeriesGenerator
>>> generator = SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
>>> generator
SequenceTimeSeriesGenerator(
  (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
  (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.BaseTimeSeriesGenerator.generate abstractmethod 

generate(
    seq_len: int,
    batch_size: int = 1,
    rng: Generator | None = None,
) -> dict[Hashable, Tensor]

Generate a time series.

Parameters:

Name Type Description Default
seq_len int

The sequence length.

 required
batch_size int

The batch size.

 1
rng Generator | None

An optional random number generator.

 None

Returns:

Type Description
dict[Hashable, Tensor]

A batch of time series.

Example usage:

>>> import torch
>>> from startorch.sequence import RandUniform
>>> from startorch.timeseries import SequenceTimeSeriesGenerator
>>> generator = SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.Concatenate

Bases: BaseTimeSeriesGenerator

Implement a time series generator that concatenates the outputs of multiple time series generators.

Note that the last value is used if there are duplicated keys.

Parameters:

Name Type Description Default
generators Sequence[BaseTimeSeriesGenerator | dict]

The time series generators or their configurations.

 required

TimeSeries usage:

>>> from startorch.timeseries import SequenceTimeSeriesGenerator, Concatenate
>>> from startorch.sequence import RandInt, RandUniform
>>> generator = Concatenate(
...     [
...         SequenceTimeSeriesGenerator(
...             generators={"value": RandUniform(), "time": RandUniform()},
...         ),
...         SequenceTimeSeriesGenerator(generators={"label": RandInt(0, 10)}),
...     ]
... )
>>> generator
ConcatenateTimeSeriesGenerator(
  (0): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (1): SequenceTimeSeriesGenerator(
      (label): RandIntSequenceGenerator(low=0, high=10, feature_size=())
    )
)
>>> generator.generate(seq_len=10, batch_size=5)
{'value': tensor([[...]]), 'time': tensor([[...]]), 'label': tensor([[...]])}

startorch.timeseries.ConcatenateTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator that concatenates the outputs of multiple time series generators.

Note that the last value is used if there are duplicated keys.

Parameters:

Name Type Description Default
generators Sequence[BaseTimeSeriesGenerator | dict]

The time series generators or their configurations.

 required

TimeSeries usage:

>>> from startorch.timeseries import SequenceTimeSeriesGenerator, Concatenate
>>> from startorch.sequence import RandInt, RandUniform
>>> generator = Concatenate(
...     [
...         SequenceTimeSeriesGenerator(
...             generators={"value": RandUniform(), "time": RandUniform()},
...         ),
...         SequenceTimeSeriesGenerator(generators={"label": RandInt(0, 10)}),
...     ]
... )
>>> generator
ConcatenateTimeSeriesGenerator(
  (0): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (1): SequenceTimeSeriesGenerator(
      (label): RandIntSequenceGenerator(low=0, high=10, feature_size=())
    )
)
>>> generator.generate(seq_len=10, batch_size=5)
{'value': tensor([[...]]), 'time': tensor([[...]]), 'label': tensor([[...]])}

startorch.timeseries.Merge

Bases: BaseTimeSeriesGenerator

Implement a time series creator that creates time series by combining several time series.

The time series are combined by using the time information.

Parameters:

Name Type Description Default
generators Sequence[BaseTimeSeriesGenerator | dict]

The time series generators or their configuration.

 required
time_key str

The key used to merge the time series by time.

 TIME

Example usage:

>>> from startorch.timeseries import Merge, SequenceTimeSeriesGenerator
>>> from startorch.sequence import RandUniform, RandNormal
>>> generator = Merge(
...     (
...         SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()}),
...         SequenceTimeSeriesGenerator({"value": RandNormal(), "time": RandNormal()}),
...     )
... )
>>> generator
MergeTimeSeriesGenerator(
  (time_key): time
  (0): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (1): SequenceTimeSeriesGenerator(
      (value): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
      (time): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
    )
)
>>> batch = generator.generate(seq_len=12, batch_size=10)
>>> batch
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.MergeTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series creator that creates time series by combining several time series.

The time series are combined by using the time information.

Parameters:

Name Type Description Default
generators Sequence[BaseTimeSeriesGenerator | dict]

The time series generators or their configuration.

 required
time_key str

The key used to merge the time series by time.

 TIME

Example usage:

>>> from startorch.timeseries import Merge, SequenceTimeSeriesGenerator
>>> from startorch.sequence import RandUniform, RandNormal
>>> generator = Merge(
...     (
...         SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()}),
...         SequenceTimeSeriesGenerator({"value": RandNormal(), "time": RandNormal()}),
...     )
... )
>>> generator
MergeTimeSeriesGenerator(
  (time_key): time
  (0): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (1): SequenceTimeSeriesGenerator(
      (value): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
      (time): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
    )
)
>>> batch = generator.generate(seq_len=12, batch_size=10)
>>> batch
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.MixedTimeSeries

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates time series by mixing two sequences of a time series.

Parameters:

Name Type Description Default
generator BaseTimeSeriesGenerator | dict

The time series generator or its configuration.

 required
key1 str

The key of the first sequence to mix.

 required
key2 str

The key of the second sequence to mix.

 required

Example usage:

>>> import torch
>>> from startorch.sequence import RandUniform
>>> from startorch.timeseries import MixedTimeSeries, SequenceTimeSeries
>>> generator = MixedTimeSeries(
...     SequenceTimeSeries({"key1": RandUniform(), "key2": RandUniform()}),
...     key1="key1",
...     key2="key2",
... )
>>> generator
MixedTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (key1): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (key2): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (key1): key1
  (key2): key2
)
>>> generator.generate(seq_len=12, batch_size=10)
{'key1': tensor([[...]]), 'key2': tensor([[...]])}

startorch.timeseries.MixedTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates time series by mixing two sequences of a time series.

Parameters:

Name Type Description Default
generator BaseTimeSeriesGenerator | dict

The time series generator or its configuration.

 required
key1 str

The key of the first sequence to mix.

 required
key2 str

The key of the second sequence to mix.

 required

Example usage:

>>> import torch
>>> from startorch.sequence import RandUniform
>>> from startorch.timeseries import MixedTimeSeries, SequenceTimeSeries
>>> generator = MixedTimeSeries(
...     SequenceTimeSeries({"key1": RandUniform(), "key2": RandUniform()}),
...     key1="key1",
...     key2="key2",
... )
>>> generator
MixedTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (key1): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (key2): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (key1): key1
  (key2): key2
)
>>> generator.generate(seq_len=12, batch_size=10)
{'key1': tensor([[...]]), 'key2': tensor([[...]])}

startorch.timeseries.MultinomialChoice

Bases: BaseTimeSeriesGenerator

Implement a time series generator that selecta a different time series generator at each batch.

This time series generator is used to generate time series with different generation processes. The user can specify a list of time series generators with an associated weight. The weight is used to sample the time series generator with a multinomial distribution. Higher weight means that the time series generator has a higher probability to be selected at each batch. Each dictionary in the generators input should have the following items:

- a key ``'generator'`` which indicates the time series
    generator or its configuration.
- an optional key ``'weight'`` with a float value which
    indicates the weight of the time series generator.
    If this key is absent, the weight is set to ``1.0``.

Parameters:

Name Type Description Default
generators Sequence[dict[str, BaseTimeSeriesGenerator | dict]]

The time series generators and their weights. See above to learn about the expected format.

 required

Example usage:

>>> from startorch.timeseries import MultinomialChoice, SequenceTimeSeries
>>> from startorch.sequence import RandUniform, RandNormal
>>> generator = MultinomialChoice(
...     (
...         {
...             "weight": 2.0,
...             "generator": SequenceTimeSeries(
...                 {"value": RandUniform(), "time": RandUniform()}
...             ),
...         },
...         {
...             "weight": 1.0,
...             "generator": SequenceTimeSeries(
...                 {"value": RandNormal(), "time": RandNormal()}
...             ),
...         },
...     )
... )
>>> generator
MultinomialChoiceTimeSeriesGenerator(
  (0) [weight=2.0] SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (1) [weight=1.0] SequenceTimeSeriesGenerator(
      (value): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
      (time): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.MultinomialChoiceTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator that selecta a different time series generator at each batch.

This time series generator is used to generate time series with different generation processes. The user can specify a list of time series generators with an associated weight. The weight is used to sample the time series generator with a multinomial distribution. Higher weight means that the time series generator has a higher probability to be selected at each batch. Each dictionary in the generators input should have the following items:

- a key ``'generator'`` which indicates the time series
    generator or its configuration.
- an optional key ``'weight'`` with a float value which
    indicates the weight of the time series generator.
    If this key is absent, the weight is set to ``1.0``.

Parameters:

Name Type Description Default
generators Sequence[dict[str, BaseTimeSeriesGenerator | dict]]

The time series generators and their weights. See above to learn about the expected format.

 required

Example usage:

>>> from startorch.timeseries import MultinomialChoice, SequenceTimeSeries
>>> from startorch.sequence import RandUniform, RandNormal
>>> generator = MultinomialChoice(
...     (
...         {
...             "weight": 2.0,
...             "generator": SequenceTimeSeries(
...                 {"value": RandUniform(), "time": RandUniform()}
...             ),
...         },
...         {
...             "weight": 1.0,
...             "generator": SequenceTimeSeries(
...                 {"value": RandNormal(), "time": RandNormal()}
...             ),
...         },
...     )
... )
>>> generator
MultinomialChoiceTimeSeriesGenerator(
  (0) [weight=2.0] SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (1) [weight=1.0] SequenceTimeSeriesGenerator(
      (value): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
      (time): RandNormalSequenceGenerator(mean=0.0, std=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.Periodic

Bases: BaseTimeSeriesGenerator

Implement a time series generator to generate periodic time series from a regular time series generator.

Parameters:

Name Type Description Default
timeseries BaseTimeSeriesGenerator | BasePeriodicTimeSeriesGenerator | dict

A time series generator or its configuration that is used to generate the periodic pattern.

 required
period BaseTensorGenerator | dict

The period length sampler or its configuration. This sampler is used to sample the period length at each batch.

 required

Example usage:

>>> from startorch.timeseries import Periodic, SequenceTimeSeries
>>> from startorch.sequence import RandUniform
>>> from startorch.tensor import RandInt
>>> generator = Periodic(
...     SequenceTimeSeries({"value": RandUniform(), "time": RandUniform()}),
...     period=RandInt(2, 5),
... )
>>> generator
PeriodicTimeSeriesGenerator(
  (sequence): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (period): RandIntTensorGenerator(low=2, high=5)
)
>>> generator.generate(seq_len=10, batch_size=2)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.PeriodicTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator to generate periodic time series from a regular time series generator.

Parameters:

Name Type Description Default
timeseries BaseTimeSeriesGenerator | BasePeriodicTimeSeriesGenerator | dict

A time series generator or its configuration that is used to generate the periodic pattern.

 required
period BaseTensorGenerator | dict

The period length sampler or its configuration. This sampler is used to sample the period length at each batch.

 required

Example usage:

>>> from startorch.timeseries import Periodic, SequenceTimeSeries
>>> from startorch.sequence import RandUniform
>>> from startorch.tensor import RandInt
>>> generator = Periodic(
...     SequenceTimeSeries({"value": RandUniform(), "time": RandUniform()}),
...     period=RandInt(2, 5),
... )
>>> generator
PeriodicTimeSeriesGenerator(
  (sequence): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (period): RandIntTensorGenerator(low=2, high=5)
)
>>> generator.generate(seq_len=10, batch_size=2)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.SequenceTimeSeries

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates time series with sequence generators.

Parameters:

Name Type Description Default
generators Mapping[str, BaseSequenceGenerator | dict]

The sequence generators or their configurations.

 required

Example usage:

>>> import torch
>>> from startorch.sequence import RandUniform
>>> from startorch.timeseries import SequenceTimeSeries
>>> generator = SequenceTimeSeries({"value": RandUniform(), "time": RandUniform()})
>>> generator
SequenceTimeSeriesGenerator(
  (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
  (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.SequenceTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates time series with sequence generators.

Parameters:

Name Type Description Default
generators Mapping[str, BaseSequenceGenerator | dict]

The sequence generators or their configurations.

 required

Example usage:

>>> import torch
>>> from startorch.sequence import RandUniform
>>> from startorch.timeseries import SequenceTimeSeries
>>> generator = SequenceTimeSeries({"value": RandUniform(), "time": RandUniform()})
>>> generator
SequenceTimeSeriesGenerator(
  (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
  (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.TensorTimeSeries

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates time series from tensor generators.

Parameters:

Name Type Description Default
generators Mapping[str, BaseTensorGenerator | dict]

The tensor generators or their configurations.

 required

Example usage:

>>> import torch
>>> from startorch.tensor import RandUniform
>>> from startorch.timeseries import TensorTimeSeriesGenerator
>>> generator = TensorTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
>>> generator
TensorTimeSeriesGenerator(
  (value): RandUniformTensorGenerator(low=0.0, high=1.0)
  (time): RandUniformTensorGenerator(low=0.0, high=1.0)
  (size): ()
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.TensorTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates time series from tensor generators.

Parameters:

Name Type Description Default
generators Mapping[str, BaseTensorGenerator | dict]

The tensor generators or their configurations.

 required

Example usage:

>>> import torch
>>> from startorch.tensor import RandUniform
>>> from startorch.timeseries import TensorTimeSeriesGenerator
>>> generator = TensorTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
>>> generator
TensorTimeSeriesGenerator(
  (value): RandUniformTensorGenerator(low=0.0, high=1.0)
  (time): RandUniformTensorGenerator(low=0.0, high=1.0)
  (size): ()
)
>>> generator.generate(seq_len=12, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.timeseries.TransformTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator that generates a batch of time series, and then transforms them.

Parameters:

Name Type Description Default
generator BaseTimeSeriesGenerator | dict

The time series generator or its configuration.

 required
transformer BaseTransformer | dict

The data transformer or its configuration.

 required

Example usage:

>>> from startorch.timeseries import TransformTimeSeriesGenerator, SequenceTimeSeries
>>> from startorch.transformer import TensorTransformer
>>> from startorch.sequence import RandUniform
>>> from startorch.tensor.transformer import Abs
>>> generator = TransformTimeSeriesGenerator(
...     generator=SequenceTimeSeries({"time": RandUniform(), "value": RandUniform()}),
...     transformer=TensorTransformer(
...         transformer=Abs(), input="value", output="value_transformed"
...     ),
... )
>>> generator
TransformTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
  (transformer): TensorTransformer(
      (transformer): AbsTensorTransformer()
      (input): value
      (output): value_transformed
      (exist_ok): False
    )
)
>>> generator.generate(batch_size=4, seq_len=12)
{'time': tensor([[[...]]]), 'value': tensor([[[...]]]), 'value_transformed': tensor([[[...]]])}

startorch.timeseries.VanillaTimeSeriesGenerator

Bases: BaseTimeSeriesGenerator

Implement a time series generator to "generate" the input data.

Parameters:

Name Type Description Default
data dict[Hashable, Tensor]

The time series data to generate. The dictionary cannot be empty.

 required

Raises:

Type Description
ValueError

if data is an empty dictionary.

TimeSeries usage:

>>> import torch
>>> from startorch.timeseries import VanillaTimeSeriesGenerator
>>> generator = VanillaTimeSeriesGenerator(
...     data={"value": torch.ones(4, 10), "time": torch.arange(40).view(4, 10)}
... )
>>> generator
VanillaTimeSeriesGenerator(batch_size=4, seq_len=10)
>>> generator.generate(batch_size=3, seq_len=6)
{'value': tensor([[1., 1., 1., 1., 1., 1.],
                  [1., 1., 1., 1., 1., 1.],
                  [1., 1., 1., 1., 1., 1.]]),
 'time': tensor([[ 0,  1,  2,  3,  4,  5],
                 [10, 11, 12, 13, 14, 15],
                 [20, 21, 22, 23, 24, 25]])}

startorch.timeseries.is_timeseries_generator_config 

is_timeseries_generator_config(config: dict) -> bool

Indicate if the input configuration is a configuration for a BaseTimeSeriesGenerator.

This function only checks if the value of the key _target_ is valid. It does not check the other values. If _target_ indicates a function, the returned type hint is used to check the class.

Parameters:

Name Type Description Default
config dict

The configuration to check.

 required

Returns:

Type Description
bool

True if the input configuration is a configuration for a BaseTimeSeriesGenerator object.

Example usage:

>>> from startorch.timeseries import is_timeseries_generator_config
>>> is_timeseries_generator_config(
...     {
...         "_target_": "startorch.timeseries.SequenceTimeSeriesGenerator",
...         "generators": {
...             "value": {"_target_": "startorch.sequence.RandUniform"},
...             "time": {"_target_": "startorch.sequence.RandUniform"},
...         },
...     }
... )
True

startorch.timeseries.setup_timeseries_generator 

setup_timeseries_generator(
    generator: BaseTimeSeriesGenerator | dict,
) -> BaseTimeSeriesGenerator

Set up a time series generator.

The time series generator is instantiated from its configuration by using the BaseTimeSeriesGenerator factory function.

Parameters:

Name Type Description Default
generator BaseTimeSeriesGenerator | dict

A time series generator or its configuration.

 required

Returns:

Type Description
BaseTimeSeriesGenerator

A time series generator.

Example usage:

>>> from startorch.timeseries import setup_timeseries_generator
>>> setup_timeseries_generator(
...     {
...         "_target_": "startorch.timeseries.SequenceTimeSeriesGenerator",
...         "generators": {
...             "value": {"_target_": "startorch.sequence.RandUniform"},
...             "time": {"_target_": "startorch.sequence.RandUniform"},
...         },
...     }
... )
SequenceTimeSeriesGenerator(
  (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
  (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)