Metadata-Version: 2.4
Name: tda-finance-mapper
Version: 0.1.0
Summary: Aplicación de análisis topológico de datos a carteras financieras.
Author-email: Jaime Corzo Galdó <jcggranada04@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jaimecrz3/tda-finance-mapper
Project-URL: Repository, https://github.com/jaimecrz3/tda-finance-mapper
Project-URL: Documentation, https://github.com/jaimecrz3/tda-finance-mapper
Project-URL: Issues, https://github.com/jaimecrz3/tda-finance-mapper/issues
Keywords: topological-data-analysis,finance,mapper,persistent-homology,portfolio-construction
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn>=1.2
Requires-Dist: umap-learn
Requires-Dist: kmapper
Requires-Dist: networkx
Requires-Dist: ripser
Requires-Dist: persim
Requires-Dist: gudhi
Requires-Dist: matplotlib
Requires-Dist: pyarrow
Requires-Dist: pandas-datareader
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Requires-Dist: flake8-pyproject; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Dynamic: license-file

# TDA Finance Mapper

`tda-finance-mapper` is a Python package developed as part of an academic project on the application of Topological Data Analysis (TDA) to financial data.

The package provides tools to build Mapper-based portfolio strategies, compute persistent-homology regime signals and evaluate the resulting portfolios through causal backtesting.

## Overview

The project studies whether topological information extracted from financial return windows can be used for:

1. market-structure analysis;
2. regime detection;
3. portfolio construction;
4. comparison against a simple equal-weight benchmark.

The main implemented models are:

- **Mapper portfolio**: assets are represented by recent return vectors, a Mapper graph is built, and the graph structure is transformed into portfolio weights.
- **Mapper + persistent homology**: Mapper remains the main portfolio construction method, while persistent homology acts as a regime-control signal.
- **Equal-weight benchmark**: all available assets receive the same weight and are evaluated with the same backtesting protocol.

## Disclaimer

This project is for academic and research purposes only. It is not financial advice, investment advice or a production trading system. The results are intended to illustrate and evaluate a methodological pipeline, not to recommend real investment decisions.

## Installation

Clone the repository:

```bash
git clone https://github.com/usuario/tda-finance-mapper.git
cd tda-finance-mapper
````

Create and activate a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
```

On Windows:

```bash
.venv\Scripts\activate
```

Install the package in editable mode:

```bash
pip install -r requirements.txt
```

The `requirements.txt` file installs the package with:

```txt
-e .
```

This means that changes made in the source code are immediately available without reinstalling the package.

For development tools such as `flake8`, `pytest`, `sphinx`, `build` and `twine`, install the optional development dependencies:

```bash
pip install -e .[dev]
```

## Project structure

```text
tda-finance-mapper/
├── data/
├── docs/
├── results_49_Industry_Portfolios/
├── results_SP500_CRSP/
├── scripts/
├── src/
│   └── tda_finance/
│       ├── data_preprocessing/
│       ├── experiments/
│       ├── portfolio/
│       └── tda/
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md
```

The main package is located under `src/tda_finance`.

The `scripts/` folder contains auxiliary scripts used during data preparation. These scripts are not part of the main package API.

## Main modules

### `tda_finance.tda.mapper_clustering`

Builds Mapper graphs from financial price windows and converts Mapper clusters into portfolio weights.

### `tda_finance.tda.persistence_diagrams`

Computes correlation-based distance matrices and persistent-homology diagrams.

### `tda_finance.tda.persistence_features`

Extracts summary features from persistence diagrams.

### `tda_finance.tda.regime_detection`

Computes persistence-landscape norms and detects topological anomalies.

### `tda_finance.portfolio.backtest_engine`

Runs causal long-only backtests, computes portfolio returns, turnover and performance metrics.

### `tda_finance.data_preprocessing`

Contains utilities to preprocess Kenneth French 49 Industry Portfolios and S&P 500 CRSP monthly data.

## Minimal API example

The following example shows the basic use of the package API with a generic price matrix.

```python
import pandas as pd

from tda_finance.portfolio.backtest_engine import backtest_tda, perf_summary
from tda_finance.tda.mapper_clustering import MapperParams

prices = pd.read_csv(
    "data/prices.csv",
    index_col=0,
    parse_dates=True,
)

params = MapperParams(
    pca_var=0.80,
    umap_dim=1,
    n_cubes=12,
    perc_overlap=0.25,
    clusterer="haca",
    haca_distance_threshold=0.6,
    haca_linkage="average",
    random_state=1,
)

result = backtest_tda(
    prices=prices,
    lookback_days=60,
    rebalance_days=3,
    params=params,
    tc_bps=5.0,
    use_ph_control=False,
)

metrics = perf_summary(
    result["port_ret"],
    periods_per_year=12,
)

print(metrics)
```

This is only a minimal usage example. The full experimental protocol is implemented in the experiment script described below.

## Running the final experiments

The final experiments can be run from the project root with:

```bash
python -m tda_finance.experiments.run_mapper_ph_experiments
```

The script compares:

1. Mapper;
2. Mapper with persistent-homology regime control;
3. equal-weight benchmark.

The selected dataset is configured inside the script.

## Data preparation

Auxiliary scripts used to prepare the S&P 500 CRSP data are located in:

```text
scripts/data_preparation/
```

Example:

```bash
python scripts/data_preparation/prepare_prices_sp500.py
python scripts/data_preparation/make_monthly_sp500.py
```

These scripts are included to make the data preparation process more transparent, but they are not part of the main package API.

## Results

The complete experimental results are discussed in the accompanying TFG report.

The repository also stores generated CSV outputs in:

```text
results_49_Industry_Portfolios/
results_SP500_CRSP/
```

These files include summary metrics, diagnostic outputs and NAV curves used in the experimental analysis.

## Reproducibility

The experiments use fixed random seeds where stochastic methods are involved, especially in dimensionality reduction.

For exact reproducibility of the Python environment used to run the experiments, a lock file can be generated with:

```bash
pip freeze > requirements-lock.txt
```

This file records the exact package versions installed in the environment. It is mainly useful for reproducing the results of the TFG, not for publishing the package to PyPI.

## Development and packaging checks

The following commands are useful during development. They require the optional development dependencies:

```bash
pip install -e .[dev]
```

Run style checks:

```bash
python -m flake8 src scripts
```

Run a basic import check:

```bash
python -c "from tda_finance.tda.mapper_clustering import MapperParams; print(MapperParams())"
```

Build the package locally:

```bash
python -m build
```

Check the distribution before uploading to PyPI:

```bash
python -m twine check dist/*
```

## License

This project is released under the MIT License. See the `LICENSE` file for details.

