Advanced time-series analytics and forecasting toolkit for commodity and power trading

These details have not been verified by PyPI

Project description

Analysis3054 – Advanced Forecasting & Analytics

Analysis3054 is a full‑featured time‑series analytics and forecasting package designed for commodity, energy, and demand‑planning teams. It combines plotting, statistics, machine learning, deep learning (Chronos‑2), physics‑inspired forecasters, and high‑speed data ingestion under a single, unified API.

Installation

Analysis3054 ships prebuilt wheels for common platforms. A minimal install pulls Chronos‑2, physics forecasters, and AutoGluon backends by default.

pip install analysis3054

Optional extras let you control the footprint per environment:

pip install "analysis3054[stats]"    # pmdarima + arch
pip install "analysis3054[ml]"       # scikit-learn + boosted trees
pip install "analysis3054[dl]"       # tensorflow
pip install "analysis3054[prophet]"  # prophet + neuralprophet
pip install "analysis3054[tbats]"    # tbats
pip install "analysis3054[all]"      # everything (same as base but explicit)

For air‑gapped or offline environments, install from an internal index mirror and export the ANALYSIS3054_HOME environment variable to control cache locations for pretrained Chronos‑2 checkpoints.

What’s new in Chronos‑2

Chronos‑2 now delivers faster inference, richer covariate handling, and clearer diagnostics:

Adaptive covariate gating – detect and down‑weight noisy drivers automatically.
Scenario packets – emit multiple forecast paths per call for stress testing.
Quantile fan – calibrated 5–95% bands optimized for medium‑horizon energy curves.
Batch streaming – stream partial results back to dashboards before the full job completes.

Chronos‑2 quickstarts

Univariate baseline (minimal inputs)

from analysis3054 import chronos2_univariate_forecast

forecast = chronos2_univariate_forecast(
    df,                     # DataFrame with a datetime column and one numeric target
    date_col="date",
    target_col="price",
    prediction_length=14,
    quantiles=[0.05, 0.5, 0.95],
)
print(forecast.forecasts.tail())      # includes scenario packet IDs
print(forecast.diagnostics.summary)   # convergence + latency insights

Multivariate with automatic covariate gating

from analysis3054 import chronos2_multivariate_forecast

multi = chronos2_multivariate_forecast(
    df,
    date_col="date",
    target_cols=["north", "south", "west"],
    covariate_cols=["temp", "load_forecast"],
    prediction_length=21,
    gate_covariates=True,            # drop unhelpful drivers per series
    scenario_paths=5,                # request multiple stress paths
)
print(multi.forecasts.columns)       # (series, quantile, scenario)

Covariate‑informed future window

from analysis3054 import chronos2_covariate_forecast

# known drivers during the forecast horizon (weather + planned outages)
future_cov = pd.DataFrame({
    "date": pd.date_range(df["date"].max() + pd.Timedelta(days=1), periods=30, freq="D"),
    "temp": 65,
    "planned_outage": [0, 0, 1, 1, 0] * 6,
})

guided = chronos2_covariate_forecast(
    df,
    date_col="date",
    target_col="price",
    covariate_cols=["temp", "planned_outage"],
    future_cov_df=future_cov,
    prediction_length=30,
    quantiles=[0.1, 0.25, 0.5, 0.75, 0.9],
)
guided.plot_quantile_fan().show()

Physics forecasters

Physics‑inspired models capture conservation relationships and engineered dynamics that traditional ML misses. The helpers accept the same DataFrame shape used across the package, making them drop‑in replacements.

Mass‑balance forecaster

Ideal for refinery yield or inventory reconciliation problems.

from analysis3054 import mass_balance_forecast

forecast = mass_balance_forecast(
    df,
    date_col="date",
    inflow_cols=["crude_intake"],
    outflow_cols=["products"],
    storage_col="tank_level",
    prediction_length=14,
    enforce_conservation=True,
)
print(forecast.forecasts[["tank_level_mean"]].tail())

Thermal decay forecaster

Captures lagged response between ambient temperature and process temperature.

from analysis3054 import thermal_decay_forecast

thermal = thermal_decay_forecast(
    df,
    date_col="date",
    target_col="process_temp",
    ambient_col="ambient_temp",
    time_constant_hours=6,
    prediction_length=48,
)
thermal.forecasts.plot(title="Thermal response");

Hydro forecast with snowmelt dynamics

from analysis3054 import hydro_snowmelt_forecast

snowmelt = hydro_snowmelt_forecast(
    df,
    date_col="date",
    precip_col="precip_in",
    temp_col="temp_f",
    target_col="river_cfs",
    prediction_length=10,
    melt_threshold=32,
)
print(snowmelt.diagnostics.water_balance)

