Metadata-Version: 2.4
Name: macrotrace
Version: 0.1.0rc1
Summary: A Python library for managing and analyzing macroeconomic time series data with vintage awareness.
Project-URL: Homepage, https://github.com/john-ramsey/macrotrace
Project-URL: Repository, https://github.com/john-ramsey/macrotrace
Project-URL: Issues, https://github.com/john-ramsey/macrotrace/issues
Project-URL: Documentation, https://john-ramsey.github.io/macrotrace/
Author-email: John Ramsey <john@johnramsey.com>
License: GNU General Public License v3.0 or later
License-File: LICENSE
Keywords: data-revisions,economic-data,economics,macroeconomics,time-series,vintages
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: darts>=0.35.0
Requires-Dist: numpy>=2.2.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: peewee>=4.0
Requires-Dist: plotly>=6.0.1
Requires-Dist: pytz>=2025.2
Requires-Dist: requests-cache>=1.2.1
Requires-Dist: requests>=2.32.3
Requires-Dist: statsmodels>=0.14.4
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tenacity>=9.1.2
Requires-Dist: tqdm>=4.67.1
Provides-Extra: ons-tui
Requires-Dist: rich>=13.9.4; extra == 'ons-tui'
Requires-Dist: textual>=0.89.1; extra == 'ons-tui'
Description-Content-Type: text/markdown

# MacroTrace

[![PyPI version](https://img.shields.io/pypi/v/macrotrace.svg)](https://pypi.org/project/macrotrace/)
[![Python versions](https://img.shields.io/pypi/pyversions/macrotrace.svg)](https://pypi.org/project/macrotrace/)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![CI](https://github.com/john-ramsey/macrotrace/actions/workflows/ci.yml/badge.svg)](https://github.com/john-ramsey/macrotrace/actions/workflows/ci.yml)
[![Docs](https://github.com/john-ramsey/macrotrace/actions/workflows/docs.yml/badge.svg)](https://john-ramsey.github.io/macrotrace/)

MacroTrace is a Python library for collecting, storing, and analyzing macroeconomic
time-series vintages. It is designed for research workflows where the revision
history matters just as much as the latest published value.

**Documentation:** <https://john-ramsey.github.io/macrotrace/>

Instead of treating a series as a single final dataset, MacroTrace helps you work
with the sequence of releases that were available in real time. This makes it
easier to study data revisions, reproduce historical analyses, and compare what was
known at different publication dates.

## Features

- Fetch vintage-aware macroeconomic time series from FRED and ONS
- Store releases locally in SQLite for reproducible, offline-friendly workflows
- Retrieve series as they were known on a specific date with `as_of(...)`
- Filter both vintage windows and data windows when loading a series
- Export to pandas DataFrames and Darts `TimeSeries` objects
- Plot vintages and revision comparisons with built-in Plotly tooling

## Installation

Install the package from PyPI:

```bash
pip install macrotrace
```

Install the optional ONS Textual interface:

```bash
pip install "macrotrace[ons-tui]"
```

## Requirements

- Python 3.11+
- A FRED API key for FRED-backed series

Set your FRED API key before loading FRED series:

```bash
export FRED_API_KEY="your_api_key_here"
```

## Quick Start

```python
from macrotrace import MTTimeSeries

payems = MTTimeSeries(
    dataset_id="PAYEMS",
    source="FRED",
)

print(payems)

july_2020 = payems.as_of("2020-07-15")
df = july_2020.to_dataframe()
```

MacroTrace stores fetched releases in a local SQLite database named
`MacroTrace.db`, making repeated loads faster and keeping vintage histories
available for later analysis.

For multi-dimensional datasets such as ONS releases, provide a `series_key` to
select a specific slice of the dataset:

```python
from macrotrace import MTTimeSeries

gdp = MTTimeSeries(
    dataset_id="gdp-to-four-decimal-places",
    source="ONS",
    series_key={
        "geography": "K02000001",
        "unofficialstandardindustrialclassification": "A--T",
    },
)
```

## Command-Line Tools

MacroTrace includes command-line tools for exploring ONS datasets:

```bash
macrotrace ons explorer
```

If you installed the optional TUI extra, you can also run:

```bash
macrotrace ons tui
```

## Development

For local development, we use `uv` for dependency management and environment
execution.

Install the project with the development, docs, and optional TUI dependencies:

```bash
uv sync --extra ons-tui --group dev --group docs
```

Run tests inside the managed environment with:

```bash
uv run pytest
```

Code formatting is handled with `black`:

```bash
uv run black .
```

## Project Status

MacroTrace is under active development as part of a PhD research project on
macroeconomic data revisions.

## License

MacroTrace is licensed under the GNU General Public License v3.0 or later
(`GPL-3.0-or-later`).
