# ranaroussi/quantstats architecture

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

- Interactive diagram: https://gitdiagram.com/ranaroussi/quantstats
- Repository: https://github.com/ranaroussi/quantstats

## Overview

##### Project type and purpose
- QuantStats is a Python library (not a standalone web app) that provides portfolio analytics and reporting.
- Its goal is to let quants and portfolio managers calculate statistics (Sharpe, drawdowns, etc.), produce visualizations (snapshots, drawdown charts), and generate HTML “tear sheet” reports.

##### File structure
- Top-level packaging/config:
- setup.py, setup.cfg, MANIFEST.in, requirements.txt, meta.yaml (for conda)
- .github/* and .travis.yml (CI/CD pipelines)
- Documentation: docs/ (includes an HTML tear sheet and supporting material)
- Core package: quantstats/
- stats.py – core performance-metric functions
- plots.py – high-level plotting functions
- reports.py – orchestration for metrics + plots to produce HTML reports
- utils.py – helper functions (e.g. data download via yfinance)
- _plotting/ – low-level plotting engine (core.py, wrappers.py)
- version.py – package version

##### README insights
- Confirms 3 main modules: stats, plots, reports
- Shows dependencies: pandas, numpy, scipy, matplotlib, seaborn, tabulate, yfinance, optional plotly
- Illustrates user flow: import qs → qs.extend_pandas() → download data via utils → call stats/plots/reports APIs → produce visual output or HTML

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Repo
    User["User Script / Python REPL"]:::external
    Repo["QuantStats Repository"]:::external

    %% QuantStats Core Modules
    subgraph "QuantStats Core Modules"
        direction TB
        Utils["quantstats.utils"]:::core
        Stats["quantstats.stats"]:::core
        Plots["quantstats.plots"]:::core
        subgraph "_plotting Subpackage"
            direction TB
            CorePlot["quantstats._plotting.core"]:::core
            Wrappers["quantstats._plotting.wrappers"]:::core
        end
        Version["quantstats.version"]:::core
        Reports["quantstats.reports"]:::core
    end

    %% External Data Source
    YFinance["yfinance Data Source"]:::external
    ExtLibs["External Libraries<br/>(pandas, numpy, scipy,<br/>matplotlib, seaborn, plotly, tabulate)"]:::external

    %% Outputs and Documentation
    subgraph "Documentation & Outputs"
        direction TB
        Docs["Documentation Site / Tear Sheet"]:::docs
        HTMLReport["HTML Tear Sheet Report"]:::outputs
        PlotsOut["Generated Plots"]:::outputs
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        GitHubActions1["GitHub Actions<br/>CodeQL Analysis"]:::ci
        GitHubActions2["GitHub Actions<br/>Python Publish"]:::ci
        Travis["Travis CI"]:::ci
        SetupPy["setup.py"]:::packaging
        SetupCFG["setup.cfg"]:::packaging
        Manifest["MANIFEST.in"]:::packaging
        MetaYml["meta.yaml"]:::packaging
        README["README.rst"]:::packaging
        Changelog["CHANGELOG.rst"]:::packaging
    end

    %% Relationships
    User -->|"calls"| Utils
    Utils -->|"downloads data"| YFinance
    User -->|"calls"| Stats
    User -->|"calls"| Plots
    Stats -->|"uses data structures"| ExtLibs
    Plots -->|"uses plotting libs"| ExtLibs
    Plots -->|"delegates to"| CorePlot
    Plots -->|"delegates to"| Wrappers
    Stats -->|"feeds into"| Reports
    Plots -->|"feeds into"| Reports
    Reports -->|"generates"| HTMLReport
    Reports -->|"generates"| PlotsOut
    Reports -->|"uses"| ExtLibs

    Repo -->|"triggers on push"| GitHubActions1
    Repo -->|"triggers on push"| GitHubActions2
    Repo -->|"triggers on push"| Travis
    Repo -->|"includes"| SetupPy
    Repo -->|"includes"| SetupCFG
    Repo -->|"includes"| Manifest
    Repo -->|"includes"| MetaYml
    Repo -->|"includes"| README
    Repo -->|"includes"| Changelog
    Repo -->|"includes"| Docs

    Docs -->|"renders"| HTMLReport

    %% Click Events
    click Stats "https://github.com/ranaroussi/quantstats/blob/main/quantstats/stats.py"
    click Plots "https://github.com/ranaroussi/quantstats/blob/main/quantstats/plots.py"
    click Reports "https://github.com/ranaroussi/quantstats/blob/main/quantstats/reports.py"
    click Utils "https://github.com/ranaroussi/quantstats/blob/main/quantstats/utils.py"
    click CorePlot "https://github.com/ranaroussi/quantstats/blob/main/quantstats/_plotting/core.py"
    click Wrappers "https://github.com/ranaroussi/quantstats/blob/main/quantstats/_plotting/wrappers.py"
    click Version "https://github.com/ranaroussi/quantstats/blob/main/quantstats/version.py"
    click Docs "https://github.com/ranaroussi/quantstats/tree/main/docs/"
    click GitHubActions1 "https://github.com/ranaroussi/quantstats/blob/main/.github/workflows/codeql-analysis.yml"
    click GitHubActions2 "https://github.com/ranaroussi/quantstats/blob/main/.github/workflows/python-publish.yml"
    click Travis "https://github.com/ranaroussi/quantstats/blob/main/.travis.yml"
    click SetupPy "https://github.com/ranaroussi/quantstats/blob/main/setup.py"
    click SetupCFG "https://github.com/ranaroussi/quantstats/blob/main/setup.cfg"
    click Manifest "https://github.com/ranaroussi/quantstats/blob/main/MANIFEST.in"
    click MetaYml "https://github.com/ranaroussi/quantstats/blob/main/meta.yaml"
    click README "https://github.com/ranaroussi/quantstats/blob/main/README.rst"
    click Changelog "https://github.com/ranaroussi/quantstats/blob/main/CHANGELOG.rst"

    %% Styles
    classDef core fill:#E8F1FA,stroke:#3182bd,stroke-width:1px
    classDef external fill:#F5E1A4,stroke:#b58900,stroke-width:1px
    classDef ci fill:#E4F7D4,stroke:#2f7f2f,stroke-width:1px
    classDef packaging fill:#F2D7D5,stroke:#a93226,stroke-width:1px
    classDef docs fill:#D7E3F2,stroke:#1f618d,stroke-width:1px
    classDef outputs fill:#FDEBD0,stroke:#b36b00,stroke-width:1px
```
