Metadata-Version: 2.4
Name: marketmind
Version: 0.2.0
Summary: Market-regime research through fractal, information-theoretic, and financial-network measures
Author: Layan Oraidi
License-Expression: BSD-3-Clause
Project-URL: Documentation, https://layan985.github.io/marketmind/
Project-URL: Issues, https://github.com/layan985/marketmind/issues
Project-URL: Repository, https://github.com/layan985/marketmind
Keywords: financial markets,market regimes,information theory,transfer entropy,fractal analysis,network science,technical analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: scipy>=1.10
Provides-Extra: data
Requires-Dist: yfinance>=0.2.40; extra == "data"
Provides-Extra: dashboard
Requires-Dist: plotly>=5.20; extra == "dashboard"
Requires-Dist: streamlit>=1.35; extra == "dashboard"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
Provides-Extra: test
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: mypy>=1.10; extra == "test"
Requires-Dist: pandas-stubs>=2.0; extra == "test"
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Requires-Dist: ruff>=0.7; extra == "test"
Requires-Dist: twine>=5.1; extra == "test"
Requires-Dist: types-PyYAML>=6.0; extra == "test"
Provides-Extra: all
Requires-Dist: build>=1.2; extra == "all"
Requires-Dist: mkdocs>=1.6; extra == "all"
Requires-Dist: mkdocs-material>=9.5; extra == "all"
Requires-Dist: mkdocstrings[python]>=0.27; extra == "all"
Requires-Dist: mypy>=1.10; extra == "all"
Requires-Dist: pandas-stubs>=2.0; extra == "all"
Requires-Dist: plotly>=5.20; extra == "all"
Requires-Dist: pytest>=8.0; extra == "all"
Requires-Dist: pytest-cov>=5.0; extra == "all"
Requires-Dist: ruff>=0.7; extra == "all"
Requires-Dist: streamlit>=1.35; extra == "all"
Requires-Dist: twine>=5.1; extra == "all"
Requires-Dist: types-PyYAML>=6.0; extra == "all"
Requires-Dist: yfinance>=0.2.40; extra == "all"
Dynamic: license-file

# MarketMind

