---

name: data-preparation description: "Format, load, cache, generate, preprocess, synchronize, and convert tslearn time-series data before modeling." disable-model-invocation: true metadata: disco-role: operating license: BSD 2-Clause

Data preparation

Start from the root tslearn router (../../SKILL.md) when the request is broader than preparation. Use this sub-skill when the task is specifically to make time-series data usable: shape it, clean it, load it, synthesize it, resample it, symbolize it, or convert it to another package format.

Owns

• tslearn.utils formatting, validation, text I/O, and conversion helpers.
• tslearn.preprocessing scalers, resampler, imputer, and feature synchronizer.
• tslearn.piecewise PAA, SAX, and 1d-SAX transforms plus inverse transforms.
• tslearn.datasets offline cached datasets and UCR/UEA loading/caching.
• tslearn.generators synthetic random-walk data.
• Interop with sklearn, pyts, seglearn, stumpy, and pandas-backed sktime, pyflux, tsfresh, plus cesium when installed.

Does not own

• Distance metrics or backend choice -> ../metrics-backends/SKILL.md.
• Clustering -> ../clustering/SKILL.md.
• Supervised model fitting -> ../supervised-models/SKILL.md.
• Forecasting -> ../forecasting/SKILL.md.
• Model serialization or persistence of learned estimators -> ../analysis-and-persistence/SKILL.md.
• Matrix profile -> route back through the root router (../../SKILL.md) or the sibling that owns profile-oriented analysis.

Read first

• references/workflows.md for end-to-end preparation sequences.
• references/interop.md for exact conversion shapes and optional-package requirements.
• references/troubleshooting.md for common shape, cache, pandas, cesium, and timestamp failures.
• scripts/data_preparation_smoke.py for a deterministic tiny-data check; run it with a Python environment that can import tslearn.

Typical route

1. Normalize raw sequences with to_time_series_dataset, check_dataset, or check_variable_length_input.
2. If the input has gaps or misaligned features, run TimeSeriesImputer and TimeSeriesFeatureSynchronizer.
3. If a fixed length is required, use TimeSeriesResampler.
4. If you need compression, apply PiecewiseAggregateApproximation, SymbolicAggregateApproximation, or OneD_SymbolicAggregateApproximation.
5. If you need an external format, use the matching helper from tslearn.utils.
6. If you need sample data, use CachedDatasets, UCR_UEA_datasets, random_walks, or random_walk_blobs.

Quick guardrails

• to_pyflux_dataset only accepts one time series and needs pandas.
• to_sktime_dataset, to_pyflux_dataset, and to_tsfresh_dataset need pandas.
• to_cesium_dataset and from_cesium_dataset need cesium.
• PAA, SAX, and 1d-SAX expect dense equal-length data; resample before using them on ragged inputs.
• TimeSeriesFeatureSynchronizer expects timestamps with the same shape as X and increasing timestamps per feature.
• TimeSeriesImputer(..., keep_trailing_nans=True) preserves padded variable-length tails.

Handoffs

• For backend-specific metric choice, leave this route and use ../metrics-backends/SKILL.md.
• For model training or evaluation, leave this route and use the sibling route that owns the estimator family.
• For loading a dataset that may download, prefer the dataset notes in references/workflows.md and references/troubleshooting.md before retrying.