data Submodule

This submodule contains tools for working with time series datasets. For clarity, we need some definitions:

• An array is a Python object that has a similar signature to a numpy array or PyTorch tensor for indexing. In particular, it has shape and ndim properties and has a length.

• A series is a 2-dimensional array, where the 0th dimension indexs channel and the 1st dimension indexs time. If a 1-dimensional array is passed to a function expecting a series, it will be interpreted as a univariate series and coerced to 2 dimensions.

• A multiseries is a 3-dimensional array consisting of a collection of series, where the 0th dimension indexs the series, the 1st dimension indexs the channel, and the 2nd dimension indexs the time. If a 2-dimensional array is passed to a function expecting a multiseries, it will be interpreted as a single multivariate series and coerced to 3 dimensions.

• A dataset is a collection of one or more multiseries. The multiseries in the dataset must all have broadcastable shapes, except for the number of channels, which is allowed to vary. That is, for each multiseries in the dataset, the 0th (series) and 2nd (time) dimensions must either be equal or one.

class torchcast.data.SeriesDataset(*data: ArrayLike, return_length: int | None = None, transform: Callable | None = None, metadata: Metadata | List[Metadata] | None = None)

This is a base class for time series datasets. It is expected to only be used in a subclass, such as torchcast.data.TensorSeriesDataset.

Data held by a SeriesDataset is always returned in shape (channels, time steps), so that it can be stacked to form a batch of series in shape (series, channels, time steps).

split_by_time(t: int | float) → Tuple[SeriesDataset, SeriesDataset]

Splits the dataset by time.

Parameters:

t (int or float) – If this is an integer, then perform the split at this time. If it is a float, perform the split at this percentage of the time.

class torchcast.data.TensorSeriesDataset(*data: ArrayLike, return_length: int | None = None, transform: Callable | None = None, metadata: Metadata | List[Metadata] | None = None)

This encapsulates one or more torch.Tensor containing a multiseries as a dataset, for use in a torch.utils.data.DataLoader. The underlying data can be stored either as a torch.Tensor or as a ListOfTensors.

class torchcast.data.H5SeriesDataset(path: str, keys: List[str] | str, return_length: int | None = None, transform: Callable | None = None, metadata: Metadata | List[Metadata] | None = None)

This encapsulates a h5py.File containing a series stored on disk.

Utility Classes

class torchcast.data.Metadata(name: str | None = None, channel_names: List[str] | None = None, series_names: List[str] | None = None)

Metadata encapsulates metadata about a multiseries. In a torchcast.data.SeriesDataset, each multiseries will have a corresponding Metadata object. All fields of Metadata are optional. The fields that may be available are:

• name: Name of the multiseries.

• channel_names: A list of the names of each channel.

• series_names: A list of the names of each series.

check_consistency(multiseries: ArrayLike)

Checks if an array-like object is compatible with the metadata.

class torchcast.data.ListOfTensors(tensors: List[ArrayLike])

This is a ListOfArrayLike that is specialized to handling torch.Tensor.

Transforms

class torchcast.data.transforms.Transform

Transforms are data transformations applied to data series during dataloading, analogous to the members of torchvision.transforms. Transforms are expected to take multiple torch.Tensor as inputs, and may return an arbitrary object.

class torchcast.data.transforms.Normalize(means, stds)

Normalizes input tensors by subtracting the mean and dividing by the standard deviation. The transform expects to receive as many values for mean and standard deviation as there are series to be transformed. If multiple series are being transformed, and one or more of them should not be normalized - for example, if they are class labels - then substitute None for the mean in that case.