# quantopian/pyfolio architecture

> Architecture diagram of the GitHub repository quantopian/pyfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantopian/pyfolio
- Repository: https://github.com/quantopian/pyfolio

## Overview

##### Project type and purpose
- pyfolio is a Python library for performance & risk analysis of financial portfolios.
- It consumes time-series data (returns, positions, transactions), processes it, and produces tear-sheet plots.
- Integrates tightly with Zipline (backtester), Jupyter notebooks, and common data science libs (Pandas, NumPy, Matplotlib, Seaborn).

##### Main components
a. Data ingestion & input
– Raw data sources: equity returns, transaction histories, position snapshots, factor returns (CSV, DataFrame).
– Users import data via Pandas or Zipline APIs.
b. Core analysis modules (pyfolio package)
– timeseries.py: series-level calculations (returns, drawdowns).
– perf_attrib.py & capacity.py: performance attribution, capacity modeling.
– pos.py & txn.py: position and transaction parsing.
– round_trips.py: trade round-trip analysis.
– interesting_periods.py: select significant time windows.
– tears.py: assemble metrics & generate tear-sheet sections.
– plotting.py & _seaborn.py: visualization logic, Matplotlib/Seaborn wrappers.
– utils.py: shared utilities (date handling, configuration).
c. Presentation layer
– Generating figures (Matplotlib Figure objects) and embedding in Jupyter notebook cells.
– PNG/HTML export for reports (via notebooks or direct save).
d. Packaging & tooling
– setup.py / conda/meta.yaml: distribution configuration.
– versioneer.py: version management.
– docs/ & mkdocs.yml: static site generation for docs.
– Travis CI (.travis.yml): continuous integration.
– build_and_deploy_docs.sh, conda/build scripts: automated builds & deployment.
e. Testing
– pyfolio/tests/: unit tests against test_data CSVs.
– Notebook tests: docs/notebooks conversion & execution (mkdocs integration).

##### Relationships & data flow
– Analysis modules depend on Pandas/NumPy libraries (annotate that dependency).
– Core modules feed their outputs (metrics, DataFrames) into plotting.py.
– Presentation node outputs to Jupyter notebook interface or saved report.
– Packaging & tooling run separately: build scripts pick up source tree → produce PyPI/conda artifacts and docs site.
– Tests run against core modules and notebooks in CI pipeline.

##### Architectural patterns & design principles
- Modular separation by concern: data ingestion, core analytics, visualization, packaging, testing.
- Extensibility: adding new tear-sheet sections by extending tears.py; adding new plots via _seaborn helper.
- Layered design:
– Bottom layer: data structures & time-series logic.
– Middle layer: analytics & metrics.
– Top layer: visualization & reporting.
- Dependency injection: users supply DataFrames; modules remain agnostic to data source.

