# skfolio/skfolio architecture

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

- Interactive diagram: https://gitdiagram.com/skfolio/skfolio
- Repository: https://github.com/skfolio/skfolio

## Overview

skfolio is a scikit-learn-compatible Python library for portfolio optimization, factor modeling, and risk management. Users supply asset-return or panel data, optionally transform or pre-select it, estimate priors and risk inputs, then fit optimizers and predict portfolios; model-selection tools validate and compare those workflows. Portfolio objects support downstream performance measurement and attribution. The README also documents distributions, uncertainty sets, synthetic stress scenarios, and factor-model capabilities, represented as subsystem nodes where source details were not sampled. Relationships among unsampled subsystems are intentionally omitted; documented capabilities are identified from the README.

Main entry points: [`src/skfolio/optimization/_base.py`](https://github.com/skfolio/skfolio/blob/main/src/skfolio/optimization/_base.py) (Optimizers), [`src/skfolio/portfolio/_portfolio.py`](https://github.com/skfolio/skfolio/blob/main/src/skfolio/portfolio/_portfolio.py) (Portfolio results), [`src/skfolio/containers/_asset_panel/_base.py`](https://github.com/skfolio/skfolio/blob/main/src/skfolio/containers/_asset_panel/_base.py) (Asset panel), [`src/skfolio/prior/_characteristics_factor_model.py`](https://github.com/skfolio/skfolio/blob/main/src/skfolio/prior/_characteristics_factor_model.py) (Factor model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and features"]
  node_asset_panel["Asset panel<br/>[_base.py]"]
  node_preprocessing["Return transforms"]
  node_preselection["Asset selection"]
  node_descriptors["Descriptors<br/>[_base.py]"]
end

subgraph group_estimation["Risk and priors"]
  node_factor_exposure["Factor exposures"]
  node_factor_model["Factor model"]
  node_priors["Prior estimators<br/>[_empirical.py]"]
  node_moments["Moment estimators"]
  node_distributions["Distributions"]
  node_uncertainty["Uncertainty sets"]
end

subgraph group_allocation["Portfolio allocation"]
  node_optimization["Optimizers<br/>[_base.py]"]
  node_convex["Convex methods<br/>[_base.py]"]
  node_hierarchical["Hierarchical methods"]
  node_portfolio["Portfolio results<br/>[_portfolio.py]"]
end

subgraph group_evaluation["Validation and analysis"]
  node_model_selection["Model selection<br/>[_validation.py]"]
  node_online_search["Online search<br/>[_search.py]"]
  node_measures["Risk measures<br/>[_measures.py]"]
  node_attribution["Factor attribution<br/>[_realized.py]"]
  node_alpha_eval["Forecast evaluation<br/>[_evaluation.py]"]
  node_results["Portfolio analysis<br/>[_population.py]"]
end

node_user(("Analyst"))
node_asset_data["Asset data"]

node_user -->|"provides returns"| node_asset_data
node_asset_data -.->|"organizes data"| node_asset_panel
node_asset_panel -.->|"transforms data"| node_preprocessing
node_asset_panel -.->|"selects assets"| node_preselection
node_asset_panel -.->|"computes features"| node_descriptors
node_descriptors -.->|"informs exposures"| node_factor_exposure
node_factor_exposure -->|"supplies exposures"| node_factor_model
node_factor_model -->|"uses factor prior"| node_priors
node_priors -.->|"estimates moments"| node_moments
node_priors -.->|"builds distributions"| node_distributions
node_uncertainty -.->|"constrains uncertainty"| node_optimization
node_priors -->|"provides prior"| node_optimization
node_optimization -->|"specializes"| node_convex
node_optimization -.->|"specializes"| node_hierarchical
node_optimization -->|"predicts portfolios"| node_portfolio
node_user -->|"validates models"| node_model_selection
node_model_selection -->|"fits estimators"| node_optimization
node_model_selection -->|"collects results"| node_portfolio
node_online_search -->|"uses validation"| node_model_selection
node_portfolio -->|"computes measures"| node_measures
node_portfolio -->|"supports attribution"| node_attribution
node_factor_model -.->|"enables factor analysis"| node_attribution
node_factor_model -.->|"evaluates forecasts"| node_alpha_eval
node_portfolio -->|"aggregates portfolios"| node_results
node_measures -.->|"scores portfolios"| node_results

click node_asset_panel "https://github.com/skfolio/skfolio/blob/main/src/skfolio/containers/_asset_panel/_base.py"
click node_preprocessing "https://github.com/skfolio/skfolio/tree/main/src/skfolio/preprocessing"
click node_preselection "https://github.com/skfolio/skfolio/tree/main/src/skfolio/pre_selection"
click node_descriptors "https://github.com/skfolio/skfolio/blob/main/src/skfolio/descriptor/_base.py"
click node_factor_exposure "https://github.com/skfolio/skfolio/tree/main/src/skfolio/factor_exposure"
click node_factor_model "https://github.com/skfolio/skfolio/blob/main/src/skfolio/prior/_characteristics_factor_model.py"
click node_priors "https://github.com/skfolio/skfolio/blob/main/src/skfolio/prior/_empirical.py"
click node_moments "https://github.com/skfolio/skfolio/tree/main/src/skfolio/moments"
click node_distributions "https://github.com/skfolio/skfolio/tree/main/src/skfolio/distribution"
click node_uncertainty "https://github.com/skfolio/skfolio/tree/main/src/skfolio/uncertainty_set"
click node_optimization "https://github.com/skfolio/skfolio/blob/main/src/skfolio/optimization/_base.py"
click node_convex "https://github.com/skfolio/skfolio/blob/main/src/skfolio/optimization/convex/_base.py"
click node_hierarchical "https://github.com/skfolio/skfolio/tree/main/src/skfolio/optimization/cluster/hierarchical"
click node_portfolio "https://github.com/skfolio/skfolio/blob/main/src/skfolio/portfolio/_portfolio.py"
click node_model_selection "https://github.com/skfolio/skfolio/blob/main/src/skfolio/model_selection/_validation.py"
click node_online_search "https://github.com/skfolio/skfolio/blob/main/src/skfolio/model_selection/_online/_search.py"
click node_measures "https://github.com/skfolio/skfolio/blob/main/src/skfolio/measures/_measures.py"
click node_attribution "https://github.com/skfolio/skfolio/blob/main/src/skfolio/attribution/_realized.py"
click node_alpha_eval "https://github.com/skfolio/skfolio/blob/main/src/skfolio/alpha/_evaluation.py"
click node_results "https://github.com/skfolio/skfolio/blob/main/src/skfolio/population/_population.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_asset_panel,node_preprocessing,node_preselection,node_descriptors toneBlue
class node_factor_exposure,node_factor_model,node_priors,node_moments,node_distributions,node_uncertainty toneAmber
class node_optimization,node_convex,node_hierarchical,node_portfolio toneMint
class node_model_selection,node_online_search,node_measures,node_attribution,node_alpha_eval,node_results toneRose
class node_user,node_asset_data toneIndigo
```

## Components

### Data and features

- [Asset panel](https://github.com/skfolio/skfolio/blob/main/src/skfolio/containers/_asset_panel/_base.py): `src/skfolio/containers/_asset_panel/_base.py`
- [Return transforms](https://github.com/skfolio/skfolio/tree/main/src/skfolio/preprocessing): `src/skfolio/preprocessing`
- [Asset selection](https://github.com/skfolio/skfolio/tree/main/src/skfolio/pre_selection): `src/skfolio/pre_selection`
- [Descriptors](https://github.com/skfolio/skfolio/blob/main/src/skfolio/descriptor/_base.py): `src/skfolio/descriptor/_base.py`

### Risk and priors

- [Factor exposures](https://github.com/skfolio/skfolio/tree/main/src/skfolio/factor_exposure): `src/skfolio/factor_exposure`
- [Factor model](https://github.com/skfolio/skfolio/blob/main/src/skfolio/prior/_characteristics_factor_model.py): `src/skfolio/prior/_characteristics_factor_model.py`
- [Prior estimators](https://github.com/skfolio/skfolio/blob/main/src/skfolio/prior/_empirical.py): `src/skfolio/prior/_empirical.py`
- [Moment estimators](https://github.com/skfolio/skfolio/tree/main/src/skfolio/moments): `src/skfolio/moments`
- [Distributions](https://github.com/skfolio/skfolio/tree/main/src/skfolio/distribution): `src/skfolio/distribution`
- [Uncertainty sets](https://github.com/skfolio/skfolio/tree/main/src/skfolio/uncertainty_set): `src/skfolio/uncertainty_set`

### Portfolio allocation

- [Optimizers](https://github.com/skfolio/skfolio/blob/main/src/skfolio/optimization/_base.py): `src/skfolio/optimization/_base.py`
- [Convex methods](https://github.com/skfolio/skfolio/blob/main/src/skfolio/optimization/convex/_base.py): `src/skfolio/optimization/convex/_base.py`
- [Hierarchical methods](https://github.com/skfolio/skfolio/tree/main/src/skfolio/optimization/cluster/hierarchical): `src/skfolio/optimization/cluster/hierarchical`
- [Portfolio results](https://github.com/skfolio/skfolio/blob/main/src/skfolio/portfolio/_portfolio.py): `src/skfolio/portfolio/_portfolio.py`

### Validation and analysis

- [Model selection](https://github.com/skfolio/skfolio/blob/main/src/skfolio/model_selection/_validation.py): `src/skfolio/model_selection/_validation.py`
- [Online search](https://github.com/skfolio/skfolio/blob/main/src/skfolio/model_selection/_online/_search.py): `src/skfolio/model_selection/_online/_search.py`
- [Risk measures](https://github.com/skfolio/skfolio/blob/main/src/skfolio/measures/_measures.py): `src/skfolio/measures/_measures.py`
- [Factor attribution](https://github.com/skfolio/skfolio/blob/main/src/skfolio/attribution/_realized.py): `src/skfolio/attribution/_realized.py`
- [Forecast evaluation](https://github.com/skfolio/skfolio/blob/main/src/skfolio/alpha/_evaluation.py): `src/skfolio/alpha/_evaluation.py`
- [Portfolio analysis](https://github.com/skfolio/skfolio/blob/main/src/skfolio/population/_population.py): `src/skfolio/population/_population.py`

### Other components

- **Analyst**
- **Asset data**

## Connections

- Analyst → Asset data: provides returns
- Asset data → Asset panel: organizes data
- Asset panel → Return transforms: transforms data
- Asset panel → Asset selection: selects assets
- Asset panel → Descriptors: computes features
- Descriptors → Factor exposures: informs exposures
- Factor exposures → Factor model: supplies exposures (evidence: `src/skfolio/prior/_characteristics_factor_model.py`)
- Factor model → Prior estimators: uses factor prior (evidence: `src/skfolio/prior/_characteristics_factor_model.py`)
- Prior estimators → Moment estimators: estimates moments
- Prior estimators → Distributions: builds distributions
- Uncertainty sets → Optimizers: constrains uncertainty
- Prior estimators → Optimizers: provides prior (evidence: `src/skfolio/optimization/_base.py`)
- Optimizers → Convex methods: specializes (evidence: `src/skfolio/optimization/convex/_base.py`)
- Optimizers → Hierarchical methods: specializes
- Optimizers → Portfolio results: predicts portfolios (evidence: `src/skfolio/optimization/_base.py`)
- Analyst → Model selection: validates models
- Model selection → Optimizers: fits estimators (evidence: `src/skfolio/model_selection/_validation.py`)
- Model selection → Portfolio results: collects results (evidence: `src/skfolio/model_selection/_validation.py`)
- Online search → Model selection: uses validation (evidence: `src/skfolio/model_selection/_online/_search.py`)
- Portfolio results → Risk measures: computes measures (evidence: `src/skfolio/portfolio/_portfolio.py`)
- Portfolio results → Factor attribution: supports attribution (evidence: `src/skfolio/portfolio/_portfolio.py`)
- Factor model → Factor attribution: enables factor analysis
- Factor model → Forecast evaluation: evaluates forecasts
- Portfolio results → Portfolio analysis: aggregates portfolios (evidence: `src/skfolio/population/_population.py`)
- Risk measures → Portfolio analysis: scores portfolios
