Metadata-Version: 2.4
Name: analysis3054
Version: 2.1.0
Summary: Advanced time-series analysis, plotting and forecasting utilities
Author: AH
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3
Requires-Dist: numpy>=1.21
Requires-Dist: plotly>=5.0
Requires-Dist: scikit-learn>=1.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: scipy>=1.7
Requires-Dist: statsmodels>=0.13
Requires-Dist: PyWavelets>=1.4
Requires-Dist: arch>=5.0
Provides-Extra: ml
Requires-Dist: autogluon.timeseries>=1.0; extra == "ml"
Provides-Extra: xgboost
Requires-Dist: xgboost>=1.5; extra == "xgboost"
Provides-Extra: dl
Requires-Dist: torch>=2.0; extra == "dl"
Requires-Dist: transformers>=4.30; extra == "dl"
Requires-Dist: accelerate>=0.20; extra == "dl"
Provides-Extra: prophet
Requires-Dist: prophet>=1.1; extra == "prophet"

# EIA Band Plot & Time Series Forecasting

This package provides comprehensive tools for time series analysis, visualization, and PhD-level forecasting.

## Key Features

### 1. Interactive Visualization
*   **`five_year_plot`**: Generates EIA-style 5-year band plots to visualize historical ranges.
*   **`plot_yearly_comparison_interactive`**: Interactive Plotly chart comparing years (Current=Red, Last=Blue, Next/Forecast=Yellow).
*   **`plot_fan_chart_interactive`**: Interactive fan chart for probabilistic forecasts.

### 2. Robust Forecasting
We provide a suite of robust forecasting functions that handle cleaning, covariates, and uncertainty quantification automatically.

*   **`forecast_chronos`**: Uses Amazon's **Chronos-2** Foundation Model (T5-based) for state-of-the-art zero-shot forecasting.
*   **`forecast_lstm_probabilistic`**: Probabilistic Deep Learning model (PyTorch) predicting confidence intervals.
*   **`forecast_stl_decomposition`**: Decomposes series into Trend/Season/Residuals for structural forecasting.
*   **`forecast_var_multivariate`**: Vector Autoregression for interdependent multiple time series.
*   **`forecast_prophet_robust`**: Wrapper for Facebook Prophet with auto-cleaning.
*   **`forecast_ensemble`**: Combine multiple models (weighted/mean) for robust consensus.
*   **`generate_scenarios_bootstrap`**: Generate Monte Carlo paths via block bootstrapping.
*   **Machine Learning Models**:
    *   `forecast_random_forest`
    *   `forecast_xgboost`
    *   `forecast_svm`
    *   `forecast_elastic_net`
    *   `forecast_sarimax`

### 3. Advanced Analysis
*   **`analyze_granger_causality`**: Tests if one time series is useful in forecasting another (pairwise matrix).
*   **`detect_structural_breaks`**: Identifies regime changes in the time series mean/variance.
*   **`analyze_cross_correlation`**: Plots lag correlations to find leading indicators.
*   **`detect_anomalies_isolation_forest`**: Unsupervised anomaly detection.
*   **`fit_garch_volatility`**: Estimate conditional volatility (GARCH).
*   **`analyze_dynamic_time_warping`**: Measure similarity and alignment between two series.
*   **`analyze_intervention_impact`**: Causal Impact analysis of events (counterfactuals).
*   **`detect_regime_switching_markov`**: Identify market regimes (e.g., High/Low Vol) using Markov Switching models.

### 4. Signal Processing & Statistics
*   **`decompose_singular_spectrum`**: SSA decomposition (Trend/Oscillation/Noise).
*   **`generate_surrogate_data`**: Generate IAAFT surrogates for hypothesis testing.
*   **`analyze_wavelet_spectrum`**: Time-Frequency analysis (Continuous Wavelet Transform).
*   **`test_diebold_mariano`**: Statistically compare forecast accuracy.
*   **`calculate_rolling_hurst_exponent`**: Measure long-term memory/fractal dimension.
*   **`calculate_rolling_permutation_entropy`**: Measure complexity/randomness.
*   **`test_stationarity_comprehensive`**: Robust stationarity test (ADF+KPSS).

