Metadata-Version: 2.3
Name: cents-ml
Version: 1.0.1
Summary: A library for generating contextual timeseries data.
License: MIT
Author: Michael Fuest
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: accelerate (>=1.2.0,<2.0.0)
Requires-Dist: autoflake (>=2.3.1,<3.0.0)
Requires-Dist: black (>=24.10.0,<25.0.0)
Requires-Dist: botocore (>=1.36.24,<2.0.0)
Requires-Dist: dtaidistance (>=2.3.12,<3.0.0)
Requires-Dist: einops (>=0.8.0,<0.9.0)
Requires-Dist: huggingface-hub (>=0.32.0,<0.33.0)
Requires-Dist: hydra-core (>=1.3.2,<2.0.0)
Requires-Dist: ipykernel (>=6.29.5,<7.0.0)
Requires-Dist: isort (>=5.13.2,<6.0.0)
Requires-Dist: jupyter (>=1.1.1,<2.0.0)
Requires-Dist: matplotlib (>=3.9.4,<4.0.0)
Requires-Dist: mypy (>=1.13.0,<2.0.0)
Requires-Dist: numpy (>=2.0.0,<3.0.0)
Requires-Dist: omegaconf (>=2.3.0,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pre-commit (>=4.0.1,<5.0.0)
Requires-Dist: pytest (>=8.3.4,<9.0.0)
Requires-Dist: pytest-cov (>=6.0.0,<7.0.0)
Requires-Dist: pytorch-lightning (>=2.4.0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: scikit-learn (>=1.6.0,<2.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: sentencepiece (>=0.2.0,<0.3.0)
Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
Requires-Dist: torch (==2.6.0)
Requires-Dist: torchaudio (==2.6.0)
Requires-Dist: torchvision (>=0.21.0,<0.22.0)
Requires-Dist: transformers (>=4.48.0,<5.0.0)
Requires-Dist: wandb (>=0.19.6,<0.20.0)
Description-Content-Type: text/markdown

<p align="left">
<img width=15% src="https://dai.lids.mit.edu/wp-content/uploads/2018/06/Logo_DAI_highres.png" alt=“DAI-Lab” />
<i>An open source project from Data to AI Lab at MIT.</i>
</p>

[![PyPI Shield](https://img.shields.io/pypi/v/Cents.svg)](https://pypi.python.org/pypi/cents-ml)
[![Downloads](https://pepy.tech/badge/cents-ml)](https://pepy.tech/project/cents-ml)
[![GitHub Actions Build Status](https://github.com/DAI-Lab/Cents/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DAI-Lab/Cents/actions)


# Cents

A library for generative modeling and evaluation of synthetic household-level electricity load timeseries. This package is still under active development.

- [Documentation](https://dtail.gitbook.io/cents)

# Overview

Cents is a library built for generating *contextual time series data*. Cents supports several generative time series model architectures that can be used to train a time series data generator from scratch on a user-defined dataset. Additionally, Cents provides functionality for loading pre-trained model checkpoints that can be used to generate data instantly.

Cents was used to train the [Watts](https://huggingface.co/michaelfuest/watts) model series.

Feel free to look at our [tutorial notebooks](https://github.com/DAI-Lab/Cents/tree/main/tutorials) to get started.

# Install

## Requirements

**Cents** has been developed and tested on [Python 3.9]((https://www.python.org/downloads/)), [Python 3.10]((https://www.python.org/downloads/)) and [Python 3.11]((https://www.python.org/downloads/)).

We recommend using [Poetry](https://python-poetry.org/docs/) for dependency management. Make sure you have poetry installed before following these setup instructions.

Poetry will automatically create a virtual environment and install all dependencies:

```bash
poetry install
```

Once installed, activate the virtual environment:

```bash
poetry shell
```

This gives you a clean, reproducible setup for development.

## Install from PyPI

If you are only interested in using Cents functionality, we recommend using
[pip](https://pip.pypa.io/en/stable/) in order to install **Cents**:

```bash
pip install cents-ml
```

This will pull and install the latest stable release from [PyPI](https://pypi.org/).

## Datasets

If you want to reproduce the pretrained Watts model series from scratch, you will need to download the [PecanStreet DataPort dataset](https://www.pecanstreet.org/dataport/) and place it in an appropriate location specified in `cents/config/dataset/pecanstreet.yaml`. Specifically you will require the following files:

- 15minute_data_austin.csv
- 15minute_data_california.csv
- 15minute_data_newyork.csv
- metadata.csv

# What's next?

New models, new evaluation functionality and new datasets coming soon!

