|
3 | 3 | <i>An open source project from Data to AI Lab at MIT.</i> |
4 | 4 | </p> |
5 | 5 |
|
6 | | -[](https://pypi.python.org/pypi/cents) |
7 | | -[](https://pepy.tech/project/cents) |
| 6 | +[](https://pypi.python.org/pypi/cents-ml) |
| 7 | +[](https://pepy.tech/project/cents-ml) |
8 | 8 | [](https://github.com/DAI-Lab/Cents/actions) |
9 | 9 |
|
10 | 10 |
|
11 | 11 | # Cents |
12 | 12 |
|
13 | 13 | A library for generative modeling and evaluation of synthetic household-level electricity load timeseries. This package is still under active development. |
14 | 14 |
|
15 | | -- Documentation: (tbd) |
| 15 | +- [Documentation](https://dtail.gitbook.io/cents) |
16 | 16 |
|
17 | 17 | # Overview |
18 | 18 |
|
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. |
20 | 20 |
|
21 | | -These currently supported models are: |
| 21 | +Cents was used to train the [Watts](https://huggingface.co/michaelfuest/watts) model series. |
22 | 22 |
|
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. |
27 | 24 |
|
28 | 25 | # Install |
29 | 26 |
|
30 | 27 | ## Requirements |
31 | 28 |
|
32 | 29 | **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/)). |
33 | 30 |
|
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. |
37 | 32 |
|
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: |
39 | 34 |
|
40 | 35 | ```bash |
41 | | -pip install virtualenv |
42 | | -virtualenv -p $(which python3.9) cents-venv |
| 36 | +poetry install |
43 | 37 | ``` |
44 | 38 |
|
45 | | -Afterwards, you have to execute this command to activate the virtualenv: |
| 39 | +Once installed, activate the virtual environment: |
46 | 40 |
|
47 | 41 | ```bash |
48 | | -source cents-venv/bin/activate |
| 42 | +poetry shell |
49 | 43 | ``` |
50 | 44 |
|
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. |
52 | 46 |
|
53 | 47 | ## Install from PyPI |
54 | 48 |
|
55 | | -After creating the virtualenv and activating it, we recommend using |
| 49 | +If you are only interested in using Cents functionality, we recommend using |
56 | 50 | [pip](https://pip.pypa.io/en/stable/) in order to install **Cents**: |
57 | 51 |
|
58 | 52 | ```bash |
59 | | -pip install cents |
| 53 | +pip install cents-ml |
60 | 54 | ``` |
61 | 55 |
|
62 | 56 | 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. --> |
119 | 57 |
|
120 | 58 | ## Datasets |
121 | 59 |
|
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: |
123 | 61 |
|
124 | 62 | - 15minute_data_austin.csv |
125 | 63 | - 15minute_data_california.csv |
|
0 commit comments