Metadata-Version: 2.4
Name: RiskLabAI
Version: 3.1.0
Summary: Financial machine-learning and causal-factor analysis tools for research and model validation.
Author-email: Hamid Arian <arian@risklab.ai>
Maintainer-email: Hamid Arian <arian@risklab.ai>
License-Expression: BSD-3-Clause
Project-URL: Repository, https://github.com/RiskLabAI/RiskLabAI.py
Project-URL: Issues, https://github.com/RiskLabAI/RiskLabAI.py/issues
Project-URL: Documentation, https://github.com/RiskLabAI/RiskLabAI.py#readme
Keywords: causal inference,factor investing,financial machine learning,quantitative finance,risk management
Classifier: Development Status :: 5 - Production/Stable
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=2.2
Requires-Dist: pandas<4,>=2.3
Requires-Dist: scipy<2,>=1.15
Requires-Dist: scikit-learn<2,>=1.6
Requires-Dist: statsmodels<0.15,>=0.14.6
Requires-Dist: joblib<2,>=1.4; python_version < "3.14"
Requires-Dist: joblib<2,>=1.5.2; python_version >= "3.14"
Requires-Dist: PyWavelets<2,>=1.9
Provides-Extra: speed
Requires-Dist: numba<0.68,>=0.67; extra == "speed"
Requires-Dist: numpy<2.6,>=2.2; extra == "speed"
Provides-Extra: pde
Requires-Dist: torch<3,>=2.10; extra == "pde"
Provides-Extra: synth
Requires-Dist: quantecon<0.12,>=0.11.4; extra == "synth"
Provides-Extra: hpo
Requires-Dist: optuna<5,>=4.9; extra == "hpo"
Provides-Extra: plot
Requires-Dist: matplotlib<4,>=3.10; extra == "plot"
Requires-Dist: seaborn<0.14,>=0.13.2; extra == "plot"
Requires-Dist: plotly<7,>=6; extra == "plot"
Provides-Extra: symbolic
Requires-Dist: sympy<2,>=1.14; extra == "symbolic"
Provides-Extra: profile
Requires-Dist: memory-profiler==0.61.0; extra == "profile"
Provides-Extra: simulation
Requires-Dist: tqdm<5,>=4.70; extra == "simulation"
Provides-Extra: changepoints
Requires-Dist: ruptures==1.1.10; python_version < "3.14" and extra == "changepoints"
Provides-Extra: test
Requires-Dist: pytest<10,>=8.4; extra == "test"
Dynamic: license-file

# RiskLabAI

