panelcast 0.14.0__py3-none-any.whl

panelcast/__init__.py

@@ -0,0 +1,73 @@
+"""panelcast — hierarchical Bayesian prediction for bounded scores of events
+nested in entities over time, configured by a YAML descriptor.
+
+The names re-exported here are the supported public API and follow semantic
+versioning from the next minor release; see ``docs/API.md`` for the guarantee.
+Everything reached through ``panelcast.*`` submodules is internal and may change
+without notice. Attribute access is lazy (PEP 562), so ``import panelcast`` stays
+cheap and does not eagerly import jax.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+try:
+    __version__ = version("panelcast")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+# Each public name mapped to the submodule it is lazily imported from. Keep this
+# minimal — every entry is a semver promise (see docs/API.md), and importing a
+# submodule here would defeat the point of the lazy seam.
+_LAZY_EXPORTS = {
+    "DatasetDescriptor": "panelcast.config.descriptor",
+    "load_descriptor": "panelcast.config.descriptor",
+    "PipelineConfig": "panelcast.pipelines.orchestrator",
+    "PipelineOrchestrator": "panelcast.pipelines.orchestrator",
+    "run_pipeline": "panelcast.pipelines.orchestrator",
+    "FeatureRegistry": "panelcast.features",
+    "FeatureBlock": "panelcast.features.base",
+    "build_default_registry": "panelcast.features",
+    "LikelihoodSpec": "panelcast.models.bayes.likelihoods",
+}
+
+if TYPE_CHECKING:  # let type checkers resolve the names without importing jax
+    from panelcast.config.descriptor import DatasetDescriptor, load_descriptor
+    from panelcast.features import FeatureRegistry, build_default_registry
+    from panelcast.features.base import FeatureBlock
+    from panelcast.models.bayes.likelihoods import LikelihoodSpec
+    from panelcast.pipelines.orchestrator import (
+        PipelineConfig,
+        PipelineOrchestrator,
+        run_pipeline,
+    )
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY_EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    return getattr(import_module(module), name)
+
+
+def __dir__() -> list[str]:
+    # Keep the default module surface (dunders, __all__, eager imports,
+    # submodules) discoverable alongside the lazily exported public names.
+    return sorted({*globals(), *_LAZY_EXPORTS})
+
+
+__all__ = [
+    "__version__",
+    "DatasetDescriptor",
+    "load_descriptor",
+    "PipelineConfig",
+    "PipelineOrchestrator",
+    "run_pipeline",
+    "FeatureRegistry",
+    "FeatureBlock",
+    "build_default_registry",
+    "LikelihoodSpec",
+]

panelcast/_data/datasets/aero.yaml

@@ -0,0 +1,82 @@
+# Aerospace worked example — a self-contained, non-music domain.
+#
+# Airframes fly sequential test flights, each scored 0-10. Identical copies of
+# this descriptor ship in the checkout and wheel; the raw path is anchored at
+# the checkout or package-data root so `panelcast demo` runs with no external
+# data.
+#
+# Every key omitted here keeps its AOTY default — see
+# src/panelcast/config/descriptor.py. Walkthrough: docs/PORTING.md.
+
+name: aero
+
+# --- raw source ----------------------------------------------------------
+raw_path_env: AERO_DATASET_PATH
+raw_path_default: examples/aerospace/flights.csv
+encoding: utf-8
+raw_column_map:
+  "Flight Date": Flight_Date
+  "Perf Score": Perf_Score
+  "Sensor Samples": Sensor_Samples
+  "Test Crew": Test_Crew
+  "Flight ID": Flight_ID
+  "Campaign Year": Year
+  "Thrust Margin": Thrust_Margin
+  "Payload Fraction": Payload_Fraction
+required_raw_columns:
+  - Airframe
+  - "Flight ID"
+  - "Campaign Year"
+  - "Flight Date"
+  - "Perf Score"
+  - "Sensor Samples"
+  - "Test Crew"
+  - "Thrust Margin"
+  - "Payload Fraction"
+optional_raw_columns: []
+
+# --- identity / sequencing ------------------------------------------------
+entity_col: Airframe
+event_col: Flight_ID
+# No per-event group column in this domain — the entity_group_pooling gate is
+# structurally unusable (inheriting AOTY's primary_genre would misdescribe it).
+entity_group_col: null
+date_col: Flight_Date
+parsed_date_col: Flight_Date_Parsed
+year_col: Year
+date_format: "%Y-%m-%d"   # ISO, unlike AOTY's "April 10, 2018"
+
+# --- targets ----------------------------------------------------------------
+target_col: Perf_Score
+target_bounds: [0.0, 10.0]
+model_prefix: perf
+n_obs_col: Sensor_Samples
+# Sensor samples count telemetry points, not independent raters whose mean is the
+# score, so the beta_binomial likelihood is not meaningful here.
+n_obs_is_aggregation_count: false
+secondary_target_col: null
+secondary_prefix: null
+secondary_n_obs_col: null
+
+# --- cleaning semantics ----------------------------------------------------
+multi_entity_col: Test_Crew
+multi_entity_separator: " + "
+unknown_entity_sentinel: null
+min_year: 2015
+
+# --- dataset preparation -----------------------------------------------------
+min_obs_thresholds: [5, 10, 25]
+primary_min_obs: 5
+processed_name_template: "perf_minobs_{min_ratings}"
+
+# --- features -----------------------------------------------------------------
+feature_packs: []
+feature_blocks:
+  - name: temporal
+  - name: entity_history
+  - name: core_numeric
+    params:
+      columns: [Thrust_Margin, Payload_Fraction]
+ablation_groups:
+  temporal: [temporal]
+  artist: [entity_history]

panelcast/_data/datasets/aoty_full.yaml

@@ -0,0 +1,37 @@
+# AOTY dataset descriptor.
+#
+# Every DatasetDescriptor field defaults to the AOTY literal it replaced, so
+# this file only needs to (re)state the name: `--dataset aoty_full` must be
+# byte-identical to running with no --dataset flag at all (verified by
+# tests/e2e/test_domain_portability.py).
+#
+# Full field reference: src/panelcast/config/descriptor.py.
+# Worked non-music example: configs/datasets/aero.yaml + docs/PORTING.md.
+#
+# Operational note: processed data, splits, features and models all live under
+# relative paths (data/, models/, outputs/) — run each domain from its own
+# working directory to keep artifacts isolated. A --data-root option is a
+# post-publication stretch item.
+
+name: aoty
+
+# Commented examples of the AOTY defaults this file inherits (do not uncomment
+# unless you mean to override):
+#
+# raw_path_env: AOTY_DATASET_PATH
+# raw_path_default: data/raw/all_albums_full.csv
+# encoding: utf-8-sig
+# entity_col: Artist
+# event_col: Album
+# target_col: User_Score
+# target_bounds: [0.0, 100.0]
+# model_prefix: user
+# n_obs_col: User_Ratings
+# secondary_target_col: Critic_Score
+# secondary_prefix: critic
+# secondary_n_obs_col: Critic_Reviews
+# date_format: "%B %d, %Y"
+# min_obs_thresholds: [5, 10, 25]
+# primary_min_obs: 10
+# processed_name_template: "user_score_minratings_{min_ratings}"
+# feature_packs: [aoty]

panelcast/_data/examples/aerospace/descriptor.yaml

@@ -0,0 +1,82 @@
+# Aerospace worked example — a self-contained, non-music domain.
+#
+# Airframes fly sequential test flights, each scored 0-10. Identical copies of
+# this descriptor ship in the checkout and wheel; the raw path is anchored at
+# the checkout or package-data root so `panelcast demo` runs with no external
+# data.
+#
+# Every key omitted here keeps its AOTY default — see
+# src/panelcast/config/descriptor.py. Walkthrough: docs/PORTING.md.
+
+name: aero
+
+# --- raw source ----------------------------------------------------------
+raw_path_env: AERO_DATASET_PATH
+raw_path_default: examples/aerospace/flights.csv
+encoding: utf-8
+raw_column_map:
+  "Flight Date": Flight_Date
+  "Perf Score": Perf_Score
+  "Sensor Samples": Sensor_Samples
+  "Test Crew": Test_Crew
+  "Flight ID": Flight_ID
+  "Campaign Year": Year
+  "Thrust Margin": Thrust_Margin
+  "Payload Fraction": Payload_Fraction
+required_raw_columns:
+  - Airframe
+  - "Flight ID"
+  - "Campaign Year"
+  - "Flight Date"
+  - "Perf Score"
+  - "Sensor Samples"
+  - "Test Crew"
+  - "Thrust Margin"
+  - "Payload Fraction"
+optional_raw_columns: []
+
+# --- identity / sequencing ------------------------------------------------
+entity_col: Airframe
+event_col: Flight_ID
+# No per-event group column in this domain — the entity_group_pooling gate is
+# structurally unusable (inheriting AOTY's primary_genre would misdescribe it).
+entity_group_col: null
+date_col: Flight_Date
+parsed_date_col: Flight_Date_Parsed
+year_col: Year
+date_format: "%Y-%m-%d"   # ISO, unlike AOTY's "April 10, 2018"
+
+# --- targets ----------------------------------------------------------------
+target_col: Perf_Score
+target_bounds: [0.0, 10.0]
+model_prefix: perf
+n_obs_col: Sensor_Samples
+# Sensor samples count telemetry points, not independent raters whose mean is the
+# score, so the beta_binomial likelihood is not meaningful here.
+n_obs_is_aggregation_count: false
+secondary_target_col: null
+secondary_prefix: null
+secondary_n_obs_col: null
+
+# --- cleaning semantics ----------------------------------------------------
+multi_entity_col: Test_Crew
+multi_entity_separator: " + "
+unknown_entity_sentinel: null
+min_year: 2015
+
+# --- dataset preparation -----------------------------------------------------
+min_obs_thresholds: [5, 10, 25]
+primary_min_obs: 5
+processed_name_template: "perf_minobs_{min_ratings}"
+
+# --- features -----------------------------------------------------------------
+feature_packs: []
+feature_blocks:
+  - name: temporal
+  - name: entity_history
+  - name: core_numeric
+    params:
+      columns: [Thrust_Margin, Payload_Fraction]
+ablation_groups:
+  temporal: [temporal]
+  artist: [entity_history]

panelcast/_data/examples/aerospace/flights.csv

@@ -0,0 +1,40 @@
+Airframe,Flight ID,Flight Date,Campaign Year,Perf Score,Sensor Samples,Test Crew,Thrust Margin,Payload Fraction
+Falcon-X1,Falcon-X1-F01,2021-04-16,2021,4.42,116,Falcon-X1 + Chase-3,-1.951,0.883
+Falcon-X1,Falcon-X1-F02,2021-05-10,2021,5.05,102,Falcon-X1 + Chase-2,0.879,0.849
+Falcon-X1,Falcon-X1-F03,2021-05-30,2021,4.27,156,Falcon-X1 + Chase-2,-0.959,0.779
+Falcon-X1,Falcon-X1-F04,2021-07-15,2021,4.72,113,Falcon-X1,-0.155,0.745
+Condor-7,Condor-7-F01,2021-04-28,2021,6.54,176,Condor-7,-0.406,0.428
+Condor-7,Condor-7-F02,2021-05-09,2021,7.0,42,Condor-7,-0.84,0.359
+Condor-7,Condor-7-F03,2021-07-20,2021,6.74,198,Condor-7,0.543,0.783
+Condor-7,Condor-7-F04,2021-07-08,2021,7.02,148,Condor-7 + Chase-3,0.224,0.34
+Raptor-M2,Raptor-M2-F01,2021-04-20,2021,5.24,128,Raptor-M2,-0.275,0.28
+Raptor-M2,Raptor-M2-F02,2021-04-30,2021,5.43,170,Raptor-M2,0.163,0.588
+Raptor-M2,Raptor-M2-F03,2021-06-11,2021,4.81,100,Raptor-M2,0.858,0.486
+Raptor-M2,Raptor-M2-F04,2021-08-30,2021,4.62,219,Raptor-M2 + Chase-1,0.142,0.663
+Raptor-M2,Raptor-M2-F05,2021-09-15,2021,4.83,171,Raptor-M2,0.457,0.317
+Albatross-3,Albatross-3-F01,2021-04-13,2021,6.81,58,Albatross-3,0.481,0.687
+Albatross-3,Albatross-3-F02,2021-05-13,2021,5.55,200,Albatross-3 + Chase-2,-1.687,0.261
+Albatross-3,Albatross-3-F03,2021-06-21,2021,6.81,64,Albatross-3,1.299,0.745
+Albatross-3,Albatross-3-F04,2021-06-12,2021,5.39,28,Albatross-3,-0.339,0.519
+Albatross-3,Albatross-3-F05,2021-09-01,2021,5.49,45,Albatross-3,-1.446,0.731
+Albatross-3,Albatross-3-F06,2021-08-05,2021,6.38,131,Albatross-3,-0.239,0.259
+Kestrel-V,Kestrel-V-F01,2021-04-05,2021,6.29,29,Kestrel-V,-1.189,0.319
+Kestrel-V,Kestrel-V-F02,2021-05-09,2021,5.92,21,Kestrel-V + Chase-2,-0.222,0.871
+Kestrel-V,Kestrel-V-F03,2021-05-05,2021,7.38,179,Kestrel-V,2.914,0.856
+Kestrel-V,Kestrel-V-F04,2021-06-12,2021,6.69,197,Kestrel-V + Chase-1,-0.415,0.507
+Harrier-9,Harrier-9-F01,2021-03-04,2021,4.48,150,Harrier-9,-0.054,0.709
+Harrier-9,Harrier-9-F02,2021-04-25,2021,4.94,105,Harrier-9 + Chase-1,-0.965,0.588
+Harrier-9,Harrier-9-F03,2021-05-27,2021,4.46,218,Harrier-9,0.932,0.404
+Harrier-9,Harrier-9-F04,2021-07-18,2021,3.66,166,Harrier-9 + Chase-1,-0.455,0.505
+Harrier-9,Harrier-9-F05,2021-06-01,2021,4.56,197,Harrier-9,0.286,0.421
+Harrier-9,Harrier-9-F06,2021-10-06,2021,4.65,28,Harrier-9,1.536,0.384
+Osprey-T4,Osprey-T4-F01,2021-03-05,2021,8.52,46,Osprey-T4,1.461,0.812
+Osprey-T4,Osprey-T4-F02,2021-03-23,2021,8.07,214,Osprey-T4,-0.005,0.301
+Osprey-T4,Osprey-T4-F03,2021-03-27,2021,6.88,151,Osprey-T4,-2.05,0.554
+Osprey-T4,Osprey-T4-F04,2021-07-09,2021,7.82,178,Osprey-T4,0.916,0.717
+Swift-E2,Swift-E2-F01,2021-05-01,2021,5.35,113,Swift-E2 + Chase-2,0.538,0.869
+Swift-E2,Swift-E2-F02,2021-05-18,2021,5.7,9,Swift-E2,0.177,0.274
+Swift-E2,Swift-E2-F03,2021-08-18,2021,4.99,11,Swift-E2 + Chase-3,-0.853,0.763
+Swift-E2,Swift-E2-F04,2021-07-25,2021,6.07,183,Swift-E2,-0.654,0.363
+Swift-E2,Swift-E2-F05,2021-07-27,2021,5.69,87,Swift-E2,1.124,0.656
+Swift-E2,Swift-E2-F06,2021-09-11,2021,7.36,58,Swift-E2,-1.097,0.772

panelcast/cli/__init__.py

@@ -0,0 +1,51 @@
+"""Command-line interface for the panelcast prediction pipeline.
+
+This module provides CLI entry points for running the full pipeline or
+individual stages. The primary entry point is `panelcast run`, which
+executes all stages in dependency order with progress tracking.
+
+Usage:
+    panelcast run --seed 42
+    panelcast run --dry-run --verbose
+    panelcast stage data --verbose
+"""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    add_completion=True,
+    help="panelcast - hierarchical Bayesian prediction for bounded scores over entity histories.",
+    invoke_without_command=True,
+)
+
+# Stage subcommand group
+stage_app = typer.Typer(help="Run individual pipeline stages")
+app.add_typer(stage_app, name="stage")
+
+# Runs subcommand group
+runs_app = typer.Typer(help="Inspect pipeline run directories")
+app.add_typer(runs_app, name="runs")
+
+# Import the command submodules for their decorator side effects: importing each
+# one runs the @app.command / @stage_app.command decorators that register the
+# subcommands onto the shared app / stage_app created above. Order matches the
+# original definition order so ``--help`` lists the commands unchanged.
+# isort: off
+from panelcast.cli import main as _main  # noqa: E402
+from panelcast.cli import run as _run  # noqa: E402, F401
+from panelcast.cli import stages as _stages  # noqa: E402, F401
+from panelcast.cli import commands as _commands  # noqa: E402, F401
+from panelcast.cli import runs_cmd as _runs_cmd  # noqa: E402, F401
+from panelcast.cli import doctor_cmd as _doctor_cmd  # noqa: E402, F401
+from panelcast.cli import preflight_cmd as _preflight_cmd  # noqa: E402, F401
+from panelcast.cli import select_cmd as _select_cmd  # noqa: E402, F401
+from panelcast.cli import stack_cmd as _stack_cmd  # noqa: E402, F401
+from panelcast.cli import backtest_cmd as _backtest_cmd  # noqa: E402, F401
+# isort: on
+
+__version__ = _main.__version__
+main = _main.main
+
+__all__ = ["__version__", "app", "main", "runs_app", "stage_app"]

panelcast/cli/backtest_cmd.py

@@ -0,0 +1,94 @@
+"""The `panelcast backtest` command (#179).
+
+Rolling-origin backtest: runs the full leakage-safe stage chain once per
+origin and reports every headline metric as mean ± SE across origins. A
+killed backtest resumes at the next unfinished origin via the JSON ledger.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from panelcast.cli import app
+
+
+@app.command("backtest")
+def backtest(
+    origins: int = typer.Option(
+        3,
+        "--origins",
+        min=1,
+        help="Number of rolling origins K: origin k holds out each entity's (last-k)-th event.",
+    ),
+    backtest_id: str = typer.Option(
+        "default",
+        "--backtest-id",
+        help="Ledger/report directory name under outputs/backtest/ (reuse to resume).",
+    ),
+    dataset: str | None = typer.Option(
+        None,
+        "--dataset",
+        help="Dataset descriptor (bare name or YAML path; omit for AOTY defaults).",
+    ),
+    num_chains: int | None = typer.Option(
+        None, "--num-chains", min=1, help="Chains per origin fit (default: pipeline default)."
+    ),
+    num_samples: int | None = typer.Option(
+        None, "--num-samples", min=1, help="Draws per origin fit (default: pipeline default)."
+    ),
+    num_warmup: int | None = typer.Option(
+        None, "--num-warmup", min=1, help="Warmup per origin fit (default: pipeline default)."
+    ),
+    origin_timeout: float | None = typer.Option(
+        None,
+        "--origin-timeout",
+        min=1.0,
+        help="Per-origin wall-clock timeout in seconds (default: none).",
+    ),
+    output_root: str = typer.Option(
+        "outputs/backtest", "--output-root", help="Root directory for backtest ledgers/reports."
+    ),
+) -> None:
+    """Run (or resume) a rolling-origin backtest and print the aggregate table.
+
+    Each origin regenerates splits/features with fresh stamps, so the leakage
+    controls hold unchanged; every origin's split content hash is recorded in
+    the ledger. Deeper origins shrink the eligible entity set — the aggregate
+    table reports n_test and n_entities per origin so cross-origin variation
+    is framed honestly.
+
+    Examples:
+        panelcast backtest --origins 3
+        panelcast backtest --origins 5 --num-chains 2 --num-samples 500
+        panelcast backtest --backtest-id nightly  # rerun to resume
+    """
+    from panelcast.pipelines.backtest import BacktestConfig, run_backtest
+
+    cfg = BacktestConfig(
+        origins=origins,
+        backtest_id=backtest_id,
+        output_root=Path(output_root),
+        dataset=dataset,
+        num_chains=num_chains,
+        num_samples=num_samples,
+        num_warmup=num_warmup,
+        origin_timeout_seconds=origin_timeout,
+    )
+    aggregate = run_backtest(cfg)
+
+    typer.echo(
+        f"\nBacktest '{backtest_id}': {aggregate['n_origins_completed']}"
+        f"/{aggregate['n_origins_requested']} origins completed."
+    )
+    for name, block in aggregate["metrics"].items():
+        if block is None:
+            continue
+        se = f" ± {block['se']:.4f}" if block["se"] is not None else ""
+        typer.echo(f"  {name}: {block['mean']:.4f}{se}  [{block['min']:.4f}, {block['max']:.4f}]")
+    typer.echo(f"\n  wrote {cfg.backtest_dir / 'backtest_metrics.json'}")
+    typer.echo(f"  wrote {cfg.backtest_dir / 'backtest_report.md'}")
+    if aggregate["n_origins_completed"] < aggregate["n_origins_requested"]:
+        typer.echo("  incomplete origins remain — rerun the same command to resume.")
+        raise typer.Exit(code=1)