# xingwudao/ferric-alpha architecture

> Architecture diagram of the GitHub repository xingwudao/ferric-alpha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xingwudao/ferric-alpha
- Repository: https://github.com/xingwudao/ferric-alpha

## Overview

Ferric Alpha is a Rust/Polars factor-analysis library with Rust and Python APIs and native tear-sheet rendering. The main workflow accepts long-form factor data, prepares and analyzes it, assembles serializable report data, then renders HTML, SVG, or PNG. Python plotting also offers an optional Matplotlib route. The graph reflects README capabilities and sampled API/rendering code; unsampled implementation wiring is shown only where documented, so some internal calls are intentionally omitted.

Main entry points: [`crates/ferric-alpha-py/src/lib.rs`](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-py/src/lib.rs) (PyO3 Bridge), [`python/ferric_alpha/tears.py`](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/tears.py) (Python API), [`python/ferric_alpha/plotting/_rendered.py`](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/_rendered.py) (Rendered Tear Sheet), [`crates/ferric-alpha/src/report/mod.rs`](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/mod.rs) (Tear-Sheet Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User APIs"]
  node_python_api["Python API<br/>[tears.py]"]
  node_validation["Input Validation<br/>[_validation.py]"]
  node_extension["PyO3 Bridge<br/>[lib.rs]"]
  node_performance_api["Performance API<br/>[performance.py]"]
end

subgraph group_prep["Factor Preparation"]
  node_factor_data["Factor Data<br/>[data.rs]"]
  node_cleaning["Data Cleaning<br/>[clean.rs]"]
  node_forward_returns["Forward Returns<br/>[forward_returns.rs]"]
  node_quantiles["Quantile Assignment<br/>[quantiles.rs]"]
end

subgraph group_analysis["Factor Analytics"]
  node_ic["Information Coefficient<br/>[ic.rs]"]
  node_quantile_metrics["Quantile Returns<br/>[quantiles.rs]"]
  node_portfolio["Portfolio Metrics<br/>[portfolio.rs]"]
  node_returns["Return Metrics<br/>[returns.rs]"]
  node_alpha_beta["Alpha and Beta<br/>[alpha_beta.rs]"]
  node_turnover["Turnover<br/>[turnover.rs]"]
  node_events["Event Studies<br/>[events.rs]"]
end

subgraph group_report["Reports and Rendering"]
  node_report_data["Tear-Sheet Data<br/>[mod.rs]"]
  node_report_context["Report Context<br/>[context.rs]"]
  node_serialization["Report Serialization<br/>[serialization.rs]"]
  node_plotting["Python Plotting<br/>[__init__.py]"]
  node_render_plan["Render Planning<br/>[mod.rs]"]
  node_charts["Chart Rendering"]
  node_html_backend["HTML Backend<br/>[html.rs]"]
  node_svg_backend["SVG Backend<br/>[svg.rs]"]
  node_png_backend["PNG Backend<br/>[png.rs]"]
  node_matplotlib["Matplotlib Backend<br/>[_matplotlib.py]"]
  node_rendered["Rendered Tear Sheet<br/>[_rendered.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits data"| node_python_api
node_python_api -->|"validates input"| node_validation
node_python_api -->|"calls API"| node_extension
node_performance_api -->|"calls metrics"| node_extension
node_extension -->|"validates frame"| node_factor_data
node_extension -->|"cleans data"| node_cleaning
node_extension -->|"computes returns"| node_forward_returns
node_extension -->|"assigns quantiles"| node_quantiles
node_extension -->|"computes IC"| node_ic
node_extension -->|"computes metrics"| node_quantile_metrics
node_extension -->|"computes portfolio"| node_portfolio
node_extension -->|"computes returns"| node_returns
node_extension -->|"computes alpha beta"| node_alpha_beta
node_extension -->|"computes turnover"| node_turnover
node_extension -->|"computes events"| node_events
node_python_api -->|"builds report"| node_extension
node_extension -->|"returns report data"| node_report_data
node_report_data -->|"prepares report"| node_report_context
node_report_data -->|"serializes report"| node_serialization
node_researcher -->|"requests rendering"| node_plotting
node_plotting -->|"requests native output"| node_extension
node_extension -->|"plans panels"| node_render_plan
node_render_plan -->|"dispatches panels"| node_charts
node_extension -->|"renders HTML"| node_html_backend
node_extension -->|"renders SVG"| node_svg_backend
node_extension -->|"renders PNG"| node_png_backend
node_plotting -.->|"selects backend"| node_matplotlib
node_html_backend -->|"returns output"| node_rendered
node_svg_backend -->|"returns output"| node_rendered
node_png_backend -->|"returns output"| node_rendered
node_matplotlib -.->|"returns figure"| node_rendered

click node_python_api "https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/tears.py"
click node_validation "https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/_validation.py"
click node_extension "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-py/src/lib.rs"
click node_factor_data "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/data.rs"
click node_cleaning "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/clean.rs"
click node_forward_returns "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/forward_returns.rs"
click node_quantiles "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/quantiles.rs"
click node_performance_api "https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/performance.py"
click node_ic "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/ic.rs"
click node_quantile_metrics "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/quantiles.rs"
click node_portfolio "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/portfolio.rs"
click node_returns "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/returns.rs"
click node_alpha_beta "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/alpha_beta.rs"
click node_turnover "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/turnover.rs"
click node_events "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/events.rs"
click node_report_data "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/mod.rs"
click node_report_context "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/context.rs"
click node_serialization "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/serialization.rs"
click node_plotting "https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/__init__.py"
click node_render_plan "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/plan/mod.rs"
click node_charts "https://github.com/xingwudao/ferric-alpha/tree/main/crates/ferric-alpha-render/src/charts"
click node_html_backend "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/backend/html.rs"
click node_svg_backend "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/backend/svg.rs"
click node_png_backend "https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/backend/png.rs"
click node_matplotlib "https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/_matplotlib.py"
click node_rendered "https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/_rendered.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_api,node_validation,node_extension,node_performance_api toneBlue
class node_factor_data,node_cleaning,node_forward_returns,node_quantiles toneAmber
class node_ic,node_quantile_metrics,node_portfolio,node_returns,node_alpha_beta,node_turnover,node_events toneMint
class node_report_data,node_report_context,node_serialization,node_plotting,node_render_plan,node_charts,node_html_backend,node_svg_backend,node_png_backend,node_matplotlib,node_rendered toneRose
class node_researcher toneIndigo
```

## Components

### User APIs

- [Python API](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/tears.py): `python/ferric_alpha/tears.py`
- [Input Validation](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/_validation.py): `python/ferric_alpha/_validation.py`
- [PyO3 Bridge](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-py/src/lib.rs): `crates/ferric-alpha-py/src/lib.rs`
- [Performance API](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/performance.py): `python/ferric_alpha/performance.py`

### Factor Preparation

- [Factor Data](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/data.rs): `crates/ferric-alpha/src/data.rs`
- [Data Cleaning](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/clean.rs): `crates/ferric-alpha/src/clean.rs`
- [Forward Returns](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/forward_returns.rs): `crates/ferric-alpha/src/forward_returns.rs`
- [Quantile Assignment](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/quantiles.rs): `crates/ferric-alpha/src/quantiles.rs`

### Factor Analytics

- [Information Coefficient](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/ic.rs): `crates/ferric-alpha/src/performance/ic.rs`
- [Quantile Returns](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/quantiles.rs): `crates/ferric-alpha/src/performance/quantiles.rs`
- [Portfolio Metrics](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/portfolio.rs): `crates/ferric-alpha/src/performance/portfolio.rs`
- [Return Metrics](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/returns.rs): `crates/ferric-alpha/src/performance/returns.rs`
- [Alpha and Beta](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/alpha_beta.rs): `crates/ferric-alpha/src/performance/alpha_beta.rs`
- [Turnover](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/turnover.rs): `crates/ferric-alpha/src/performance/turnover.rs`
- [Event Studies](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/performance/events.rs): `crates/ferric-alpha/src/performance/events.rs`

### Reports and Rendering

- [Tear-Sheet Data](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/mod.rs): `crates/ferric-alpha/src/report/mod.rs`
- [Report Context](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/context.rs): `crates/ferric-alpha/src/report/context.rs`
- [Report Serialization](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha/src/report/serialization.rs): `crates/ferric-alpha/src/report/serialization.rs`
- [Python Plotting](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/__init__.py): `python/ferric_alpha/plotting/__init__.py`
- [Render Planning](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/plan/mod.rs): `crates/ferric-alpha-render/src/plan/mod.rs`
- [Chart Rendering](https://github.com/xingwudao/ferric-alpha/tree/main/crates/ferric-alpha-render/src/charts): `crates/ferric-alpha-render/src/charts`
- [HTML Backend](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/backend/html.rs): `crates/ferric-alpha-render/src/backend/html.rs`
- [SVG Backend](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/backend/svg.rs): `crates/ferric-alpha-render/src/backend/svg.rs`
- [PNG Backend](https://github.com/xingwudao/ferric-alpha/blob/main/crates/ferric-alpha-render/src/backend/png.rs): `crates/ferric-alpha-render/src/backend/png.rs`
- [Matplotlib Backend](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/_matplotlib.py): `python/ferric_alpha/plotting/_matplotlib.py`
- [Rendered Tear Sheet](https://github.com/xingwudao/ferric-alpha/blob/main/python/ferric_alpha/plotting/_rendered.py): `python/ferric_alpha/plotting/_rendered.py`

### Other components

- **Researcher**

## Connections

- Researcher → Python API: submits data
- Python API → Input Validation: validates input
- Python API → PyO3 Bridge: calls API
- Performance API → PyO3 Bridge: calls metrics
- PyO3 Bridge → Factor Data: validates frame
- PyO3 Bridge → Data Cleaning: cleans data
- PyO3 Bridge → Forward Returns: computes returns
- PyO3 Bridge → Quantile Assignment: assigns quantiles
- PyO3 Bridge → Information Coefficient: computes IC
- PyO3 Bridge → Quantile Returns: computes metrics
- PyO3 Bridge → Portfolio Metrics: computes portfolio
- PyO3 Bridge → Return Metrics: computes returns
- PyO3 Bridge → Alpha and Beta: computes alpha beta
- PyO3 Bridge → Turnover: computes turnover
- PyO3 Bridge → Event Studies: computes events
- Python API → PyO3 Bridge: builds report
- PyO3 Bridge → Tear-Sheet Data: returns report data
- Tear-Sheet Data → Report Context: prepares report
- Tear-Sheet Data → Report Serialization: serializes report
- Researcher → Python Plotting: requests rendering
- Python Plotting → PyO3 Bridge: requests native output
- PyO3 Bridge → Render Planning: plans panels
- Render Planning → Chart Rendering: dispatches panels
- PyO3 Bridge → HTML Backend: renders HTML
- PyO3 Bridge → SVG Backend: renders SVG
- PyO3 Bridge → PNG Backend: renders PNG
- Python Plotting → Matplotlib Backend: selects backend
- HTML Backend → Rendered Tear Sheet: returns output
- SVG Backend → Rendered Tear Sheet: returns output
- PNG Backend → Rendered Tear Sheet: returns output
- Matplotlib Backend → Rendered Tear Sheet: returns figure