docs: performance metrics

Author: williarin

.vitepress/config.mts

@@ -47,6 +47,7 @@ export default defineConfig({
         items: [
           { text: 'Running a Backtest', link: '/running-backtests' },
           { text: 'Understanding the Results', link: '/understanding-results' },
+          { text: 'Performance Metrics', link: '/performance-metrics' },
         ]
       }
     ],

performance-metrics.md

@@ -0,0 +1,48 @@
+
+# Performance Metrics
+
+A backtest is more than just its final profit or loss. To truly understand a strategy's strengths, weaknesses, and risk profile, you need to analyze a variety of statistical metrics. Stochastix calculates a suite of institutional-grade metrics for every backtest.
+
+This page serves as a glossary for the key metrics found in the `summaryMetrics` object of the results file and displayed in the CLI summary.
+
+## Overall Performance & Profitability
+
+These metrics give you a high-level view of the strategy's profitability.
+
+* **Total Net Profit / %**: The most basic metric. It shows the absolute profit/loss in your account's currency and its percentage relative to your initial capital.
+* **Profit Factor**: This is the gross profit (sum of all winning trades) divided by the gross loss (sum of all losing trades).
+    * **Interpretation**: A value greater than 1.0 indicates a profitable strategy. A value of 2.0 means you made twice as much on your winners as you lost on your losers. A value below 1.0 indicates a net-losing strategy.
+* **CAGR (Compound Annual Growth Rate)**: The year-over-year growth rate of your portfolio over the backtest period.
+    * **Interpretation**: This normalizes the return, allowing you to compare strategies that were run over different time periods (e.g., a 6-month test vs. a 3-year test).
+* **Expectancy**: The average amount you can expect to win (or lose) per trade. It's calculated as `(Win Rate * Average Win) - (Loss Rate * Average Loss)`.
+    * **Interpretation**: A positive expectancy means that, on average, your strategy is profitable over time.
+
+## Risk-Adjusted Return Metrics
+
+These metrics measure how much return your strategy generated for the amount of risk it took. A strategy with high returns but extreme volatility may be less desirable than a strategy with moderate returns and low volatility.
+
+* **Sharpe Ratio**: A measure of return compared to its volatility. It's the average return earned in excess of a risk-free rate, divided by the standard deviation of the returns.
+    * **Interpretation**: The higher the Sharpe Ratio, the better the risk-adjusted return. A value > 1.0 is often considered good.
+* **Sortino Ratio**: A variation of the Sharpe Ratio that only penalizes for "bad" volatility. It divides the excess return by the standard deviation of *only the negative returns* (downside deviation).
+    * **Interpretation**: Many consider this a better measure of risk, as it doesn't penalize a strategy for having large positive returns. A higher value is better.
+* **Calmar Ratio**: The Compound Annual Growth Rate (CAGR) divided by the Maximum Drawdown.
+    * **Interpretation**: This metric directly answers the question: "How much annual return am I getting for the worst loss I would have had to endure?". A higher value is better.
+* **Max Drawdown (%)**: The largest peak-to-trough decline in portfolio value during the backtest, expressed as a percentage.
+    * **Interpretation**: This is a critical measure of risk. It represents the worst-case loss from a single high point and gives you an idea of the potential pain of holding through the strategy's worst period.
+
+## Market-Relative Metrics
+
+These metrics evaluate your strategy's performance in relation to the underlying market's movement (i.e., a simple "buy and hold" of the asset).
+
+* **Beta**: Measures the volatility of your strategy's returns relative to the market.
+    * **Interpretation**: A Beta of 1.0 means your portfolio moves in line with the market. > 1.0 means it's more volatile than the market. < 1.0 means it's less volatile. A negative Beta would mean it tends to move opposite to the market.
+* **Alpha**: Represents the "edge" or excess return of your strategy that is not explained by the market's movement (as measured by Beta). It is the return generated by the strategy's unique logic.
+    * **Interpretation**: A positive Alpha is the ultimate goal of any strategy, as it indicates you are outperforming the market on a risk-adjusted basis.
+
+## Trade-Specific Statistics
+
+These metrics provide insight into the character and behavior of the trades themselves.
+
+* **Total Trades**: The total number of closed trades executed.
+* **Max Consecutive Wins / Losses**: The longest streak of winning or losing trades in a row. This is useful for understanding the psychological pressure the strategy might create.
+* **Avg Duration (Winners/Losers)**: The average time a winning or losing trade was held open. This can help you see if your strategy successfully "cuts its losers short and lets its winners run."