autofcholv

A Python library for Automated extraction of relevant features from OHLCV time series data. Designed to help quantitative researchers and traders quickly generate a massive set of highly predictive features from basic pricing and volume data.

Key Features

• Automated Validation & Cleaning: Built-in verification processes that ensure input OHLCV records don't contain logical errors, missing records, or erroneous overlaps (such as incorrect High/Low bounds).
• Vectorized Execution: Under the hood, feature extraction heavily uses vectorized pandas and numpy functions alongside pandas-ta to ensure lightning-fast execution times, even when handling millions of rows.
• Broad Feature Sets: Automatically extracts everything from time signatures and candlestick geometries to advanced fractal mathematics like the Hurst Exponent.
• CLI Included: Ships with an easy-to-use Command Line Interface (autofcholv) for users who want to run extractions in a terminal.

Installation

Using pip

It is recommended to use a virtual environment (venv).

pip install autofcholv

Using uv (recommended)

uv is an extremely fast Python package manager. Install it first if you haven't:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the library:

uv add autofcholv

Or run it in an isolated environment without installing:

uvx autofcholv

From source

# Clone the repository
git clone https://github.com/tempusoneps/autofcholv.git
cd autofcholv

# Install via pip
pip install .

# Or via uv
uv sync

# For development mode (pip)
pip install -e .[dev]

# For development mode (uv)
uv sync --dev

Requirements

• Python >= 3.12
• pandas
• numpy
• pandas_ta
• python-dotenv

Usage

Using the Command Line Interface (CLI)

After installing, the autofcholv command is immediately available in your terminal.

extract - Extract features from a CSV file

autofcholv extract input.csv --output my_features.csv

Options:

• input: Path to your input OHLCV CSV file. It must contain Date, Open, High, Low, Close, and Volume columns.
• --output, -o: The path where the output features CSV will be saved (default: output_features.csv).
• --no-progress: Disable the extraction progress bar.

generate-config - Generate a default configuration file

autofcholv generate-config --path config.json

Options:

• --path, -p: Path to save the generated JSON config file (default: config.json).

This creates a config file pre-filled with all default configuration values. Edit it to customise feature behaviour (e.g. ONE_DAY_BARS=49, SELECTED_TIME_FRAME=15m).

Global Options

• --version, -v: Print library version.
• --help, -h: Show help message.

Using the Python API

You can easily use autofcholv directly in Jupyter Notebooks or Python scripts:

import pandas as pd
from autofcholv import extract_features, load_config

# 1. Load your OHLCV data into a Pandas DataFrame
# It is important that index is a DatetimeIndex and columns are correctly named
df = pd.read_csv("historic_data.csv", index_col="Date", parse_dates=True)

# 2. Run the extraction pipeline
config = load_config("config.json")
features_df = extract_features(df, config=config)

# 3. View the results
print(features_df.tail())

Configuration

autofcholv loads configuration into a typed Config object:

1. Config file - a JSON or YAML file passed explicitly via the API (load_config(path)) or CLI (--config). .env files are not supported.
2. Default config file - config.default.json (searched in the current working directory, then packaged library defaults) is loaded automatically if no config file is specified.
3. Built-in defaults - fallback defaults from the Config dataclass are applied if no config file is found.

SELECTED_TIME_FRAME: 15m
ONE_DAY_BARS: 49
MICRO_LOOKBACK: 5
SHORT_LOOKBACK: 10
MEDIUM_LOOKBACK: 20
LONG_LOOKBACK: 50
MACRO_LOOKBACK: 100

Other Resources

Please refer to the Pipeline Overview for a comprehensive list of all generated features.

Please refer to the Extracted Features Catalog for a comprehensive list of all generated features.