# Reproduce the synthetic examples

Extract reproduce.zip and run commands from its root. Python 3.13 and uv are
required. `uv sync --group dev` installs NumPy, SciPy, Polars, Matplotlib,
CVXPY and pytest, using the dependency declarations in pyproject.toml.

## Figure data

Run `uv run python web/tools/data/f2-variance-level.py`, or replace the filename
with f4 through f13. Outputs go to web/public/data/. The archive includes the
summary inputs for f5, f7, f10 and f12, and the simulation modules for f4,
f11 and f13. Those summary-based scripts export existing results; they do not
rerun the underlying studies. The f13 script recomputes its four seeded paths.
Allow seconds for exporters; f13 can take minutes. Time depends on hardware.

Browser figures f1, f3 and f14 compute in the page. The embeds/ directory
contains their exact HTML and extracted JavaScript, plus the other article
figures. They require D3 v7, the article's CSS variables and a [data-embed]
container whose data-url points to the matching JSON. The scripts refer to
document.currentScript and run inside that container. They are not command-line
programs. The published JSON files contain their initial parameters.

## Section 3.5 tables and signal study

Run the complete sweep (107 units, 485 seeds, 20 seeds for each main
configuration; some variants use fewer seeds):

```sh
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 VECLIB_MAXIMUM_THREADS=1 uv run python -m sim.signal_attribution.run_local full results --workers 8
uv run python -m sim.signal_attribution.summarise results
uv run python -m sim.cli figures signal_attribution --results results --figdir figures --tier full
```

The original full sweep measured 6.060 summed unit wall-hours under concurrent
load. This is not CPU time or elapsed time for the parallel command above.
Allow hours, depending on hardware and worker count. The smoke tier is a
shorter execution check: replace full with smoke and use a separate directory.

Run the tests, including closed-form/CVXPY comparisons and approximate Shapley:

```sh
uv run pytest sim/signal_attribution/tests
```

Run the approximate Shapley study described in sections 3.4 and 7.2:

```sh
uv run python -m sim.signal_attribution.approximate_study --help
```

Use its help for the output directory and study-size options. The archived
article-summary.json records the published table inputs. Simulation times and
floating-point results can vary by numerical library and hardware.

## Reuse

The text, figures, infographics and presentation are under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) (`LICENSE-CONTENT`);
the code (simulation package, figure exporters, notebook, page scripts, embeds and presentation view) is under [MIT](https://opensource.org/license/mit) (`LICENSE`).
All figures and diagrams are drawn for this page; numbers taken from published papers are cited in their captions.
Quoted passages, cited results and bibliographic metadata belong to their authors and publishers. Adapted and third-party components keep their own licences, listed in NOTICE.md.

The page adapts Thibaud Frere's [research article template](https://huggingface.co/spaces/tfrere/research-article-template) and David Louapre's [NLP before LLMs course page](https://huggingface.co/spaces/dlouapre/nlp-before-llms),
both under CC BY 4.0; the upstream notice is kept in `web/LICENSE`.

## Citation

For attribution in academic contexts, please cite this work as

> Sérié, E. (2026). Explaining a trading P&L: what finance knows about performance attribution, and what is open. https://attribution.serie-research.dev/attribution/

```bibtex
@misc{serie2026attribution,
  author = {S{\'e}ri{\'e}, Emmanuel},
  title = {Explaining a trading {P\&L}: what finance knows about performance attribution, and what is open},
  year = {2026},
  month = nov,
  url = {https://attribution.serie-research.dev/attribution/},
  note = {Code: https://github.com/serie-research/pnl-attribution}
}
```