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.

Obfuscated builds (PyArmor)

To ship bytecode‑only builds, generate an obfuscated copy with the helper script:

pip install pyarmor build
python scripts/pyarmor_obfuscate.py --output dist/pyarmor
cd dist/pyarmor && python -m build --wheel --no-isolation

The script copies project metadata, bundles the PyArmor runtime alongside the obfuscated modules, and stamps the wheel version with a +pyarmor suffix so you can differentiate obfuscated artifacts from source distributions.

Debugging and expectations. PyArmor replaces Python source with obfuscated bytecode; the resulting wheel still runs normally but stack traces and line numbers point at the obfuscated copy. Regular debugging tools (e.g., logging, exceptions) remain available to you, but they become less useful for someone trying to read the code. Obfuscation is a deterrent—not a hard barrier—so highly motivated reverse engineers can still recover behavior with enough effort.

Stronger hardening options. If you need a higher bar than bytecode obfuscation, consider compiling the most sensitive modules to native extensions (Cython or Nuitka) or wrapping them behind a service boundary. You can also tighten PyArmor settings (e.g., restricted mode, runtime license checks, or binding to specific machines) when invoking the CLI directly.

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.

New data acquisition helpers

LA refinery activity scraper (Playwright)

Use the new fetch_la_refinery_data helper to download Louisiana SONRIS refinery activity reports without touching the browser UI yourself. The scraper installs Playwright-managed browsers when needed, retries common selectors, and waits for Oracle APEX processing overlays automatically.

import asyncio
from analysis3054.la_refinery import fetch_la_refinery_data

# Pull all available data since 2018; pass a later start_date to scope the report
df = asyncio.run(fetch_la_refinery_data(start_date="01-JAN-2018"))
print(df.head())

Tips: Ensure the environment can run headless Chromium/WebKit. Downloads are isolated in a temporary directory per invocation, so the helper is safe to call from concurrent tasks.

Refined Fuels USMD API client

RefinedFuelsUSMDClient wraps the DTN Refined Fuels USMD API with automatic pagination into DataFrames. Authenticate with either an API key or a bearer token obtained via request_access_token.

from analysis3054.refined_fuels_api import (
    RefinedFuelsUSMDClient,
    request_access_token,
)

token = request_access_token(client_id="<id>", client_secret="<secret>")
client = RefinedFuelsUSMDClient(access_token=token)

padd = client.fetch_padd_daily(regions="1,2,3", startDate="2024-01-01")
rack = client.fetch_rack_daily(states="TX,LA", products="GAS")

# Supplier + terminal monthly summaries support density filters via keywords
monthly = client.fetch_supplier_terminal_monthly(
    regions="3",
    supplierMinCount=2,
    terminalMinCount=2,
)

Paginated methods default to the maximum page size for efficiency and raise requests.HTTPError on non-200 responses, making failures visible in pipelines.

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.