[![CI](https://github.com/layan985/marketmind/actions/workflows/ci.yml/badge.svg)](https://github.com/layan985/marketmind/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/marketmind.svg)](https://pypi.org/project/marketmind/)
[![Python](https://img.shields.io/pypi/pyversions/marketmind.svg)](https://pypi.org/project/marketmind/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21844956.svg)](https://doi.org/10.5281/zenodo.21844956)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)

A market-regime test can look predictive when its normalization bounds, regime thresholds, or trading rules are chosen with knowledge of the evaluation period. MarketMind puts those choices into code so their timing can be inspected and the same rules can be run again.

The package implements the Market Intelligence Index (MII) from my [2026 Charles H. Dow Award](https://cmtassociation.org/association/award-recognizing/charles-h-dow-award/) paper, *The Emergent Market Mind*. The paper argues that market organization can be studied through changes in memory, information flow, and cross-market connectivity.

## Current status

As of 13 August 2026:

- version 0.1.0 remains the frozen release used by the preregistration; v0.2.0 adds the controlled audit and executable study engine without altering that freeze;
- 29 tests pass with 83.06% branch-aware coverage in the current source environment;
- the controlled v0.2.0 research audit passes 7/7 checks, including future-perturbation, known-structure, directional-information, execution-timing, and artifact-integrity tests;
- the prospective test is active from 10 August 2026 through 6 August 2027, while all confirmatory performance remains sealed;
- no result from that holdout exists yet;
- the public-data pipeline is not a numerical reproduction of the paper because the Bloomberg and Refinitiv histories used in the paper cannot be redistributed;
- no independent reproduction or outside research use is recorded yet.

See [RESULTS.md](RESULTS.md) for the result status and [preregistration/DEVIATIONS.csv](preregistration/DEVIATIONS.csv) for changes made after registration.

## Verification snapshot

| Controlled check | Frozen v0.2.0 result |
| --- | ---: |
| Connectivity metrics vs. disclosed trailing latent coherence | 0.879–0.901 correlation |
| Earlier raw-metric change after a future-only perturbation | 0.0 max absolute difference |
| Earlier regime rows changed after a future-only perturbation | 0 / 350 |
| Known source→target minus reverse transfer entropy | +1.218 nats |
| Same-session position under the confirmatory contract | 0.0 |
| Hash-verified result files | 4 / 4 |

Reproduce the complete evidence pack:

```bash
marketmind audit --output artifacts/research-audit
```

The committed [audit report](validation/audit-v0.2.0/AUDIT.md) states the acceptance rule, observed statistic, environment, and interpretation boundary for every check. It is controlled implementation evidence—not a profitability claim.

## Method

MII combines three groups of measurements:

| Component | Measurements | Weight |
| --- | --- | ---: |
| Memory | DFA Hurst exponent, Higuchi fractal dimension, absolute-return ACF decay | 0.35 |
| Information flow | Shannon entropy, Kraskov mutual information, transfer entropy | 0.40 |
| Connectivity | Correlation strength, weighted clustering, correlation-distance MST | 0.25 |

Low, medium, and high states are defined by terciles estimated from the preceding three years and refreshed monthly. The expanding-normalization option also uses only observations available at the date being classified.

## Install and run

```bash
pip install marketmind
```

```python
from marketmind import MarketMind, MarketMindConfig
from marketmind.synthetic import synthetic_market

prices = synthetic_market(periods=1_500, assets=8, seed=42)
model = MarketMind(MarketMindConfig(window=252, step=21))
result = model.fit_transform(
    prices[["SPX", "NDX", "SX5E", "ES"]],
    network_data=prices,
)

print(result.to_frame().tail())
```

An offline example writes its inputs, configuration, raw metrics, MII states, and file hashes to one directory:

```bash
marketmind demo --output artifacts/demo
```

Install `marketmind[data]` for the public-data adapter or `marketmind[dashboard]` for the optional Streamlit interface.

## Prospective test

The registered hypothesis maps high MII to trend signals, medium MII to breakout or volatility-expansion signals, and low MII to mean-reversion signals. The test fixes the market panel, signal definitions, one-session execution lag, primary 5-basis-point cost assumption, inference, exclusions, and robustness checks before the holdout is observed.

- Registration: [OSF nyseh](https://osf.io/nyseh/overview)
- Written plan: [preregistration/OSF_MARKETMIND_PROSPECTIVE_2026.md](preregistration/OSF_MARKETMIND_PROSPECTIVE_2026.md)
- Executable configuration: [config/preregistered-validation-2026.yml](config/preregistered-validation-2026.yml)

The paper's award and development-sample results are not treated as confirmation of this prospective hypothesis.

The registered analysis is executable rather than prose-only. `marketmind.study` constructs the three signal families, the regime-aware and unconditional exposures, one-session-lagged net returns, paired cross-market Sharpe bootstraps for H1/H3, and Holm-corrected mechanism tests for H2a–H2c. Interim holdout outcomes are not exposed.

## Data limitation

The paper used Bloomberg for SPX, NDX, VIX, and continuous ES; Refinitiv for SX5E; Yahoo Finance for sector ETFs; and FRED for ancillary checks. The first two sources cannot be redistributed here.

[config/paper-public.yml](config/paper-public.yml) substitutes public proxies. It can test whether the code runs and whether conclusions are sensitive to accessible data, but it cannot recover the paper's exact input histories. The 2015–2024 period is a validation sample from the paper, not a new untouched test set.

## Development

```bash
git clone https://github.com/layan985/marketmind.git
cd marketmind
python -m pip install -e ".[all]"
pytest
```

Method details are in [docs/methodology.md](docs/methodology.md). Data and timing conventions are in [REPRODUCIBILITY.md](REPRODUCIBILITY.md).

## Citation and license

> Oraidi, L. (2026). *MarketMind: Multiscale Market Intelligence Research Software* (v0.1.0). Zenodo. https://doi.org/10.5281/zenodo.21844956

BSD 3-Clause. MarketMind is research software, not an execution engine or investment recommendation.
