# cardtale
[](https://pypi.org/project/cardtale/)
[](https://github.com/vcerqueira/cardtale)
[](https://pepy.tech/project/cardtale)
**cardtale** is a Python package for generating automated model
and data cards for time series, streamlining the documentation process
for machine learning models and datasets.
### Key Features
- Automated generation of PDF reports with comprehensive time series analysis
- Built-in statistical analysis and visualization of temporal patterns
- Support for univariate time series data
Each time series is studied from multiple dimensions, including:
- **Data Overview**: Fundamental characteristics and statistical properties analysis
- **Trend Analysis**: Long-term growth patterns and level stabilization assessment
- **Seasonality Detection**: Analysis of multiple seasonality levels with strength metrics
- **Variance Analysis**: Heteroskedasticity testing and variance stabilization methods
- **Change Point Detection**: Identification of structural changes and their impact
## Basic Example
Here's a basic example of **cardtale**.
```python
from datasetsforecast.m3 import M3
from cardtale.cards.builder import CardsBuilder
df, *_ = M3.load('./assets', group='Monthly')
freq = 'ME'
uid = 'M1080'
series_df = df.query(f'unique_id=="{uid}"').reset_index(drop=True)
tcard = CardsBuilder(series_df, freq)
tcard.build_cards()
tcard.get_pdf(path='example.pdf')
```
### Screenshots
### **⚠️ WARNING**
> cardtale is in the early stages of development.
> It is designed to cover datasets containing single univariate time series, focusing on forecasting tasks.
>
> cardtale has been developed for monthly time series. So, the output for other frequencies may not be as reliable.
> Especially time series with complex seasonality.
>
> If you encounter any issues, please report
> them in [GitHub Issues](https://github.com/vcerqueira/cardtale/issues)
## Installation
### Prerequisites
Required dependencies:
```
arch==7.1.0
pandas==2.2.3
lightgbm==4.5.0
neuralforecast==1.7.5
mlforecast==0.13.4
statsforecast==1.7.8
datasetsforecast==0.0.8
numerize==0.12
plotnine==0.13.6
statsmodels==0.14.4
jinja2==3.1.4
ruptures==1.1.9
weasyprint==62.3
```
You can install **cardtale** using pip:
```bash
pip install cardtale -U
```
### [Optional] Installation from source
To install cardtale from source, clone the repository and run the following command:
```bash
git clone https://github.com/vcerqueira/cardtale
pip install -e cardtale
```
## License
Cardtale is released under the MIT License. See the [LICENSE](LICENSE) file for more details.
## Mission
In the machine learning lifecycle,
proper documentation of models and datasets is crucial for transparency,
reproducibility, and responsible AI practices.
However, creating comprehensive model and data cards can be time-consuming.
The Python package **cardtale** aims to partially automate this
process, making it more efficient and consistent.
The goal of **cardtale** is to generate a set of analyses,
visualizations, and interpretations based on input model
metrics and dataset characteristics.
While it doesn't replace the expertise of data scientists or
domain experts, Cardtale speeds up the creation of model and
data cards, guiding analysts towards key insights and
areas that may require further exploration.
### Project Funded by
> Agenda “Center for Responsible AI”, nr. C645008882-00000055, investment project nr. 62, financed by the Recovery and Resilience Plan (PRR) and by European Union - NextGeneration EU.
Raw data
{
"_id": null,
"home_page": null,
"name": "cardtale",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Data Cards, Data Science, Forecasting, Machine Learning, Model Cards, Time Series",
"author": null,
"author_email": "Vitor Cerqueira <cerqueira.vitormanuel@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2c/da/2bf0b883826b5ccc532cc400bfd6b4b27b0df309f1529d6175e03f61bab7/cardtale-0.1.2.tar.gz",
"platform": null,
"description": "# cardtale\n\n\n[](https://pypi.org/project/cardtale/)\n[](https://github.com/vcerqueira/cardtale)\n[](https://pepy.tech/project/cardtale)\n\n\n**cardtale** is a Python package for generating automated model \nand data cards for time series, streamlining the documentation process \nfor machine learning models and datasets.\n\n### Key Features\n\n- Automated generation of PDF reports with comprehensive time series analysis\n- Built-in statistical analysis and visualization of temporal patterns\n- Support for univariate time series data\n\nEach time series is studied from multiple dimensions, including:\n- **Data Overview**: Fundamental characteristics and statistical properties analysis\n- **Trend Analysis**: Long-term growth patterns and level stabilization assessment\n- **Seasonality Detection**: Analysis of multiple seasonality levels with strength metrics\n- **Variance Analysis**: Heteroskedasticity testing and variance stabilization methods\n- **Change Point Detection**: Identification of structural changes and their impact\n\n## Basic Example\n\nHere's a basic example of **cardtale**.\n\n```python\nfrom datasetsforecast.m3 import M3\nfrom cardtale.cards.builder import CardsBuilder\n\ndf, *_ = M3.load('./assets', group='Monthly')\n\nfreq = 'ME'\nuid = 'M1080'\n\nseries_df = df.query(f'unique_id==\"{uid}\"').reset_index(drop=True)\n\ntcard = CardsBuilder(series_df, freq)\ntcard.build_cards()\ntcard.get_pdf(path='example.pdf')\n\n```\n\n### Screenshots\n\n\n\n\n\n\n\n\n\n\n\n\n\n### **\u26a0\ufe0f WARNING**\n\n> cardtale is in the early stages of development. \n> It is designed to cover datasets containing single univariate time series, focusing on forecasting tasks.\n> \n> cardtale has been developed for monthly time series. So, the output for other frequencies may not be as reliable. \n> Especially time series with complex seasonality.\n> \n> If you encounter any issues, please report\n> them in [GitHub Issues](https://github.com/vcerqueira/cardtale/issues)\n\n\n## Installation\n\n### Prerequisites\n\nRequired dependencies:\n```\narch==7.1.0\npandas==2.2.3\nlightgbm==4.5.0\nneuralforecast==1.7.5\nmlforecast==0.13.4\nstatsforecast==1.7.8\ndatasetsforecast==0.0.8\nnumerize==0.12\nplotnine==0.13.6\nstatsmodels==0.14.4\njinja2==3.1.4\nruptures==1.1.9\nweasyprint==62.3\n```\n\n\nYou can install **cardtale** using pip:\n\n```bash\npip install cardtale -U\n```\n\n### [Optional] Installation from source\n\nTo install cardtale from source, clone the repository and run the following command:\n\n```bash\ngit clone https://github.com/vcerqueira/cardtale\npip install -e cardtale\n```\n\n## License\n\nCardtale is released under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## Mission\n\nIn the machine learning lifecycle, \nproper documentation of models and datasets is crucial for transparency, \nreproducibility, and responsible AI practices. \nHowever, creating comprehensive model and data cards can be time-consuming. \nThe Python package **cardtale** aims to partially automate this \nprocess, making it more efficient and consistent.\n\nThe goal of **cardtale** is to generate a set of analyses, \nvisualizations, and interpretations based on input model \nmetrics and dataset characteristics. \nWhile it doesn't replace the expertise of data scientists or \ndomain experts, Cardtale speeds up the creation of model and \ndata cards, guiding analysts towards key insights and \nareas that may require further exploration.\n\n### Project Funded by\n\n> Agenda \u201cCenter for Responsible AI\u201d, nr. C645008882-00000055, investment project nr. 62, financed by the Recovery and Resilience Plan (PRR) and by European Union - NextGeneration EU.\n",
"bugtrack_url": null,
"license": null,
"summary": "Data, Model, and Algorithm Cards for Time Series",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/vcerqueira/cardtale/issues",
"Homepage": "https://github.com/vcerqueira/cardtale"
},
"split_keywords": [
"data cards",
" data science",
" forecasting",
" machine learning",
" model cards",
" time series"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "045ed571d6b95c429d07d5f37c621a59e6604436122e3961963545f0307f2c06",
"md5": "75ed246602261a42eb9124ebf85817b1",
"sha256": "f18a39a7fd6aaba4fdf961ce0e6651de1e44b343de80b005248629841c95bd39"
},
"downloads": -1,
"filename": "cardtale-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75ed246602261a42eb9124ebf85817b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 88939,
"upload_time": "2025-02-05T11:08:57",
"upload_time_iso_8601": "2025-02-05T11:08:57.385944Z",
"url": "https://files.pythonhosted.org/packages/04/5e/d571d6b95c429d07d5f37c621a59e6604436122e3961963545f0307f2c06/cardtale-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2cda2bf0b883826b5ccc532cc400bfd6b4b27b0df309f1529d6175e03f61bab7",
"md5": "bf03662b9a74a3da6b8872712d06e89f",
"sha256": "9b9e1bf45401570db7b4692c8620d66baf681f3a6eb9a146760f50bf178a4ad6"
},
"downloads": -1,
"filename": "cardtale-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "bf03662b9a74a3da6b8872712d06e89f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28479798,
"upload_time": "2025-02-05T11:09:01",
"upload_time_iso_8601": "2025-02-05T11:09:01.026206Z",
"url": "https://files.pythonhosted.org/packages/2c/da/2bf0b883826b5ccc532cc400bfd6b4b27b0df309f1529d6175e03f61bab7/cardtale-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-05 11:09:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vcerqueira",
"github_project": "cardtale",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cardtale"
}
JSON