[![PyPI version](https://badge.fury.io/py/RiskLabAI.svg)](https://badge.fury.io/py/RiskLabAI)
[![CI](https://github.com/RiskLabAI/RiskLabAI.py/actions/workflows/ci.yml/badge.svg)](https://github.com/RiskLabAI/RiskLabAI.py/actions/workflows/ci.yml)

RiskLabAI is a Python library for quantitative finance, financial machine
learning, and causal factor analysis. It provides research-oriented
implementations of methods associated with Marcos López de Prado's *Advances
in Financial Machine Learning*, *Machine Learning for Asset Managers*, and
*Causal Factor Investing*.

RiskLabAI 3.1.0 preserves the clean 57-name causal-factor-analysis namespace
released in 3.0.0 and adds 30 paper-derived names, producing an 87-name causal
API. The companion
[RiskLabAI.jl](https://github.com/RiskLabAI/RiskLabAI.jl) package independently
implements the same concepts. This parity statement applies to the causal API,
not to every Python module.

## What is included

- **Causal factor analysis** - constrained minimum-variance allocation,
  factor-mirage and allocation-misspecification diagnostics, graphical
  identification and factor roles, deterministic structural-model evaluation,
  treatment-effect formulas, search-adjusted false discovery, specification
  experiments, and evidence records for the seven-stage causal-factor protocol
- **Financial data structures** - tick, volume, dollar, imbalance, run, and
  time bars
- **Labeling and sample weights** - triple-barrier, meta-labeling,
  trend-scanning, uniqueness, and time-decay methods
- **Fractional differentiation and denoising** - fixed-width fractional
  differentiation, Marcenko-Pastur denoising, and targeted shrinkage
- **Validation and feature importance** - purged and combinatorial
  cross-validation, walk-forward validation, MDI, MDA, SFI, and clustered
  variants
- **Portfolio and backtest analytics** - HRP, NCO, hedging, PSR/DSR, PBO, and
  strategy-risk tools
- **Market features** - microstructure, entropy, structural-break, and
  technical-indicator utilities
- **Optional capabilities** - plotting, optimization, simulation, symbolic
  analysis, changepoint detection, acceleration, synthetic-control tools, and
  a Deep-BSDE PDE solver

## Compatibility

RiskLabAI 3.1.0 supports CPython 3.12,
3.13, and 3.14 with NumPy `>=2.2,<3`. The complete tested policy and
feature-specific limitations are in
[`docs/compatibility.md`](https://github.com/RiskLabAI/RiskLabAI.py/blob/main/docs/compatibility.md).

## Installation

Install the base package from PyPI:

```bash
python -m pip install RiskLabAI
```

Optional dependency groups can be installed individually or together:

| Extra | Enables |
|---|---|
| `speed` | Numba acceleration |
| `pde` | Deep-BSDE PDE solver using PyTorch |
| `synth` | synthetic-control utilities using QuantEcon |
| `hpo` | hyperparameter tuning using Optuna |
| `plot` | Matplotlib, Seaborn, and Plotly helpers |
| `symbolic` | symbolic analysis using SymPy |
| `profile` | memory profiling |
| `simulation` | simulation progress support |
| `changepoints` | changepoint detection on Python 3.12-3.13 |
| `test` | the supported pytest test runner |

For example:

```bash
python -m pip install "RiskLabAI[plot,speed]"
```

There is intentionally no `all` extra. See
[`INSTALLATION.md`](https://github.com/RiskLabAI/RiskLabAI.py/blob/main/INSTALLATION.md) for environment setup, all tested optional
groups, and development instructions.

## Causal-factor quick start

```python
import numpy as np

from RiskLabAI.causal_factor_analysis import (
    CausalDAG,
    average_treatment_effect,
    check_backdoor_adjustment_set,
    minimum_variance_factor_weights,
)

covariance = np.diag([1.0, 2.0, 4.0])
factor_exposures = np.array([[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
target_exposures = np.array([0.0, 1.0])

weights = minimum_variance_factor_weights(
    covariance,
    factor_exposures,
    target_exposures,
)
np.testing.assert_allclose(weights, [-2.0 / 7.0, 5.0 / 7.0, 2.0 / 7.0])

effect = average_treatment_effect(3.5, 1.25)
assert effect == 2.25

dag = CausalDAG(
    nodes=("T", "U", "Y"),
    directed_edges=(("U", "T"), ("U", "Y"), ("T", "Y")),
    observed_nodes=("T", "U", "Y"),
)
assert check_backdoor_adjustment_set(dag, "T", "Y", ("U",)).admissible
```

The complete deterministic example is
[`examples/causal_factor_analysis_quickstart.py`](https://github.com/RiskLabAI/RiskLabAI.py/blob/main/examples/causal_factor_analysis_quickstart.py).
The causal API and its limits are documented in
[`docs/causal_factor_analysis.md`](https://github.com/RiskLabAI/RiskLabAI.py/blob/main/docs/causal_factor_analysis.md).

## Financial-data quick start

```python
from RiskLabAI.data.structures.standard_bars import StandardBars
from RiskLabAI.utils.constants import CUMULATIVE_DOLLAR

ticks = [
    ("2020-01-01 10:00:00", 100.0, 10),
    ("2020-01-01 10:00:01", 101.0, 5),
    ("2020-01-01 10:00:02", 100.0, 20),
]

bars = StandardBars(bar_type=CUMULATIVE_DOLLAR, threshold=3000)
bar_list = bars.construct_bars_from_data(ticks)
```

## Extending the library

The `RiskLabAI.core` registries provide discovery and construction points for
bars, cross-validators, feature-importance models, labelers, bet sizers, and
portfolio optimizers. For example:

```python
import pandas as pd

from RiskLabAI.core import CROSS_VALIDATORS, list_components

catalogue = list_components()
start_times = pd.to_datetime(["2024-01-02", "2024-01-03", "2024-01-04"])
event_times = pd.Series(
    pd.to_datetime(["2024-01-03", "2024-01-04", "2024-01-05"]),
    index=start_times,
)
cross_validator = CROSS_VALIDATORS.create(
    "purgedkfold",
    n_splits=5,
    times=event_times,
)
```

See [`EXTENDING.md`](https://github.com/RiskLabAI/RiskLabAI.py/blob/main/EXTENDING.md)
for the extension interfaces and examples.

## Development

```bash
python -m pip install -e ".[test]" "black==26.5.1" "ruff==0.15.17"
python -m pytest -q
black --check src/RiskLabAI/causal_factor_analysis test/causal_factor_analysis
ruff check src/RiskLabAI/causal_factor_analysis test/causal_factor_analysis
```

Please branch from `main`, keep changes focused, and include tests for behavior
changes.

## Scope

RiskLabAI is research software, not investment advice. Graph routines evaluate
criteria on a caller-supplied directed acyclic graph; they do not discover or
certify that graph. Protocol records validate declared evidence structures;
they do not prove that empirical assumptions are true.

## License

RiskLabAI is distributed under the
[BSD 3-Clause License](https://github.com/RiskLabAI/RiskLabAI.py/blob/main/LICENSE).
