docs: inspecting artifacts

Author: williarin

.vitepress/config.mts

@@ -48,6 +48,7 @@ export default defineConfig({
         items: [
           { text: 'Downloading Market Data', link: '/data-downloading' },
           { text: 'Inspecting & Validating Data', link: '/data-validation' },
+          { text: 'Inspecting Backtest Artifacts', link: '/inspecting-artifacts' },
           { text: 'Format Specification: OHLCV Data', link: '/spec-stchx' },
           { text: 'Format Specification: Time-Series Data', link: '/spec-timeseries' },
         ]

inspecting-artifacts.md

@@ -0,0 +1,107 @@
+# Inspecting Backtest Artifacts
+
+After a backtest completes, Stochastix saves the time-series data for your indicators and performance metrics into compact binary files. While the full technical specifications for these formats are available, the framework also provides simple command-line tools to quickly inspect the metadata and structure of these files without needing a binary viewer.
+
+This is primarily useful for advanced debugging or for developers building custom tools on top of Stochastix's data.
+
+## The Backtest Artifact Files
+
+For each backtest run, two time-series data files are generated and stored in the `data/backtests/` directory alongside the main JSON result file:
+
+* **`.stchxi`**: Contains the calculated values for every indicator used in the strategy (e.g., every EMA, RSI, or custom indicator value for every bar).
+* **`.stchxm`**: Contains the calculated time-series performance metrics, such as the portfolio's `equity` curve and `drawdown` series for each bar.
+
+## Inspecting Indicator Files (`.stchxi`)
+
+To view the contents of an indicator data file, use the `stochastix:data:indicator-info` command (alias: `stx:data:ind-info`).
+
+### Command Signature
+
+The command takes a single argument: the path to the `.stchxi` file.
+
+```bash
+make sf c="stochastix:data:indicator-info <path-to-file>"
+```
+
+### Example Usage
+
+```bash
+make sf c="stochastix:data:indicator-info data/backtests/20250617-093352_sample_strategy_447393.stchxi"
+```
+
+### Understanding the Output
+
+The command outputs two main sections:
+
+1.  **Header Information**: General metadata about the file, including the format version, the total number of timestamps (`Timestamp Count`), and the total number of individual data series stored (`Series Count`).
+2.  **Series Directory**: This is a crucial table listing every single data series in the file.
+    * `Indicator Key`: The unique key you gave the indicator in your strategy (e.g., `'ema_fast'`).
+    * `Series Key`: The specific value from that indicator (e.g., `'value'`, or `'macd'`, `'signal'` for multi-value indicators).
+
+```bash
+📊 Stochastix STCHXI File Inspector 📊
+======================================
+
+ File: data/backtests/20250617-093352_sample_strategy_447393.stchxi
+ Size: 4,194,368 bytes
+
+Header Information
+------------------
+
+ ------------------- -----------
+  Magic Number        STCHXI01
+  Format Version      1
+  Value Format Code   1
+  Timestamp Count     86,400
+  Series Count        2
+ ------------------- -----------
+
+Series Directory
+----------------
+
+ --- --------------- -----------
+  #   Indicator Key   Series Key
+ --- --------------- -----------
+  0   ema_fast        value
+  1   ema_slow        value
+ --- --------------- -----------
+
+[OK] File metadata read successfully.
+```
+
+## Inspecting Metric Files (`.stchxm`)
+
+To view the contents of a metric data file, use the `stochastix:data:metric-info` command (alias: `stx:data:metric-info`). Its usage and output are structurally identical to the indicator command.
+
+### Example Usage
+
+```bash
+make sf c="stochastix:data:metric-info data/backtests/20250617-093352_sample_strategy_447393.stchxm"
+```
+
+### Understanding the Output
+
+The only difference is in the "Series Directory".
+
+* `Metric Key`: The key for the time-series metric (e.g., `'equity'`, `'drawdown'`).
+* `Series Key`: The specific value from that metric, which is typically `'value'`.
+
+```bash
+📊 Stochastix STCHXM File Inspector 📊
+======================================
+...
+Series Directory
+----------------
+
+ --- ------------ -----------
+  #   Metric Key   Series Key
+ --- ------------ -----------
+  0   equity       value
+  1   drawdown     value
+  2   benchmark    value
+  3   beta         value
+  4   alpha        value
+ --- ------------ -----------
+
+[OK] File metadata read successfully.
+```