[Data Layer]
- CSV / Database / Zipline API → time-series ingestion
[Analytics Layer]
- timeseries.py → raw calculations
- perf_attrib.py → attribution metrics
- capacity.py → capacity modeling
- pos.py / txn.py → position & trade parsing
- round_trips.py → trade cycle analysis
- interesting_periods.py → period selection
[Tear-Sheet Assembly]
- tears.py → orchestrates analytics & plotting calls
[Visualization Layer]
- plotting.py / _seaborn.py → produces Matplotlib Figures
[Presentation]
- Jupyter Notebook / CLI save functions → final output
[Tooling & Packaging]
- setup.py, conda/, versioneer.py → build & distribution
- docs/, mkdocs.yml → documentation website
- .travis.yml, build_and_deploy_docs.sh → CI/CD pipelines
- pyfolio/tests/ → automated testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData(["CSV Files / Test Data"]):::data
        ZiplineAPI(["Zipline DataFrame Input"]):::external
    end

    %% Analytics Layer
    subgraph "Analytics Layer"
        direction TB
        TS(["timeseries.py"]):::core
        PA(["perf_attrib.py"]):::core
        Cap(["capacity.py"]):::core
        Pos(["pos.py"]):::core
        Txn(["txn.py"]):::core
        RT(["round_trips.py"]):::core
        IP(["interesting_periods.py"]):::core
        Utils(["utils.py"]):::core
    end

    %% Tear-Sheet Assembly
    subgraph "Tear-Sheet Assembly"
        direction TB
        Tears(["tears.py"]):::core
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        Plot(["plotting.py"]):::core
        Seaborn(["_seaborn.py"]):::core
    end

    %% Presentation
    subgraph "Presentation"
        direction TB
        Jupyter(["Jupyter Notebook Interface"]):::external
        CLI(["CLI/PNG/HTML Export"]):::external
    end

    %% Packaging & Tooling
    subgraph "Packaging & Tooling"
        direction TB
        Setup(["setup.py"]):::docs
        Conda(["conda/meta.yaml"]):::docs
        Version(["versioneer.py"]):::docs
        Mkdocs(["mkdocs.yml"]):::docs
        DocsSite(["docs/ Site Source"]):::docs
        Travis([".travis.yml"]):::docs
        BuildDocs(["build_and_deploy_docs.sh"]):::docs
    end

    %% Testing
    subgraph "Testing Framework"
        direction TB
        Tests(["pyfolio/tests/ & Notebook Tests"]):::docs
    end

    %% External Dependencies
    Pandas(["Pandas"]):::external
    NumPy(["NumPy"]):::external
    Matplotlib(["Matplotlib"]):::external
    SeabornLib(["Seaborn"]):::external
    ZiplineExt(["Zipline"]):::external
    JupyterExt(["Jupyter"]):::external

    %% Data Flow Arrows
    RawData -->|“DataFrame of returns/positions/transactions”| TS
    ZiplineAPI -->|“DataFrame Input”| TS
    TS --> PA
    TS --> Cap
    TS --> Pos
    Pos --> Txn
    TS --> RT
    TS --> IP
    TS --> Utils
    PA --> Tears
    Cap --> Tears
    Pos --> Tears
    Txn --> Tears
    RT --> Tears
    IP --> Tears
    Utils --> Tears
    Tears --> Plot
    Tears --> Seaborn
    Plot --> Jupyter
    Seaborn --> Jupyter
    Plot --> CLI
    Seaborn --> CLI

    %% Packaging & CI flows
    Setup -->|“Build”| Tests
    Conda --> Tests
    Version --> Tests
    Mkdocs --> DocsSite
    DocsSite --> BuildDocs
    Travis --> Tests
    Travis --> BuildDocs

    %% Dependencies
    TS -->|depends on| Pandas
    TS -->|depends on| NumPy
    PA --> Pandas
    Plot --> Matplotlib
    Plot --> SeabornLib
    Seaborn --> SeabornLib
    Jupyter --> JupyterExt

    %% Click Events
    click RawData "https://github.com/quantopian/pyfolio/tree/master/pyfolio/tests/test_data/"
    click TS "https://github.com/quantopian/pyfolio/blob/master/pyfolio/timeseries.py"
    click PA "https://github.com/quantopian/pyfolio/blob/master/pyfolio/perf_attrib.py"
    click Cap "https://github.com/quantopian/pyfolio/blob/master/pyfolio/capacity.py"
    click Pos "https://github.com/quantopian/pyfolio/blob/master/pyfolio/pos.py"
    click Txn "https://github.com/quantopian/pyfolio/blob/master/pyfolio/txn.py"
    click RT "https://github.com/quantopian/pyfolio/blob/master/pyfolio/round_trips.py"
    click IP "https://github.com/quantopian/pyfolio/blob/master/pyfolio/interesting_periods.py"
    click Utils "https://github.com/quantopian/pyfolio/blob/master/pyfolio/utils.py"
    click Tears "https://github.com/quantopian/pyfolio/blob/master/pyfolio/tears.py"
    click Plot "https://github.com/quantopian/pyfolio/blob/master/pyfolio/plotting.py"
    click Seaborn "https://github.com/quantopian/pyfolio/blob/master/pyfolio/_seaborn.py"
    click Setup "https://github.com/quantopian/pyfolio/blob/master/setup.py"
    click Conda "https://github.com/quantopian/pyfolio/blob/master/conda/meta.yaml"
    click Version "https://github.com/quantopian/pyfolio/blob/master/versioneer.py"
    click Mkdocs "https://github.com/quantopian/pyfolio/blob/master/mkdocs.yml"
    click DocsSite "https://github.com/quantopian/pyfolio/tree/master/docs/"
    click Travis "https://github.com/quantopian/pyfolio/blob/master/.travis.yml"
    click BuildDocs "https://github.com/quantopian/pyfolio/blob/master/build_and_deploy_docs.sh"
    click Tests "https://github.com/quantopian/pyfolio/tree/master/pyfolio/tests/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085
    classDef data fill:#d4edda,stroke:#155724
    classDef external fill:#fff3cd,stroke:#856404
    classDef docs fill:#f8d7da,stroke:#721c24
```
