tsam

library3.4.1pypypi✓ verified 84d ago

tsam is a time series aggregation module for creating typical periods (e.g., days or weeks) from high-resolution time series, commonly used in energy system modeling and other time series analysis. It provides methods like k-means clustering, hierarchical clustering, and averaging to reduce data while preserving key statistical features. Current version: 3.4.1, requires Python >=3.10, <3.15. Release cadence: periodic, with major version bumps for breaking changes.

analytics

pip install tsam

INSTALL

IMPORT

SIG · TSAM

tsam

analyticspythonv3.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TimeSeriesAggregation

✓ from tsam import TimeSeriesAggregation

aggregate

✓ from tsam import aggregate

Basic usage: create a TimeSeriesAggregation object from a pandas DataFrame and generate typical periods.

import pandas as pd from tsam import TimeSeriesAggregation # create example time series (5 time steps, 3 columns) raw = pd.DataFrame({ 'load': [100, 120, 110, 130, 125], 'pv': [0, 50, 80, 60, 10], 'wind': [30, 20, 25, 35, 40] }) # aggregate to 2 typical periods aggregator = TimeSeriesAggregation(raw, noTypicalPeriods=2) typical_periods = aggregator.createTypicalPeriods() print(typical_periods)

Debug

Known issues

breakingIn version 2.x and earlier, the main class was imported from 'tsam.tsam' or used differently. Version 3.x changed the import path to 'from tsam import TimeSeriesAggregation'.

fix

Update imports to 'from tsam import TimeSeriesAggregation' and adjust method calls according to v3 API.

affects: <=2.x

breakingThe parameter 'noTypicalPeriods' was renamed or changed behavior in v3. In v2, it was 'n_clusters'. Ensure you use the correct parameter names for your version.

fix

Use 'noTypicalPeriods' for v3, 'n_clusters' for v2. Check documentation for the version you are using.

affects: 2.x -> 3.x

gotchaThe input DataFrame must have a DateTime index or at least a monotonic index for proper handling of time steps. Without an index, tsam may misinterpret the order.

fix

Ensure raw.index is a DatetimeIndex or a monotonically increasing integer index. Use pd.DatetimeIndex or reset_index(drop=True) appropriately.

affects: all

deprecatedThe method 'createTypicalPeriods()' may be deprecated in future versions in favor of 'aggregate()' or similar. Currently both work.

fix

Prefer 'aggregator.aggregate()' if available; check changelog for transition.

affects: >=3.4

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tsam'

tsam is not installed or installed in a different environment.

fix

Run 'pip install tsam' in the correct Python environment.

AttributeError: module 'tsam' has no attribute 'TimeSeriesAggregation'

Attempting to import from an outdated version (pre-v3) where the class was in a submodule.

fix

Upgrade tsam to >=3.0.0 using 'pip install --upgrade tsam' and import using 'from tsam import TimeSeriesAggregation'.

ValueError: The number of typical periods must be less than or equal to the number of time steps.

Requesting more typical periods than the number of time steps in the input data.

fix

Reduce 'noTypicalPeriods' to a value less than or equal to len(raw).

TypeError: __init__() got an unexpected keyword argument 'n_clusters'

Using the old parameter name 'n_clusters' from version 2.x in version 3.x.

fix

Use 'noTypicalPeriods' instead of 'n_clusters' for the number of typical periods.

Upgrade

Version history

3.4.1latest on PyPI · released May 31, 2026

Audit

Dependencies

numpyrequiredArray operations and numerical computations.

pandasrequiredData structures for time series.

scikit-learnrequiredClustering algorithms (e.g., k-means, hierarchical).

pyomooptionalOptimization modeling for some aggregation methods (e.g., time series with constraints).

tqdmoptionalProgress bars for long computations.

Agent activity

43 hits · last 30 days

node

OpenAI (training)

Resources

No resource links recorded.