### 5. Commodity Trading Toolkit
*   **`analyze_spread_cointegration`**: Pair trading analysis (Hedge Ratio, Z-Score, ADF).
*   **`plot_volatility_cones`**: Realized volatility cones (Min/Max/Median/Current) for option pricing context.
*   **`plot_seasonal_heatmap`**: Month vs Year heatmap for seasonality detection.
*   **`analyze_term_structure`**: Contango/Backwardation analysis and roll yield proxy.

### 6. Financial Metrics
*   **`calculate_tail_risk_metrics`**: VaR, CVaR, Max Drawdown.
*   **`liquidity_adjusted_volatility`**, **`rolling_beta`**.

### 7. Diagnostics & Clustering
*   **`plot_residual_diagnostics`**: 4-panel check (Residuals, Hist, ACF, QQ).
*   **`backtest_rolling_window`**: Robust walk-forward validation.
*   **`cluster_time_series`**: Cluster multiple series using features or raw shape (K-Means).

### 8. The Unified API (`TimeSeriesLab`)
A fluent interface wrapping all functionality.

---

## Installation

```bash
pip install analysis3054
```

To use Chronos and Deep Learning features:
```bash
pip install analysis3054[ml] torch transformers accelerate
# For Chronos specifically
pip install git+https://github.com/amazon-science/chronos-forecasting.git
```

To use Prophet:
```bash
pip install prophet
```

To use GARCH models:
```bash
pip install arch
```

To use Wavelets:
```bash
pip install PyWavelets
```

---

## User Guide: Commodity Trading Toolkit

### 1. Volatility Cones

**Scenario**: Is current 30-day volatility cheap or expensive relative to history?

```python
from analysis3054 import TimeSeriesLab

lab = TimeSeriesLab(df, 'date', 'price')
lab.analyze_commodities('volatility')
# Plots Max, Min, Median, and Current vol across 10, 30, 60, 90 day horizons.
```

### 2. Spread Analysis (Pairs Trading)

**Scenario**: Is the spread between Crude Oil and Gasoline stationary? What is the hedge ratio?

```python
from analysis3054 import analyze_spread_cointegration

metrics, fig = analyze_spread_cointegration(df, 'date', asset1='Gasoline', asset2='Crude')
print(f"Hedge Ratio: {metrics['Hedge_Ratio']}")
fig.show() # Shows normalized spread Z-Score
```

### 3. Seasonality Heatmap

**Scenario**: Identify seasonal weak months for Natural Gas over the last 10 years.

```python
from analysis3054 import plot_seasonal_heatmap

# Plots Monthly Returns Heatmap (Year on Y-axis, Month on X-axis)
fig = plot_seasonal_heatmap(df, 'date', 'natgas_price', metric='return')
fig.show()
```

### 4. Term Structure (Roll Yield)

**Scenario**: Analyze the roll yield between Front Month and Second Month contracts.

```python
from analysis3054 import analyze_term_structure

# df must have 'price_m1' and 'price_m2'
res_df, fig = analyze_term_structure(df, 'date', front_col='price_m1', back_col='price_m2')
fig.show()
```

---

## Production Ready: The Unified API

For rapid analysis and production pipelines, use `TimeSeriesLab`.

```python
import pandas as pd
from analysis3054 import TimeSeriesLab

# 1. Load Data
df = pd.read_csv('data.csv')
lab = TimeSeriesLab(df, date_col='date', target_col='sales')

# 2. Clean & Check Health
lab.clean(fill_method='interpolate').check_health()

# 3. Visualize
lab.plot(interactive=True)

# 4. Analyze Structure
lab.analyze('decomposition') # STL
lab.analyze('wavelet') # Frequency spectrum

# 5. Backtest a Model
lab.backtest(model='random_forest', initial_window=100, horizon=10)

# 6. Forecast
result = lab.forecast(model='chronos', prediction_start='2024-01-01')
result.figure_interactive.show()
```
