Metadata-Version: 2.4
Name: timegram
Version: 0.1.1a1
Summary: A generative grammar for time series forecasting and inference
License-Expression: GPL-3.0-or-later
Keywords: time-series,forecasting,simulation,grammar,statistical-software
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: torch
Requires-Dist: pandas
Requires-Dist: scipy
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Requires-Dist: networkx; extra == "plot"
Provides-Extra: data
Requires-Dist: fcompdata; extra == "data"
Dynamic: license-file

# timegram

**Alpha release, under active development. APIs may change; feedback and issue reports are welcome.**

A generative grammar for time series forecasting and inference.

Build models from sources, filters and combinators. Choose an estimation target and a
decision-theoretic objective, then train a reusable neural estimator on simulated data.
The same components also support simulation and inspection without training.

## Installation

From a source distribution or checkout:

```bash
python -m pip install .
```

Install this alpha release from PyPI:

```bash
python -m pip install timegram==0.1.1a1
```

Python 3.11 or later is required. Core dependencies are NumPy, pandas, SciPy and PyTorch.
Choose the PyTorch installation and execution device that fit your hardware. Both CPU and
GPU execution are supported; installing the package starts no training or model downloads.

Optional graph plotting (matplotlib and networkx): `python -m pip install "timegram[plot]==0.1.1a1"`.
Optional benchmark-data helpers: `python -m pip install "timegram[data]==0.1.1a1"`.

## Simulate and inspect

```python
import timegram as tg

world = tg.ets("AAA", period=12)
report = world.typecheck(history_length=128)
print(report.has_errors)

samples = world.simulate(n=3, length=128, seed=42, device="cpu")
print(samples.context.shape)
```

The simulator chooses parameters and initial states from the world's declared sampling
distributions. The static report describes supported checks with their scope and assumptions;
an unverified property is not established by the absence of a structural error.

## Change a model by composition

```python
spiky = tg.noise(tg.mixture(tg.normal(), tg.normal(0, 10), weights=[0.95, 0.05]))
world_spiky = spiky >> world
independent_ar = tg.noise(tg.student_t(3)) >> tg.ar(1)
world_combined = world_spiky + independent_ar
```

`>>` feeds a process into a filter. `+` adds generated paths; `convex` blends them;
`select` chooses an alternative once per generated series. Reusing a source object shares
its realized shocks; copying it creates a separate source.

## Specify an estimation task

```python
problem = (
    world_combined
    .estimate(tg.forecast(h=24, quantiles=[0.1, 0.5, 0.9]))
    .loss(tg.pinball())
    .objective(tg.risk())
)
```

To train or retrieve a compatible local estimator, call `problem.pretrain(...)`. Calling
the resulting estimator on a history returns an object whose `.forecast` contains the
forecast. Pretraining is an explicit computational step; its cost depends on the task,
architecture, backend and budget. Choose device and training settings for your workload.

Estimators are stored in `$TIMEGRAM_HOME`, defaulting to `~/.cache/timegram`. The distribution
includes no pretrained weights. The public API also provides model-definition graphs,
descriptive complexity, checked model moves and scoped parameter-ambiguity witnesses.

## License

GPL-3.0-or-later. See `LICENSE`.
