Skip to content

[FEATURE] Add TimeSeriesSequence collection type for more accessible multiple time series representation #3037

@brunnedu

Description

@brunnedu

Is your feature request related to a current problem? Please describe.
Working with multiple time series is central to many darts use cases. However the current list[TimeSeries] representation is opaque. Users cannot quickly discover what series they have (frequencies, lengths, date ranges), filter by metadata, or get a high-level summary like pd.DataFrame.describe(). Each TimeSeries carries static_covariates and metadata, but there is no collection-level API to query across them.

Describe proposed solution
Add a TimeSeriesSequence class: an immutable Sequence[TimeSeries] wrapper with collection-level convenience methods. It would implement collections.abc.Sequence, so it works everywhere list[TimeSeries] is accepted today (models, transformers, utilities) with no changes to existing call sites.

Desired Features:

  • Construction: TimeSeriesSequence([...]), TimeSeriesSequence.from_group_dataframe(df, group_cols=...)
  • Discovery: catalog (lazy one-row-per-series metadata DataFrame), describe() (summary statistics), info() (compact text summary)
  • Filtering: filter(callable) — e.g. seq.filter(lambda ts: ts.n_timesteps > 100)
  • Conversion: to_list(), to_dataframe() (wraps to_group_dataframe)
  • Representation: repr and repr_html for terminal and Jupyter

Describe potential alternatives

  • Stay with list[TimeSeries]: Manual loops and comprehensions for discovery and filtering.
  • Use to_group_dataframe() as the query layer: Convert to DataFrame, filter/summarize, then reconstruct via from_group_dataframe(). Cumbersome and forces users to leave the TimeSeries abstraction.

Additional context

  • The existing internal machinery (get_series_seq_type(), series2seq()) uses duck typing, not isinstance(ts, list), so TimeSeriesSequence inputs already work through models and transformers. No library changes required for acceptance.
  • TimeSeries is immutable; making TimeSeriesSequence immutable follows the same philosophy.
  • The lazy catalog avoids metadata extraction cost for users who only need indexing or iteration, while making describe() and filter() fast once materialized.

Metadata

Metadata

Assignees

Labels

core improvementSignificant change, refactor or improvementfeature requestUse this label to request a new feature

Type

No type

Projects

Status

In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions