Implementation:HKUDS AI Trader Calculate Metrics

Knowledge Sources	AI-Trader
Domains	Quantitative_Finance, Performance_Analysis
Last Updated	2026-02-09 14:00 GMT

Overview

Concrete tool for computing financial performance metrics from portfolio value time series data.

Description

The calculate_metrics function takes a pandas DataFrame with a total_value column and computes a comprehensive set of financial metrics: CR, Annualized Return, Sharpe Ratio, Sortino Ratio, Volatility, Maximum Drawdown, Calmar Ratio, Win Rate, Average Win/Loss, and more. The annualization factor is configurable via periods_per_year (252 for daily US stocks, 252*6.5 for hourly, 365 for crypto).

Usage

Call after computing portfolio values via calculate_portfolio_values(). Used in both the single-agent results review step and the multi-agent comparison workflow.

Code Reference

Source Location

• Repository: AI-Trader
• File: tools/calculate_metrics.py
• Lines: L194-271

Signature

def calculate_metrics(portfolio_df, periods_per_year=252, risk_free_rate=0.0):
    """
    Calculate comprehensive financial performance metrics.

    Args:
        portfolio_df: DataFrame with 'total_value' column
        periods_per_year: Annualization factor (252=daily, 1638=hourly, 365=crypto)
        risk_free_rate: Risk-free rate for Sharpe/Sortino (default 0.0)

    Returns:
        dict with keys: CR, Annualized Return, SR, Sharpe Ratio, Vol, MDD,
              Calmar Ratio, Win Rate, Average Win, Average Loss,
              Initial Value, Final Value, Number of Trades, Date Range
    """

Import

from tools.calculate_metrics import calculate_metrics

I/O Contract

Inputs

Name	Type	Required	Description
portfolio_df	pd.DataFrame	Yes	Must contain 'total_value' column
periods_per_year	int	No	Annualization factor (default 252)
risk_free_rate	float	No	Risk-free rate (default 0.0)

Outputs

Name	Type	Description
metrics	dict	Comprehensive metrics dict with CR, SR, Sharpe, Vol, MDD, etc.

Usage Examples

Calculate After Backtest

from tools.calculate_metrics import calculate_metrics, calculate_portfolio_values, load_all_price_files
import json

# Load position data
with open("data/agent_data/gpt-4o/position/position.jsonl") as f:
    positions = [json.loads(line) for line in f]

# Load price data and compute portfolio values
price_data = load_all_price_files("data/")
portfolio_df = calculate_portfolio_values(positions, price_data)

# Calculate metrics
metrics = calculate_metrics(portfolio_df, periods_per_year=252)
print(f"Cumulative Return: {metrics['CR']:.2%}")
print(f"Sharpe Ratio: {metrics['Sharpe Ratio']:.4f}")
print(f"Max Drawdown: {metrics['MDD']:.2%}")

Related Pages

Requires Environment

• Environment:HKUDS_AI_Trader_Python_LangChain_Runtime

Uses Heuristic

• Heuristic:HKUDS_AI_Trader_Sortino_Ratio_Capping
• Heuristic:HKUDS_AI_Trader_Market_Type_Auto_Detection

Implements Principle

• Principle:HKUDS_AI_Trader_Portfolio_Metrics_Calculation