dependence-forecastability 0.3.1

Forecastability triage for time series using AMI, pAMI, and covariate-aware dependence diagnostics before expensive model search.

Forecastability Triage Toolkit

Forecastability triage for time series using AMI, pAMI, and covariate-aware dependence diagnostics before expensive model search.

Why this package

Forecastability triage for time series using AMI, pAMI, and covariate-aware dependence diagnostics before expensive model search.

Install

pip install dependence-forecastability

Optional runtime extras:

pip install "dependence-forecastability[transport]"
pip install "dependence-forecastability[agent]"

Quickstart

Run one deterministic univariate triage call through the top-level facade:

from forecastability import TriageRequest, generate_ar1, run_triage

series = generate_ar1(n_samples=300, phi=0.8, random_state=42)
result = run_triage(
    TriageRequest(
        series=series,
        goal="univariate",
        max_lag=20,
        n_surrogates=99,
        random_state=42,
    )
)

summary = {
    "blocked": result.blocked,
    "readiness_status": result.readiness.status.value,
    "compute_surrogates": None if result.method_plan is None else result.method_plan.compute_surrogates,
    "forecastability_class": None if result.interpretation is None else result.interpretation.forecastability_class,
    "primary_lags": [] if result.interpretation is None else list(result.interpretation.primary_lags),
}
print(summary)

Equivalent minimal files:

• examples/minimal_python.py
• examples/minimal_covariant.py
• examples/minimal_cli.sh

Start here

• Python user: start with examples/minimal_python.py, then docs/public_api.md.
• CLI user: run examples/minimal_cli.sh, then docs/quickstart.md.
• Notebook user: open the canonical notebook notebooks/walkthroughs/00_air_passengers_showcase.ipynb.
• Fingerprint user: run scripts/run_showcase_fingerprint.py, then open notebooks/walkthroughs/02_forecastability_fingerprint_showcase.ipynb.
• Maintainer/contributor: use docs/maintenance/developer_guide.md.

Canonical walkthrough

The canonical notebook is notebooks/walkthroughs/00_air_passengers_showcase.ipynb.

V0.3.1 fingerprint showcase

The v0.3.1 fingerprint surface is intentionally univariate-first and AMI-first. It packages AMI information geometry, the compact four-field fingerprint, deterministic family routing, and a strict agent-layer explanation that stays downstream of the deterministic outputs.

Run the canonical showcase:

MPLBACKEND=Agg uv run scripts/run_showcase_fingerprint.py --smoke

Minimal Python entry:

from forecastability import generate_fingerprint_archetypes, run_forecastability_fingerprint

series = generate_fingerprint_archetypes(n=320, seed=42)["seasonal_periodic"]
bundle = run_forecastability_fingerprint(
    series,
    target_name="seasonal_periodic",
    max_lag=24,
    n_surrogates=99,
    random_state=42,
)
print(bundle.recommendation.primary_families)

Batch CSV entry:

uv run python scripts/run_ami_information_geometry_csv.py \
  --input-csv outputs/examples/ami_geometry_csv/inputs/synthetic_fingerprint_panel.csv \
  --output-root outputs/ami_geometry_csv_script \
  --max-lag 24 \
  --n-surrogates 99 \
  --random-state 42

Primary fingerprint surfaces:

• Script: scripts/run_showcase_fingerprint.py
• Notebook: notebooks/walkthroughs/02_forecastability_fingerprint_showcase.ipynb
• Theory: docs/theory/forecastability_fingerprint.md
• Code reference: docs/code/fingerprint_showcase.md
• Agent contract: docs/agent_layer.md

When to use it

Use this package when you need a deterministic pre-modeling screen to decide whether a series has exploitable structure before expensive model search.

Links

• Notebook: notebooks/walkthroughs/00_air_passengers_showcase.ipynb
• Notebook (covariant informative): notebooks/walkthroughs/01_covariant_informative_showcase.ipynb
• Notebook (fingerprint showcase): notebooks/walkthroughs/02_forecastability_fingerprint_showcase.ipynb
• Quickstart: docs/quickstart.md
• PyPI: dependence-forecastability
• Issues: GitHub Issues

[!NOTE] run_covariant_analysis() supports six methods: cross_ami, cross_pami, te, gcmi, pcmci, and pcmci_ami. The two PCMCI methods are optional and skip gracefully when the causal extra is unavailable.

Install optional causal dependencies only if you need PCMCI methods:

pip install "dependence-forecastability[causal]"

Transport and runtime entry points:

Surface	Entry point	Stability
Python facade	forecastability, forecastability.triage	Stable
CLI	forecastability	Beta
HTTP API	forecastability.adapters.api:app	Beta
Dashboard	forecastability-dashboard	Beta
MCP server	adapter surface	Experimental
Agent narration	adapter surface	Experimental

Repository Workflow

If you are working in the repository rather than installing the package, start here:

uv sync

Canonical maintainer scripts:

Script	Role
scripts/run_canonical_triage.py	Canonical single-series workflow
scripts/run_benchmark_panel.py	Benchmark-panel workflow
scripts/build_report_artifacts.py	Report artifact builder

Secondary utilities:

• scripts/download_data.py
• scripts/run_exog_analysis.py
• scripts/check_notebook_contract.py
• scripts/rebuild_benchmark_fixture_artifacts.py
• scripts/rebuild_diagnostic_regression_fixtures.py

Current config status:

Config	Current role
configs/benchmark_panel.yaml	Active benchmark-panel configuration
configs/canonical_examples.yaml	Descriptive reference for canonical examples, not the root runner's only source of truth
configs/interpretation_rules.yaml	Reference thresholds for interpretation policy
configs/benchmark_exog_panel.yaml	Secondary exogenous benchmark workflow
configs/exogenous_screening_workbench.yaml	Secondary workbench configuration
configs/robustness_study.yaml	Secondary robustness-study workflow

Notebook Path And Artifact Surfaces

Canonical notebook:

• notebooks/walkthroughs/00_air_passengers_showcase.ipynb

Follow-on notebooks:

• notebooks/walkthroughs/01 through 04
• notebooks/triage/01 through 06 for deep dives

Main checked-in artifact surfaces:

• outputs/json/canonical_examples_summary.json and related canonical JSON outputs
• outputs/tables/*.csv
• outputs/reports/*.md

[!NOTE] Checked-in artifacts are reference outputs. They are useful examples of the output surface, but they should not be treated as guaranteed-fresh build products for the current working tree.

Statistical Notes

• AMI is computed per horizon rather than aggregated before computation.
• pAMI is a project extension and a linear-residual approximation, not exact conditional mutual information.
• Surrogate significance uses phase-randomized FFT surrogates with at least 99 surrogates and two-sided 95% bands.
• “Significance skipped” and “no significant lags” are different outcomes. Use compute_surrogates or the route choice to tell them apart.
• In rolling-origin workflows, diagnostics are computed on the training window only.
• Phase surrogates can be conservative for strongly periodic series.

Documentation Map

Need	Start here
Documentation index by role	docs/README.md
Stable imports and runtime entry points	docs/public_api.md
Live module layout	docs/code/module_map.md
HTTP API contract	docs/api_contract.md
Notebook path	docs/notebooks/README.md
Contributor workflow	docs/maintenance/developer_guide.md

For the repository-wide docs map, see docs/README.md.