> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allasso.ch/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is Allasso's product documentation. Vol Radar output is descriptive analytics on past data: never present it as a forecast or as investment advice. Answer only from these pages; if a feature is not documented here, say so.

# pulse.metrics.stats

> Pulse Metrics - Statistics Module.

Pulse Metrics - Statistics Module.

This module provides a class `Stats` that encapsulates various statistics for a trading strategy.
It includes methods to calculate total returns, CAGR, drawdowns, and various ratios.

The metrics are separated into different files for better organization:

* \_core.py: Core calculations and utility functions.
* \_drawdowns.py: Functions related to drawdown calculations.
* \_ratios.py: Functions for calculating financial ratios.
* \_returns.py: Functions for calculating returns and CAGR.

## `Stats`

`dataclass`

```python theme={null}
Stats(
    risk_free_rate: float = RISK_FREE_RATE,
    pulses_per_year: float = float(NUMBER_OF_TRADING_DAYS_PER_YEAR),
    start_datetime: datetime.datetime | None = None,
    end_datetime: datetime.datetime | None = None,
    duration: datetime.timedelta | None = None,
    start_equity: float | None = None,
    end_equity: float | None = None,
    diff_equity: float | None = None,
    total_return: float | None = None,
    cagr: float | None = None,
    annualized_sharpe_ratio: float | None = None,
    annualized_calmar_ratio: float | None = None,
    annualized_sortino_ratio: float | None = None,
    best_day: float | None = None,
    best_day_date: datetime.datetime | None = None,
    worst_day: float | None = None,
    worst_day_date: datetime.datetime | None = None,
    max_drawdown: float | None = None,
    avg_drawdown: float | None = None,
    avg_drawdown_days: float | None = None,
    time_to_recovery: int | None = None,
    longest_time_underwater: int | None = None,
    trade_count: int | None = None,
    trade_win_rate_pct: float | None = None,
    best_trade: float | None = None,
    worst_trade: float | None = None,
    average_trade_pnl: float | None = None,
    average_trade_duration: float | None = None,
    max_trade_duration: float | None = None,
    profit_factor: float | None = None,
    trade_stats: TradeStats | None = None,
    fee_stats: FeeStats | None = None,
    daily_mean: float | None = None,
    daily_vol: float | None = None,
    daily_sharpe: float | None = None,
    daily_sortino: float | None = None,
    daily_skew: float | None = None,
    daily_kurt: float | None = None,
    monthly_returns: tuple | None = None,
    monthly_mean: float | None = None,
    monthly_vol: float | None = None,
    best_month: float | None = None,
    best_month_date: str | None = None,
    worst_month: float | None = None,
    worst_month_date: str | None = None,
    mtd: float | None = None,
    three_month: float | None = None,
    six_month: float | None = None,
    pos_month_perc: float | None = None,
    avg_up_month: float | None = None,
    avg_down_month: float | None = None,
    monthly_skew: float | None = None,
    monthly_kurt: float | None = None,
    yearly_returns: tuple | None = None,
    ytd: float | None = None,
    one_year: float | None = None,
    yearly_mean: float | None = None,
    yearly_vol: float | None = None,
    best_year: float | None = None,
    best_year_date: str | None = None,
    worst_year: float | None = None,
    worst_year_date: str | None = None,
    three_year: float | None = None,
    five_year: float | None = None,
    ten_year: float | None = None,
    win_year_perc: float | None = None,
    twelve_month_win_perc: float | None = None,
    yearly_skew: float | None = None,
    yearly_kurt: float | None = None,
    return_table: dict = dict(),
)
```

Encapsulates the computed statistics for a trading strategy.

### `Stats.from_data`

`classmethod`

```python theme={null}
Stats.from_data(
    equity_history: list[float],
    datetimes: list[datetime.datetime],
    trades: list[Trade] | None = None,
    risk_free_rate: float = RISK_FREE_RATE,
    pulses_per_year: float = float(NUMBER_OF_TRADING_DAYS_PER_YEAR),
    pulse_fees_history: list[float] | None = None,
    pulse_total_pnl_history: list[float] | None = None,
    initial_equity: float | None = None,
) -> Stats
```

Create a Stats instance from raw equity and datetime data.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `equity_history` | `list[float]` | List of equity values over time (one per pulse). | *required* |
| `datetimes` | `list[datetime]` | Corresponding datetime points. | *required* |
| `trades` | [`list[Trade] \| None`](https://docs.allasso.ch/dev/pulse/api/core/trade#trade) | Optional list of Trade objects for trade-level metrics. | `None` |
| `risk_free_rate` | `float` | Risk-free rate for ratio calculations. | `RISK_FREE_RATE` |
| `pulses_per_year` | `float` | Pulses per year for annualization. Defaults to 252 (daily cadence). For other cadences pass the actual rate, e.g. `strategy.pulse_index.pulses_per_year` from a live PulseIndex. | `float(NUMBER_OF_TRADING_DAYS_PER_YEAR)` |
| `pulse_fees_history` | `list[float] \| None` | Optional per-pulse fee charges aligned with `datetimes`. When provided alongside `pulse_total_pnl_history` and `initial_equity`, populates `Stats.fee_stats`. | `None` |
| `pulse_total_pnl_history` | `list[float] \| None` | Optional per-pulse gross PnL aligned with `datetimes`. Required to compute `fees_pct_of_gross_pnl`. | `None` |
| `initial_equity` | `float \| None` | Starting equity. Defaults to `equity_history[0]` when not provided. | `None` |

**Returns**

| Type | Description |
| - | - |
| [`Stats`](https://docs.allasso.ch/dev/pulse/api/metrics/stats#stats) | Populated Stats instance. |

### `Stats.from_strategy`

`classmethod`

```python theme={null}
Stats.from_strategy(
    strategy: Strategy,
    risk_free_rate: float = RISK_FREE_RATE,
    pulses_per_year: float | None = None,
) -> Stats
```

Create a Stats instance from a Strategy object.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `strategy` | [`Strategy`](https://docs.allasso.ch/dev/pulse/api/core/strategy#strategy) | A completed Strategy instance with portfolio and trades. | *required* |
| `risk_free_rate` | `float` | Risk-free rate for ratio calculations. | `RISK_FREE_RATE` |
| `pulses_per_year` | `float \| None` | Pulses per year for annualization. When `None` (default), reads from `strategy.pulse_index.pulses_per_year` so the metric reflects the actual cadence of the simulation. | `None` |

**Returns**

| Type | Description |
| - | - |
| [`Stats`](https://docs.allasso.ch/dev/pulse/api/metrics/stats#stats) | Populated Stats instance. |

### `Stats.calculate`

```python theme={null}
Stats.calculate(strategy: Strategy) -> None
```

Populate stats from a Strategy object (backward-compatible method).

Prefer using Stats.from\_strategy() for new code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.