tda-finance-mapper 0.1.0__tar.gz

tda_finance_mapper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Corzo Galdó
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tda_finance_mapper-0.1.0/PKG-INFO

@@ -0,0 +1,299 @@
+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.
+

tda_finance_mapper-0.1.0/README.md

@@ -0,0 +1,258 @@
+# 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.
+

tda_finance_mapper-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tda-finance-mapper"
+version = "0.1.0"
+description = "Aplicación de análisis topológico de datos a carteras financieras."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Jaime Corzo Galdó", email = "jcggranada04@gmail.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+  "topological-data-analysis",
+  "finance",
+  "mapper",
+  "persistent-homology",
+  "portfolio-construction",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+dependencies = [
+  "numpy",
+  "pandas",
+  "scikit-learn>=1.2",
+  "umap-learn",
+  "kmapper",
+  "networkx",
+  "ripser",
+  "persim",
+  "gudhi",
+  "matplotlib",
+  "pyarrow",
+  "pandas-datareader",
+]
+
+[project.optional-dependencies]
+dev = [
+  "flake8",
+  "flake8-pyproject",
+  "pyright",
+  "pytest",
+  "build",
+  "twine",
+  "sphinx",
+  "sphinx-rtd-theme",
+]
+
+[project.urls]
+Homepage = "https://github.com/jaimecrz3/tda-finance-mapper"
+Repository = "https://github.com/jaimecrz3/tda-finance-mapper"
+Documentation = "https://github.com/jaimecrz3/tda-finance-mapper"
+Issues = "https://github.com/jaimecrz3/tda-finance-mapper/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "basic"
+pythonVersion = "3.12"
+
+[tool.flake8]
+max-line-length = 119
+extend-ignore = ["E203", "W503"]
+exclude = [
+  ".git",
+  "__pycache__",
+  "build",
+  "dist",
+  ".venv",
+  "venv",
+  "env",
+  "docs/_build",
+  "*.egg-info"
+]
+

tda_finance_mapper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tda_finance_mapper-0.1.0/src/tda_finance/__init__.py

@@ -0,0 +1,3 @@
+"""Topological Data Analysis tools for financial portfolio experiments."""
+
+__version__ = "0.1.0"

tda_finance_mapper-0.1.0/src/tda_finance/data_preprocessing/__init__.py

@@ -0,0 +1 @@
+"""Data preprocessing utilities for financial datasets."""