backtester/metrics/configs/portfolio_perf.py portfolio_perf.py:
The report metric map: section labels, result paths and formatter types.
This config file is the bridge between calculation output and the PDF/report surface. It defines what appears in the portfolio performance report, where each value is read from, and how it should be formatted.
Import
from backtester.metrics.configs.portfolio_perf import PORTFOLIO_PERF_METRICS When To Read This
- 01You want to add a metric to the PDF report without rewriting the report engine.
- 02You need to understand how compute_trade_analytics.net_profit becomes a table row.
- 03You are auditing which sections appear in the report packet.
File Anatomy
- Nested dictionary: top-level keys are report sections.
- Each row maps display label -> (dot path, formatter type).
- Dot paths traverse nested result dictionaries produced by engines and analysis modules.
- Formatter types keep calculation and presentation separated.
Data Contract
Inputs
- A nested result object produced by the performance/report pipeline.
- Dot paths such as compute_trade_analytics.net_profit or execution_context.config_hash.
- Formatter names such as percentage, ratio, currency0, bool, date and definition.
Outputs
- Report table sections for executive summary, risk, benchmark, trading, operations and reproducibility.
- A consistent mapping that PDF, console or JSON views can share.
- Human-readable labels that do not leak implementation names into the report.
Invariants
- Metric labels are presentation names; dot paths are internal result keys.
- Adding a metric requires the upstream calculation to populate the referenced path.
- Formatter type should match the semantic value, not only the numeric shape.
Public API And Key Internals
PORTFOLIO_PERF_METRICS
configPORTFOLIO_PERF_METRICS: dict[str, dict[str, tuple[str, str]]] Report metric registry grouped by section.
Returns
Nested dict consumed by report rendering code.
Executive Summary
config"CAGR": ("compute_annualized_return", "percentage") Top report rows shown first in review surfaces.
Trading Analytics
config"Total Round Trips": ("compute_trade_analytics.total_round_trips", "count") Round-trip and blotter-derived metrics sourced from RoundTripAnalyzer.summary().
Interesting Times
config"Crises Evaluated": ("compute_crisis_analysis.overlapping_count", "count") Crisis analysis fields sourced from compute_crisis_analysis().
Reproducibility
config"Fingerprint": ("execution_context.fingerprint", "text") Audit and reproducibility fields attached to the run context.
Implementation Notes
- This file is not calculation code, but it is critical architecture: it defines the public reporting contract.
- The metric map makes the report extensible because rows are declarative.
- The best implementation pattern is: add calculation -> expose result path -> add display row here -> verify report output.
Code Walkthrough
Read the report metric registry
Useful when building a custom report renderer or checking which upstream fields are required.
portfolio_perf_usage.py Python
from backtester.metrics.configs.portfolio_perf import PORTFOLIO_PERF_METRICS
for section, rows in PORTFOLIO_PERF_METRICS.items():
print(section)
for label, (path, formatter) in rows.items():
print(f" {label}: {path} [{formatter}]")Key implementation: executive and trading sections
Labels are report-facing; dot paths connect to calculation output.
backtester/metrics/configs/portfolio_perf.py Python
PORTFOLIO_PERF_METRICS = {
"Executive Summary": {
"CAGR": ("compute_annualized_return", "percentage"),
"Net Profit": ("compute_trade_analytics.net_profit", "currency0"),
"Sharpe Ratio": ("compute_advanced_sharpe_ratio.smart_sharpe", "ratio"),
"Max Drawdown": ("compute_max_drawdown", "percentage"),
},
"Trading Analytics": {
"Win Rate": ("compute_win_percentages.win_rate", "percentage"),
"Total Trades": ("compute_trade_analytics.total_trades", "count"),
"Total Round Trips": ("compute_trade_analytics.total_round_trips", "count"),
"Turnover (ann.)": ("compute_trade_analytics.annualized_turnover_pct", "percentage_raw"),
},
}Key implementation: crisis and reproducibility sections
This is where stress evidence and audit fields enter the same report table system.
backtester/metrics/configs/portfolio_perf.py Python
"Interesting Times": {
"Crises Evaluated": ("compute_crisis_analysis.overlapping_count", "count"),
"Crises Defined": ("compute_crisis_analysis.total_defined", "count"),
"Avg Crisis Return": ("compute_crisis_analysis.avg_crisis_return", "percentage"),
"Worst Crisis": ("compute_crisis_analysis.worst_crisis", "text"),
"Best Crisis": ("compute_crisis_analysis.best_crisis", "text"),
},
"Reproducibility": {
"Fingerprint": ("execution_context.fingerprint", "text"),
"Config Hash": ("execution_context.config_hash", "text"),
"Data Hash": ("execution_context.data_hash", "text"),
"Sanity Checks Passed": ("sanity_passed", "bool"),
}