Skip to content

Commit 7d0d4d7

Browse files
author
Michael Fuest
committed
updated README
1 parent 30c93cf commit 7d0d4d7

File tree

2 files changed

+15
-88
lines changed

2 files changed

+15
-88
lines changed

MANIFEST.in

Lines changed: 0 additions & 11 deletions
This file was deleted.

README.md

Lines changed: 15 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -3,123 +3,61 @@
33
<i>An open source project from Data to AI Lab at MIT.</i>
44
</p>
55

6-
[![PyPI Shield](https://img.shields.io/pypi/v/Cents.svg)](https://pypi.python.org/pypi/cents)
7-
[![Downloads](https://pepy.tech/badge/cents)](https://pepy.tech/project/cents)
6+
[![PyPI Shield](https://img.shields.io/pypi/v/Cents.svg)](https://pypi.python.org/pypi/cents-ml)
7+
[![Downloads](https://pepy.tech/badge/cents-ml)](https://pepy.tech/project/cents-ml)
88
[![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)
99

1010

1111
# Cents
1212

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

15-
- Documentation: (tbd)
15+
- [Documentation](https://dtail.gitbook.io/cents)
1616

1717
# Overview
1818

19-
Cents is a library built for generating *synthetic household-level electric load and generation timeseries*. Cents supports several generative time series models 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. Trained models can be evaluated using a series of metrics and visualizations also implemented here.
19+
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.
2020

21-
These currently supported models are:
21+
Cents was used to train the [Watts](https://huggingface.co/michaelfuest/watts) model series.
2222

23-
- [Diffusion-TS](https://github.com/Y-debug-sys/Diffusion-TS/tree/main)
24-
- [ACGAN](https://arxiv.org/abs/1610.09585)
25-
26-
Feel free to look at our [tutorial notebooks]() to get started.
23+
Feel free to look at our [tutorial notebooks](https://github.com/DAI-Lab/Cents/tree/main/tutorials) to get started.
2724

2825
# Install
2926

3027
## Requirements
3128

3229
**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/)).
3330

34-
Also, although it is not strictly required, the usage of a [virtualenv](https://virtualenv.pypa.io/en/latest/)
35-
is highly recommended in order to avoid interfering with other software installed in the system
36-
in which **Cents** is run.
31+
We recommend using [Poetry](https://python-poetry.org/docs/) for dependency management. Make sure you have poetry installed before following these setup instructions.
3732

38-
These are the minimum commands needed to create a virtualenv using python3.8 for **Cents**:
33+
Poetry will automatically create a virtual environment and install all dependencies:
3934

4035
```bash
41-
pip install virtualenv
42-
virtualenv -p $(which python3.9) cents-venv
36+
poetry install
4337
```
4438

45-
Afterwards, you have to execute this command to activate the virtualenv:
39+
Once installed, activate the virtual environment:
4640

4741
```bash
48-
source cents-venv/bin/activate
42+
poetry shell
4943
```
5044

51-
Remember to execute it every time you start a new console to work on **Cents**!
45+
This gives you a clean, reproducible setup for development.
5246

5347
## Install from PyPI
5448

55-
After creating the virtualenv and activating it, we recommend using
49+
If you are only interested in using Cents functionality, we recommend using
5650
[pip](https://pip.pypa.io/en/stable/) in order to install **Cents**:
5751

5852
```bash
59-
pip install cents
53+
pip install cents-ml
6054
```
6155

6256
This will pull and install the latest stable release from [PyPI](https://pypi.org/).
63-
-->
64-
65-
<!-- ## Install from source
66-
67-
With your virtualenv activated, you can clone the repository and install it from
68-
source by running `make install` on the `stable` branch:
69-
70-
```bash
71-
git clone git@github.com:michael-fuest/Cents.git
72-
cd Cents
73-
git checkout stable
74-
make install
75-
``` -->
76-
77-
<!-- ## Install for Development
78-
79-
If you want to contribute to the project, a few more steps are required to make the project ready
80-
for development.
81-
82-
Please head to the [Contributing Guide](https://michael-fuest.github.io/Cents/contributing.html#get-started)
83-
for more details about this process. -->
84-
85-
<!-- # Quickstart
86-
87-
In this short tutorial we will guide you through a series of steps that will help you
88-
getting started with **Cents**.
89-
90-
## Generating Data
91-
92-
To get started, define a DataGenerator and specify the name of the model you would like to use.
93-
94-
```python
95-
generator = DataGenerator(model_name="diffusion_ts")
96-
```
97-
98-
We provide pre-trained model checkpoints that were trained on the [PecanStreet Dataport](https://www.pecanstreet.org/dataport/) dataset. You can use these checkpoints to load a trained model. The first step is to assign the `DataGenerator` a `TimeSeriesDataset`instance. We are using the `PecanStreetDataset` class here, which is an extension of `TimeSeriesDataset`.
99-
100-
```python
101-
dataset = PecanStreetDataset()
102-
generator.set_dataset(dataset)
103-
```
104-
105-
Once a dataset has been assigned, we can load a pre-trained model for that dataset as follows:
106-
107-
```python
108-
generator.load_model()
109-
```
110-
111-
These pre-trained models are conditional models, meaning they require a set of conditioning variables to generate synthetic time series data. If you want to generate data for a random set of conditioning variables, you can do so as follows:
112-
113-
```python
114-
conditioning_variables = generator.sample_random_conditioning_variables()
115-
synthetic_data = generator.generate(conditioning_variables)
116-
```
117-
118-
For a more in-depth tutorial, please refer to the tutorial notebooks in the `tutorials` directory. -->
11957

12058
## Datasets
12159

122-
If you want to reproduce our models from scratch, you will need to download the [PecanStreet DataPort dataset](https://www.pecanstreet.org/dataport/) and place it under the path specified in `pecanstreet.yaml`. Specifically you will require the following files:
60+
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:
12361

12462
- 15minute_data_austin.csv
12563
- 15minute_data_california.csv

0 commit comments

Comments
 (0)