Metadata-Version: 2.4
Name: analysis3054
Version: 0.3.0
Summary: Advanced time-series analytics and forecasting toolkit for commodity and power trading
Author-email: Hoff <you@example.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.24
Requires-Dist: plotly>=5.20
Requires-Dist: statsmodels>=0.13
Requires-Dist: scipy>=1.10
Requires-Dist: chronos-forecasting>=0.3.3
Requires-Dist: autogluon.timeseries>=1.1.1
Provides-Extra: stats
Requires-Dist: pmdarima>=2.0; extra == "stats"
Requires-Dist: arch>=6.0; extra == "stats"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.2; extra == "ml"
Requires-Dist: xgboost>=2.0; extra == "ml"
Requires-Dist: lightgbm>=4.0; extra == "ml"
Requires-Dist: catboost>=1.2; extra == "ml"
Provides-Extra: dl
Requires-Dist: tensorflow>=2.12; extra == "dl"
Provides-Extra: prophet
Requires-Dist: prophet>=1.1; extra == "prophet"
Requires-Dist: neuralprophet>=0.6.0; extra == "prophet"
Provides-Extra: tbats
Requires-Dist: tbats>=1.1.3; extra == "tbats"
Provides-Extra: plot
Requires-Dist: plotly>=5.20; extra == "plot"
Provides-Extra: all
Requires-Dist: analysis3054[dl,ml,plot,prophet,stats,tbats]; extra == "all"
Dynamic: license-file

# Analysis3054 – Advanced Forecasting & Analytics

Analysis3054 is a full‑featured time‑series analytics and forecasting package designed for commodity, energy, and demand‑planning practitioners. It combines plotting, statistics, machine learning, and deep learning (Chronos‑2, AutoGluon, gradient boosting, SARIMAX, and more) under a single, unified API.

## Installation
Install the latest release (Chronos‑2 and AutoGluon are installed by default):

```bash
pip install analysis3054
```

Optional extras let you control footprint per environment:

```bash
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)
```

### Building for PyPI
From a clean checkout:

```bash
python -m build
```

This produces wheel and sdist artifacts under `dist/` ready for upload via `twine upload dist/*`.

## Quickstart
Create a small demo DataFrame (weekly power prices with a covariate):

```python
import numpy as np
import pandas as pd
from analysis3054 import (
    five_year_plot,
    ForecastEngine,
    forecast_distillate_burn,
    ml_forecast,
    chronos2_forecast,
    bayesian_ridge_forecast,
    huber_forecast,
    pls_forecast,
    fourier_ridge_forecast,
    histgb_direct_forecast,
)

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),
})
```

## Plotting
### Five‑Year Band Plot
```python
fig = five_year_plot(date="date", df=df, smooth=True)
fig.show()
```

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

### High‑level helper: distillate burn
```python
res = forecast_distillate_burn(
    df=df,
    date_col="date",
    target_col="price",
    covariate_cols=["temp"],
    prediction_length=6,
    method="chronos2",
)
```

### Chronos‑2 direct use
```python
chronos_out = chronos2_forecast(
    df=df,
    date_col="date",
    target_col="price",
    covariate_cols=["temp"],
    prediction_length=12,
    model_name="amazon/chronos-2",
)
```

## ML & Robust Forecasters
All ML helpers infer frequency, propagate covariates, apply exponential error correction, and handle missing sklearn gracefully.

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

### Auto ML family (10+ helpers)
```python
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
```python
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.
