# quantopian/empyrical architecture

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

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

## Overview

##### Project type and purpose
- This is a Python library (“empyrical”) providing common financial risk and performance metrics (drawdown, alpha/beta, capture ratios, etc.).
- It’s intended for import as a dependency in other Python projects, not a standalone web or desktop application.

##### File structure
- Top-level packaging and configuration:
- setup.py, setup.cfg, versioneer.py – package metadata and version management
- MANIFEST.in, LICENSE – packaging and legal files
- .gitignore, .gitattributes, .travis.yml – VCS and CI configuration
- runtests.py – test harness
- Core source code directory: empyrical/
- __init__.py – package entry point (version import)
- _version.py – auto-generated version stub
- stats.py, perf_attrib.py, periods.py, deprecate.py – main algorithm modules
- utils.py – deprecated data-loading utilities
- Documentation: docs/ (Sphinx)
- Test suite: empyrical/tests/ with sample CSVs under test_data/

##### README for additional insights
- Dependencies: numpy, pandas (optional), nose, parameterized
- Features: simple and rolling measures, pandas support
- Deprecation notice: data‐reading utilities are deprecated

a. Main components
- Core Library Modules (empyrical package)
- External Dependencies (numpy, pandas)
- Test Suite
- Documentation Build
- Packaging & Release Tooling
b. Relationships and interactions
- Core modules import numpy (and pandas for Series support)
- perf_attrib, stats, periods call shared utility functions
- utils (deprecated) stand apart but still import pandas-datareader (indicate deprecation)
- tests import core modules and sample CSVs, run via runtests.py
- docs reference the core modules, built with Sphinx (docs/conf.py, Makefile)
- setup.py pulls in versioneer.py for version stamping; produces a PyPI artifact
c. Architectural patterns / design principles
- Modular decomposition by functionality (statistics vs performance attribution vs period calculations)
- Clear separation of concerns: core algorithms vs I/O utilities vs testing vs docs
- Deprecation path indicated in deprecate.py and utils.py
d. Key technologies & frameworks
- Python packaging: setuptools (setup.py), versioneer
- Testing: nose, parameterized
- Documentation: Sphinx (conf.py, Makefile)
- CI: Travis CI (.travis.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        NumPy(("numpy")):::external
        Pandas(("pandas")):::external
    end

    %% Core Library Modules
    subgraph "Core Library Modules"
        Entry["empyrical/__init__.py & empyrical/_version.py"]:::core
        Stats["empyrical.stats"]:::core
        Perf["empyrical.perf_attrib"]:::core
        Periods["empyrical.periods"]:::core
        DeprHelper["empyrical.deprecate (helpers)"]:::util
        Utils["empyrical.utils (deprecated)"]:::util
    end

    %% Packaging & Release
    subgraph "Packaging & Release"
        Setup["setup.py & setup.cfg"]:::packaging
        Manifest["MANIFEST.in"]:::packaging
        Versioneer["versioneer.py"]:::packaging
    end

    %% Test Suite
    subgraph "Test Suite"
        Runtests["runtests.py"]:::tests
        TestsDir["empyrical/tests/"]:::tests
    end

    %% Documentation (Sphinx)
    subgraph "Documentation (Sphinx)"
        DocsDir["docs/"]:::docs
    end

    %% CI & VCS
    subgraph "CI & VCS"
        Travis[".travis.yml"]:::ci
        GitIgnore[".gitignore & .gitattributes"]:::ci
    end

    %% Relationships
    Stats -->|imports| NumPy
    Perf -->|imports| NumPy
    Perf -->|optional pandas support| Pandas
    Stats -->|uses helpers| DeprHelper
    Perf -->|uses helpers| DeprHelper
    Periods -->|uses helpers| DeprHelper
    Utils -->|deprecated I/O| Pandas

    Entry -->|initializes package| Stats
    Entry -->|initializes package| Perf
    Entry -->|initializes package| Periods

    Setup -->|includes metadata| Entry
    Setup -->|includes manifest| Manifest
    Setup -->|uses versioneer| Versioneer

    Runtests -->|runs tests in| TestsDir
    TestsDir -->|tests modules| Stats
    TestsDir -->|tests modules| Perf
    TestsDir -->|tests modules| Periods
    TestsDir -->|tests deprecated utils| Utils
    TestsDir -->|tests deprecation helpers| DeprHelper

    DocsDir -->|references| Stats
    DocsDir -->|references| Perf
    DocsDir -->|references| Periods
    DocsDir -->|references| Utils
    DocsDir -->|builds with| Setup

    Travis -->|CI for| Runtests
    Travis -->|CI for| Setup
    GitIgnore -->|VCS config| Setup

    %% Click Events
    click Stats "https://github.com/quantopian/empyrical/blob/master/empyrical/stats.py"
    click Perf "https://github.com/quantopian/empyrical/blob/master/empyrical/perf_attrib.py"
    click Periods "https://github.com/quantopian/empyrical/blob/master/empyrical/periods.py"
    click Utils "https://github.com/quantopian/empyrical/blob/master/empyrical/utils.py"
    click DeprHelper "https://github.com/quantopian/empyrical/blob/master/empyrical/deprecate.py"
    click Entry "https://github.com/quantopian/empyrical/blob/master/empyrical/__init__.py"
    click Versioneer "https://github.com/quantopian/empyrical/blob/master/versioneer.py"
    click Setup "https://github.com/quantopian/empyrical/blob/master/setup.py"
    click Manifest "https://github.com/quantopian/empyrical/blob/master/MANIFEST.in"
    click Runtests "https://github.com/quantopian/empyrical/blob/master/runtests.py"
    click TestsDir "https://github.com/quantopian/empyrical/tree/master/empyrical/tests/"
    click DocsDir "https://github.com/quantopian/empyrical/tree/master/docs/"
    click Travis "https://github.com/quantopian/empyrical/blob/master/.travis.yml"
    click GitIgnore "https://github.com/quantopian/empyrical/blob/master/.gitignore"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef util fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef tests fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef docs fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef external fill:#FFF9C4,stroke:#FDD835,color:#F57F17
    classDef packaging fill:#CFD8DC,stroke:#546E7A,color:#263238
    classDef ci fill:#FFCDD2,stroke:#E53935,color:#B71C1C
```