Lightning‑fast API ingestion

fetch_apis_to_dataframe pools HTTP/2 connections, batches retries, and streams partial frames so you can ingest many endpoints into one DataFrame without manual plumbing.

from analysis3054 import fetch_apis_to_dataframe

endpoints = [
    "https://api.example.com/v1/events",                 # simple URL
    {"url": "https://api.example.com/v1/users", "params": {"page": 1}},
    {"url": "https://api.example.com/v1/prices.ndjson", "format": "ndjson"},
]

df = fetch_apis_to_dataframe(
    endpoints,
    max_workers=24,                   # aggressive concurrency
    timeout="5s",                    # per‑request timeout with auto backoff
    sort_by=["timestamp", "region"],
    transform=lambda frame: frame.assign(
        value_pct=frame["value"] / frame["value"].sum()
    ),
    stream_results=True,             # yield partial frames for dashboards
    output_dir="./exports",          # optional CSV persistence
    file_name="daily_snapshot",
)
print(df.head())

Background ingestion for UI threads

future = fetch_apis_to_dataframe(
    endpoints,
    max_workers=12,
    run_in_background=True,          # returns a Future immediately
    throttle_after=0.5,              # adaptive throttle after 429s or timeouts
)

# do other work here ...
df_async = future.result()           # blocks only when results are needed

transform accepts both regular and async callables. When stream_results=True, each partial DataFrame is passed through the transform before being concatenated, ensuring your downstream math stays consistent while the ingestion speeds ahead.

Quickstart (forecasting)

Create a small demo DataFrame (weekly power prices with a covariate) and run a unified forecast.

import numpy as np
import pandas as pd
from analysis3054 import ForecastEngine

rng = pd.date_range("2020-01-05", periods=120, freq="W")
df = pd.DataFrame({
    "date": rng,
    "price": 50 + np.sin(np.arange(120) / 6) * 5 + np.random.randn(120),
    "temp": 30 + np.random.randn(120),
})

engine = ForecastEngine.default()
forecast = engine.run(
    df=df,
    date_col="date",
    target_cols=["price"],
    horizon=8,
    covariate_cols=["temp"],
)
print(forecast.forecasts.head())

Plotting

Five‑Year Band Plot

from analysis3054 import five_year_plot

fig = five_year_plot(date="date", df=df, smooth=True)
fig.show()

ML & Robust Forecasters

All ML helpers infer frequency, propagate covariates, apply exponential error correction, and handle missing scikit‑learn gracefully.

from analysis3054 import (
    bayesian_ridge_forecast,
    huber_forecast,
    pls_forecast,
    fourier_ridge_forecast,
    histgb_direct_forecast,
)

ridge = bayesian_ridge_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=10)
huber = huber_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=10)
pls = pls_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=10)
fourier = fourier_ridge_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=10, seasonal_periods=[52])
histgb = histgb_direct_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=10, max_depth=4)

Auto ML family (10+ helpers)

from analysis3054 import (
    chronos2_auto_covariate_forecast,
    boosted_tree_forecast,
    random_forest_forecast,
    elastic_net_forecast,
    xgboost_forecast,
    catboost_forecast,
    lightgbm_forecast,
    svr_forecast,
    mlp_forecast,
    harmonic_regression_forecast,
    intraday_sarimax_forecast,
)

auto = chronos2_auto_covariate_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=6)
boosted = boosted_tree_forecast(df, "date", "price", covariate_cols=["temp"], prediction_length=6)

Leaderboards & Ensembles

from analysis3054 import model_leaderboard, simple_ensemble

leaderboard = model_leaderboard(df, "date", "price", covariate_cols=["temp"], prediction_length=8, models=["chronos2", "sarimax", "harmonic"])
ensemble = simple_ensemble(df, "date", "price", covariate_cols=["temp"], prediction_length=8, models=["chronos2", "harmonic"], weights=[0.7, 0.3])

Additional Utilities

ml_forecast: AutoGluon multiseries forecaster with optional quantiles.
forecast_engine: Registry for plugging in custom model handlers.
forecast_distillate_burn: Sector‑specific helper with automatic Chronos‑2 routing.
statistics.py / stats.py: stationarity tests, autocorrelation utilities.
plot.py / visualization.py: distribution, correlation, and seasonal plots.
finance.py: Sharpe ratio, drawdown analytics, and return attribution.

Refer to USER_GUIDE.md for end‑to‑end walkthroughs, troubleshooting tips, and extended examples spanning every public function.

Extended Chronos-2 enhancement tour

Below are deeply annotated scenarios covering ingestion, covariates, diagnostics, and deployment patterns.