Folioframe

Folioframe turns user-provided Pandas return or equity series into structured portfolio analytics and a modern, interactive, self-contained HTML report. It supports English and Simplified Chinese, one or many strategies, and zero, one or many benchmarks.

Open the interactive English demo · Open the Simplified Chinese demo · Browse the demo source

What you get

• Performance, risk, drawdown, distribution, tail-risk and data-quality metrics for every series.
• Strategy-versus-benchmark metrics for every pair, with a selector when multiple benchmarks exist.
• Interactive equity, drawdown and weekly/monthly/quarterly/yearly return comparisons.
• Consistent comparison tables: series in rows, metrics in columns, best values emphasized.
• Optional IC/RankIC, sample, model, recorded-cost and turnover diagnostics.
• Offline Plotly charts, light/dark themes and a single portable HTML file.
• Strict inputs: no downloads, silent filling, implicit alignment or inferred return/equity type.

Install

Install the latest release from PyPI:

python -m pip install folioframe

To test the current unreleased main branch instead:

python -m pip install "folioframe @ git+https://github.com/xystudio-ai/folioframe.git"

For local development:

git clone https://github.com/xystudio-ai/folioframe.git
cd folioframe
python -m pip install -e ".[dev]"

Quick start

import pandas as pd

from folioframe import report

strategies = pd.DataFrame(
    {"My strategy": strategy_returns},
    index=pd.DatetimeIndex(dates),
)
benchmarks = pd.DataFrame(
    {"Market benchmark": benchmark_returns},
    index=strategies.index,
)

analysis = report(
    strategies,
    benchmarks,
    input_kind="returns",
    periods_per_year=252,
    risk_free_rate=0.02,
    primary_benchmark="Market benchmark",
    output="report.html",
    language="en",  # or "zh-CN"
)

print(analysis.metrics)

DataFrame column names are the report labels. Use input_kind="returns" for simple period returns or input_kind="equity" for positive equity/NAV levels. All series must share the same increasing, unique DatetimeIndex; Folioframe fails clearly instead of repairing inputs silently.

periods_per_year and risk_free_rate default to None. Metrics that need a missing assumption are marked unavailable instead of assuming 252 observations or a zero risk-free rate. See the metric definitions.

Three public workflows

MachineLearningDiagnostics and TradingDiagnostics are independent optional inputs. If an object or field is omitted, its report section is omitted too. They display supplied research facts without training a model or rerunning a backtest. See optional diagnostics.

Reproduce the demo

The repository includes an authorized, anonymized research sample with two strategy views, two benchmarks, a 2% risk-free assumption, IC/RankIC, recorded cost, turnover and sample diagnostics. Names and machine-specific identifiers have been removed.

python examples/generate_reports.py

This writes both languages to examples/output/. The two canonical reports are also versioned in docs/demo, so visitors can inspect the result before installing anything.

Project structure

src/folioframe/
  _core.py          input validation and portfolio calculations
  _diagnostics.py   optional research and trading diagnostics
  _render.py        the single HTML/Plotly renderer
examples/
  data/              anonymous demo inputs
  generate_reports.py
docs/
  demo/              canonical bilingual HTML reports
tests/               numerical, rendering and real-browser checks

The library owns generic formulas and rendering. Calling frameworks only translate their own verified evidence into Pandas objects; no caller-specific report logic belongs in Folioframe.

Development

python -m pip install -e ".[dev,browser,release]"
python -m playwright install chromium
ruff check .
python -m pytest
python -m build
python -m twine check dist/*

Tests are offline and deterministic. Contributions that change a public formula must include a numerical regression test, metric-documentation update and changelog entry. See CONTRIBUTING.md.

License

Folioframe is source-available under CC BY-NC 4.0. Sharing and adaptation are allowed with attribution; commercial use requires separate permission. This non-commercial license is not an OSI-approved open-source license.