# Using pyfolio for Portfolio Risk Analytics and Tear Sheets: A Complete Guide

> Master portfolio risk analytics with pyfolio. This guide shows you how to generate professional tear sheets visualizing performance, drawdown, risk metrics, and factor exposures.

- Repository: [Papers With Backtest/awesome-systematic-trading](https://github.com/paperswithbacktest/awesome-systematic-trading)
- Tags: how-to-guide
- Published: 2026-08-01

---

**`pyfolio` is a Python library that transforms raw backtest returns into professional tear sheets visualizing cumulative performance, drawdown periods, risk-adjusted metrics, and factor exposures.**

The `paperswithbacktest/awesome-systematic-trading` repository recognizes `pyfolio` as an essential tool for systematic strategy evaluation, listing it in the curated resources table of [`README.md`](https://github.com/paperswithbacktest/awesome-systematic-trading/blob/main/README.md). While the repository does not maintain its own fork of the library, it provides numerous static strategy scripts in `static/strategies/` that generate the exact pandas data structures `pyfolio` requires for risk analysis.

## What is pyfolio?

**`pyfolio`** is an open-source Python library designed for portfolio performance and risk analytics. It consumes time-series data—specifically **returns** as a `pandas.Series` and optional **positions** as a `pandas.DataFrame`—to compute a comprehensive set of financial metrics. The library automatically generates a **tear sheet**, a single-page HTML or PDF report containing interactive visualizations of cumulative returns, drawdown analysis, rolling Sharpe ratios, and sector exposures.

## Architecture and Workflow

`pyfolio` operates as the analytics layer in a three-stage pipeline. According to the repository structure in `paperswithbacktest/awesome-systematic-trading`, you can feed outputs from any backtest engine directly into `pyfolio` without data transformation.

### Data Ingestion

Your backtest engine—whether custom code or third-party libraries—must produce a daily or weekly time-series of portfolio returns. The `static/strategies/` folder contains example scripts that output precisely this format, typically as CSV files with date-indexed return columns.

### Risk Analytics Engine

`pyfolio` computes statistics such as maximum drawdown, volatility, beta, and alpha. These calculations happen internally when you invoke the tear sheet creation functions.

### Tear Sheet Generation

The final stage renders multiple matplotlib visualizations into a cohesive report. The entry point `pyfolio.create_returns_tear_sheet` orchestrates this process, accepting your returns series and optional benchmark data.

## Implementing pyfolio with Strategy Backtests

To integrate `pyfolio` with strategies from the repository, load your backtest results and pass them to the tear sheet generator. The following example assumes you have executed a strategy from `static/strategies/` and saved the returns to CSV.

```python
import pandas as pd
import pyfolio as pf
import matplotlib.pyplot as plt

# Load daily returns from a backtested strategy

returns = pd.read_csv('data/strategy_returns.csv',
                      parse_dates=['date'],
                      index_col='date')['return']

# Optional: Load position data for exposure analysis

# positions = pd.read_csv('data/positions.csv', 

#                        parse_dates=['date'], 

#                        index_col='date')

# Generate the full tear sheet

pf.create_returns_tear_sheet(
    returns,
    benchmark_rets=None,   # Add benchmark series here for comparison

    live_start_date=None,  # Date when strategy went live (for out-of-sample analysis)

    # pos=positions        # Uncomment if providing position data

)
plt.show()

```

This workflow applies to any strategy notebook in `static/strategies/` that outputs a time-indexed return series.

## Understanding Tear Sheet Components

The tear sheet produced by `pyfolio.create_returns_tear_sheet` contains several analytical sections:

- **Cumulative Returns**: Tracks portfolio growth over time versus a benchmark.
- **Drawdown Analysis**: Identifies peak-to-trough declines and recovery periods, critical for setting stop-loss levels.
- **Rolling Sharpe Ratio**: Displays risk-adjusted returns over a moving window to detect regime changes.
- **Monthly Returns Heatmap**: Reveals seasonal patterns and calendar effects in strategy performance.
- **Factor Exposure**: When position data is provided via the `pos` parameter, shows concentration risks across sectors or asset classes.

## Integration with the Awesome Systematic Trading Repository

The `paperswithbacktest/awesome-systematic-trading` repository references `pyfolio` in specific locations:

- **[`README.md`](https://github.com/paperswithbacktest/awesome-systematic-trading/blob/main/README.md)** (line 197): Lists `pyfolio` as a recommended resource for portfolio risk analytics.
- **[`README_zh.md`](https://github.com/paperswithbacktest/awesome-systematic-trading/blob/main/README_zh.md)** (line 187): Contains the Chinese translation of the same resource entry.
- **`static/strategies/`**: Directory containing strategy implementations that generate compatible return series.
- **[`opencode.json`](https://github.com/paperswithbacktest/awesome-systematic-trading/blob/main/opencode.json)**: Repository metadata file supporting the project's tooling infrastructure.

To use `pyfolio` with this repository, select any strategy from `static/strategies/`, capture its return output, and process it through the tear sheet function demonstrated above.

## Summary

- **`pyfolio`** generates institutional-grade risk reports from simple pandas Series objects.
- The **`create_returns_tear_sheet`** function requires only a returns time-series, with optional benchmark and position data.
- The **`paperswithbacktest/awesome-systematic-trading`** repository catalogs `pyfolio` as a core analytics tool and provides strategy templates in `static/strategies/` that feed directly into it.
- Tear sheets visualize cumulative returns, drawdowns, rolling Sharpe ratios, and factor exposures in a single comprehensive view.

## Frequently Asked Questions

### What data format does pyfolio require for analysis?

`pyfolio` requires a `pandas.Series` of percentage returns indexed by datetime. The series should contain daily or weekly portfolio returns, not cumulative values. If you want exposure analysis, you must also provide a `pandas.DataFrame` of positions indexed by date with ticker weights or dollar amounts.

### Can I use pyfolio without providing position data?

Yes. The `pos` parameter in `create_returns_tear_sheet` is optional. Without position data, `pyfolio` will generate all performance and risk metrics except for factor exposure and sector concentration plots. The core functionality—returns analysis, drawdown calculation, and Sharpe ratio computation—requires only the returns series.

### How do I integrate pyfolio with existing backtests in the repository?

Execute any script in `static/strategies/` to generate a CSV of daily returns, then load that file into a pandas Series. Pass this series to `pyfolio.create_returns_tear_sheet`. Because `pyfolio` operates independently of the backtest engine, no modifications to the original strategy code are necessary—only standardization of the output format to a datetime-indexed return series.

### What is the difference between a tear sheet and a standard backtest report?

A **tear sheet** is a condensed, single-page visualization designed for rapid risk assessment, whereas standard backtest reports often contain tabular trade logs and granular statistics. `pyfolio` tear sheets focus on visual analytics—drawdown charts, rolling metrics, and heatmaps—making them ideal for presentations and high-level strategy comparison, while traditional reports prioritize transactional detail.