Zipfolio

Backtest tearsheets that read the book, not just the returns.

▶ Open a live report  ·  The same backtest in QuantStats

QuantStats tells you what the equity curve did. Zipfolio tells you why it did it, and whether you could have traded it: which positions made the money, which ones made each drawdown, which factors the strategy was really riding, whether its fills were possible at all, and what costs took. It is one self-contained HTML page with interactive charts that also works on a phone, and it checks its own arithmetic before you read it.

Quick start

pip install -U "zipfolio[all]"

import pandas as pd
from zipfolio import build_tearsheet

returns = pd.read_csv("returns.csv", index_col=0, parse_dates=True).squeeze()  # one return per day
build_tearsheet("report.html", returns)

To see a full report without any data of your own, run the example. It builds a report from a real ziplime backtest (three years, 147 fills) and opens it in your browser:

curl -sO https://raw.githubusercontent.com/Limex-com/zipfolio/main/examples/quickstart.py
python quickstart.py

Give it more, get more

Only returns is required. Each input you add turns on the sections that need it:

build_tearsheet(
    "report.html", returns, benchmark,
    position_records=positions,   # date, symbol, quantity, last_sale_price: one row per open position per day
    cash=cash,                    # cash at the end of each day
    transactions=fills,           # dt, symbol, quantity, price: one row per fill
    sector_mappings={"AAPL": "Information Technology", "JPM": "Financials"},
)

The frames are plain pandas, so any backtester that can export positions and fills gets the same report. For a ziplime run, zipfolio.ziplime reads the rest out of its market-data bundle: see Zipfolio and ziplime.

Zipfolio and QuantStats

QuantStats sees one number per day. A drawdown, a Sharpe ratio or a monthly heatmap can be computed from that. Nothing in that number says whether a fill was possible, what slippage cost, or which position carried the risk. Zipfolio reads the book the returns came from:

The last row is deliberate. Zipfolio covers what a return series cannot show and leaves return analytics to QuantStats. ZipLime builds both reports for every backtest. To compare them, open the same backtest in QuantStats and in Zipfolio.

What only the book can show

These panels come from the US momentum example. It rotates monthly into the top 3 of 10 US large caps, with $1m, from October 2023 to October 2026.

Could it have been traded? The backtest fills each order at the close of the bar that produced the signal. Zipfolio fills the same 147 trades at the next bar's open instead. The total return falls from 140% to 122% and the Sharpe ratio from 1.47 to 1.31: waiting one bar costs $186k. QuantStats never sees a fill, so it cannot run this check.

Where did the capital go, and what did it make? In the treemap, each tile is one name inside its sector, sized by the capital it took and coloured by what it added to the return.

Who made each drawdown? Each of the five worst drawdowns is split across the names that made it. The split is exact, to the percentage point.

What is it really exposed to? The style box places the strategy by its Fama-French betas and traces its rolling path. The efficient frontier of the names it held shows what a fixed mix would have done. The frontier uses hindsight, so the page labels it as a ceiling.

Interactive, and readable on a phone

Every chart is live. Hover a chart to read the values, click a legend entry to hide a series, and zoom with the slider. Any chart opens full screen and saves as PNG, JPG or SVG. Each table has a copy button for Excel or Google Sheets. A term such as CVaR, Treynor or M² explains itself on hover. Copy report for an AI puts the page's numbers on the clipboard as Markdown, so you can discuss the strategy with any assistant. The page loads nothing from the network: ECharts is inlined, and interactive=False gives static SVG instead.

On a phone, each chart redraws for the width it gets, and the scorecard turns into cards.

What is in a report

The summary comes first: the main issues in one sentence, the facts at a glance, a score and 16 checks, four per part. The checks are the same for every backtest. Open a check to see its reasoning, its threshold and what to try. The sections follow in four parts, each answering one question:

A section that cannot be computed becomes a short note. The page fails only if it can report nothing at all. The reference lists what each section contains and when it appears.

The numbers are checked before you read them. zipfolio.integrity replays the book from the opening state, independently of the report: every fill, fee, cash movement and position. It then checks every profit figure the page publishes against that replay. The panel at the top of the page shows the result, and the same check runs from a shell or in CI:

# book.pkl: a pickle of AccountingInputs fields
python -m zipfolio.integrity book.pkl --mode ci --json accounting_integrity.json

Any market

US stocks get Fama-French factors by default. For any other market, use a market model against your own benchmark and risk-free rate:

build_tearsheet("report.html", returns, dax.rename("DAX"), ...,
                factor_model="market", risk_free=estr.rename("€STR"),
                currency="EUR", market_timezone="Europe/Berlin",
                sector_mappings={"SAP": "Information Technology", "ALV": "Financials"})

Inputs

All inputs are plain pandas. Only returns is required.

build_tearsheet returns the titles of the sections that made it into the page, in page order.

Installation

pip install zipfolio              # the core report
pip install "zipfolio[risk]"      # + skfolio: Portfolio Risk and the efficient frontier
pip install "zipfolio[ziplime]"   # + polars: zipfolio.ziplime, the bundle readers
pip install "zipfolio[all]"       # everything

Python 3.10+. Without skfolio the Portfolio Risk section and the efficient frontier are left out, and nothing else changes. To install the latest unreleased code: pip install "zipfolio[all] @ git+https://github.com/Limex-com/zipfolio".

Network: the page itself makes no requests. The library downloads Fama-French factors from Kenneth French's data library and caches them for a week. If the download fails, the library falls back to the cache, and failing that the report shows a note. GICS sectors are not shipped, because MSCI and S&P license the classification: bring your own table, or pass any {symbol: sector}. Details are in Data the package fetches or ships.

Limitations

• Futures exposure is understated: positions are valued at quantity × price, with no contract multiplier.
• Slippage is reconstructed for the fixed-basis-point model only.
• Factor analysis needs at least 60 sessions inside the factor data, which is published monthly with a lag.
• The efficient frontier uses the returns the names went on to make. It is hindsight and long only.

More

• The reference: every section and check, the accounting integrity check, how Zipfolio uses pyfolio, the ziplime integration, the release process.
• CHANGELOG.md
• Development: pip install -e ".[all]" pytest && pytest. The tests never touch the network.

License

Apache License 2.0. See LICENSE. Zipfolio builds on pyfolio-reloaded (Apache-2.0), skfolio (BSD-3-Clause) and Apache ECharts (Apache-2.0, inlined in every page). No market or classification data ships with it. Zipfolio is part of the ZipLime ecosystem.