Metadata-Version: 2.4
Name: data-energy-ff
Version: 0.1.0
Summary: Utilities for crude-oil futures data analysis: MultiIndex CSV loading, dynamic butterfly spreads, roll-period splitting, and normalized plotting.
Author: Shubh
Author-email: Deepanshu Goyal <deepanshugoyal9000@gmail.com>
Maintainer-email: Deepanshu Goyal <deepanshugoyal9000@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/shubhquant1125ff-commits/pythonlib
Project-URL: Repository, https://github.com/shubhquant1125ff-commits/pythonlib
Project-URL: Issues, https://github.com/shubhquant1125ff-commits/pythonlib/issues
Project-URL: Changelog, https://github.com/shubhquant1125ff-commits/pythonlib/blob/main/CHANGELOG.md
Keywords: futures,commodities,crude-oil,brent,wti,butterfly-spread,trading,quant,pandas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: plotly
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# data-energy-ff

[![CI](https://github.com/shubhquant1125ff-commits/pythonlib/actions/workflows/ci.yml/badge.svg)](https://github.com/shubhquant1125ff-commits/pythonlib/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/data-energy-ff.svg)](https://pypi.org/project/data-energy-ff/)
[![Python versions](https://img.shields.io/pypi/pyversions/data-energy-ff.svg)](https://pypi.org/project/data-energy-ff/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
pip install data-energy-ff
```

Latest from source:

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

## Quick start

```python
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

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and release steps.

## License

[MIT](LICENSE) © Deepanshu Goyal and Shubh
