analysis3054 2.1.0

Advanced time-series analysis, plotting and forecasting utilities

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

pip install analysis3054

To use Chronos and Deep Learning features:

pip install analysis3054[ml] torch transformers accelerate
# For Chronos specifically
pip install git+https://github.com/amazon-science/chronos-forecasting.git

To use Prophet:

pip install prophet

To use GARCH models:

pip install arch

To use Wavelets:

pip install PyWavelets

---

User Guide: Commodity Trading Toolkit

1. Volatility Cones

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

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?

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.

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.

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.

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()