data-energy-ff 0.1.0

Utilities for crude-oil futures data analysis: MultiIndex CSV loading, dynamic butterfly spreads, roll-period splitting, and normalized plotting.

data-energy-ff

A small toolkit of helpers for crude-oil futures data analysis — loading pipeline CSVs into tidy pandas MultiIndex frames, building butterfly spreads from sequential outrights, splitting a series into roll-period windows, and quick normalized plots.

Installation

From PyPI (once published):

pip install data-energy-ff

Latest from source:

pip install "git+https://github.com/shubhquant1125ff-commits/pythonlib.git"

Quick start

import data_energy_ff as de

# 1. Load a futures CSV saved by the pipeline (restores the MultiIndex columns)
df = de.read_futures_csv_shubh("cl_outrights_1min.csv")

# 2. Build butterfly spreads from the sequential outrights (c1, c2, c3, ...)
flies = de.calculate_dynamic_butterflies(df)

# 3. Split a time series into pre / during / post roll windows
pre, during, post = de.split_by_roll_period(df, product="BRENT")

# 4. Compare two columns on a z-score normalized axis
de.plot_two_cols_normalized(df, ("c1", "weighted_mid"), ("c2", "weighted_mid"))

API

read_futures_csv_shubh(path, SEP="||")

Read a CSV saved by the futures pipeline and rebuild the clean MultiIndex DataFrame it was saved from. The first line is expected to be a metadata comment (#meta:<freq>||<level0_name>||<level1_name>), and column headers are SEP-joined tuples such as c1||weighted_mid. The datetime index is parsed as UTC and returned tz-naive.

calculate_dynamic_butterflies(df)

Build dynamic butterfly spreads from a MultiIndex frame of outrights. Level 0 holds the sequential outrights (c1, c2, ...) and level 1 holds contract and weighted_mid. For N outrights it returns N-2 butterflies priced as leg1 - 2*leg2 + leg3, with concatenated contract names. Raises ValueError if fewer than three outrights are present.

split_by_roll_period(df, product="BRENT")

Split a DatetimeIndex frame into (pre, during, post) roll-period windows using business-day-of-month thresholds. Windows adjust by product (BRENT/LCO, WTCL/CL/WTI, with a default fallback). Raises ValueError if the index is not a DatetimeIndex.

plot_two_cols_normalized(df, col1, col2)

Z-score normalize two columns and plot them together with a zero reference line, so you can see when each is above or below its own average.

Dependencies

Runtime: numpy, pandas, matplotlib, seaborn, plotly.

Development

git clone https://github.com/shubhquant1125ff-commits/pythonlib.git
cd pythonlib
python -m pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the full workflow and release steps.

License

MIT © Deepanshu Goyal and Shubh