docs: multi series indicators and custom plotting

Author: williarin

.vitepress/config.mts

@@ -38,6 +38,8 @@ export default defineConfig({
         text: 'Indicator Customization',
         items: [
           { text: 'Creating a Custom Indicator', link: '/custom-indicator-basics' },
+          { text: 'Multi-Series Custom Indicators', link: '/custom-indicator-multi-series' },
+          { text: 'Plotting Custom Indicators', link: '/custom-indicator-plotting' },
         ]
       }
     ],

custom-indicator-multi-series.md

@@ -0,0 +1,62 @@
+# Multi-Series Custom Indicators
+
+Many powerful indicators are not just a single line on a chart, but a combination of multiple data series. A classic example is the MACD, which consists of the MACD line, a signal line, and a histogram.
+
+Stochastix allows your custom indicators to compute and expose multiple, distinct `Series` objects. This is achieved by using the `$this->resultSeries` property as an associative array.
+
+## The `$resultSeries` Property
+
+As we saw on the previous page, the final step in the `calculateBatch()` method is to store your calculated data in the `$this->resultSeries` property.
+
+This property is an associative array where:
+* **The key** is a `string` that uniquely identifies a specific data series (e.g., `'rsi'`, `'rsi_ma'`).
+* **The value** is the final, padded `Series` object for that data.
+
+By adding multiple key-value pairs to this array, your indicator effectively publishes multiple output series.
+
+## A Practical Example: `RSIMovingAverage`
+
+Let's revisit the `RSIMovingAverage` indicator we created. It naturally produces two distinct data series: the RSI line itself, and the moving average of that RSI line.
+
+In the `calculateBatch()` method, we stored them with unique keys:
+
+```php
+// In src/Indicator/RSIMovingAverage.php
+
+public function calculateBatch(Map $dataframes): void
+{
+    // ... (calculations for $rsiPadded and $maPadded)
+
+    // Store the final, padded data as Series objects.
+    // The keys used here are critical for accessing the data later.
+    $this->resultSeries['rsi'] = new Series($rsiPadded);
+    $this->resultSeries['rsi_ma'] = new Series($maPadded);
+}
+```
+
+## Accessing Multi-Value Series in a Strategy
+
+When you want to use this indicator in a strategy, you access each series by providing the specific key as the second argument to the `$this->getIndicatorSeries()` method.
+
+```php
+// In your strategy's onBar() method:
+
+// Get the indicator instance we defined earlier.
+$indicatorKey = 'my_custom_rsi';
+
+// To get the raw RSI line, we use the 'rsi' key.
+$rsiLine = $this->getIndicatorSeries($indicatorKey, 'rsi');
+
+// To get the moving average line, we use the 'rsi_ma' key.
+$rsiMaLine = $this->getIndicatorSeries($indicatorKey, 'rsi_ma');
+
+// Now we can use both series in our logic.
+if ($rsiLine->crossesOver($rsiMaLine)) {
+    // A bullish signal has occurred.
+    // ...
+}
+```
+
+::: warning Important
+If you do not provide the second argument to `$this->getIndicatorSeries()`, it will default to requesting a series with the key `'value'`. In the case of our `RSIMovingAverage` indicator, this would cause an error because we did not define a series with the key `'value'`. You must always use the explicit keys you defined in your indicator's `calculateBatch()` method.
+:::

custom-indicator-plotting.md

@@ -0,0 +1,80 @@
+# Plotting Custom Indicators
+
+Once you've created a custom indicator, you'll want to see it on the results chart to analyze its behavior. Stochastix provides a clean way for an indicator to define its own default plotting configuration. This makes your custom indicators reusable and easy to visualize without adding complex plotting logic to your strategies.
+
+This is achieved by implementing the `getPlotDefinition()` method in your indicator class.
+
+## The `getPlotDefinition()` Method
+
+By implementing this method from the `IndicatorInterface`, your custom indicator can return a `PlotDefinition` object that acts as a "template" for how it should be drawn on a chart.
+
+The backtesting framework can then use this template automatically whenever you add the indicator to a strategy.
+
+## Implementing the Plot for `RSIMovingAverage`
+
+Let's continue with our `RSIMovingAverage` example and implement its `getPlotDefinition()` method. We want to display the RSI and its moving average in a separate pane below the price chart, with horizontal lines at the 70 and 30 levels.
+
+```php
+// In src/Indicator/RSIMovingAverage.php
+
+use Stochastix\Domain\Plot\Annotation\HorizontalLine;
+use Stochastix\Domain\Plot\Enum\HorizontalLineStyleEnum;
+use Stochastix\Domain\Plot\PlotDefinition;
+use Stochastix\Domain\Plot\Series\Line;
+
+// ... inside the RSIMovingAverage class
+
+public function getPlotDefinition(): ?PlotDefinition
+{
+    return new PlotDefinition(
+        // This name is a default suggestion; it can be overridden by the strategy.
+        name: 'RSI / MA',
+        
+        // 'false' renders the plot in a separate pane below the price chart.
+        overlay: false,
+
+        // Define the data series to draw.
+        plots: [
+            // Draw a line using the data from the 'rsi' series key.
+            new Line(key: 'rsi', color: '#4e79a7'),
+            
+            // Draw a second line using data from the 'rsi_ma' series key.
+            new Line(key: 'rsi_ma', color: '#f28e2b'),
+        ],
+
+        // Define static annotations for the plot pane.
+        annotations: [
+            new HorizontalLine(value: 70, style: HorizontalLineStyleEnum::Dashed),
+            new HorizontalLine(value: 30, style: HorizontalLineStyleEnum::Dashed),
+        ]
+    );
+}
+```
+
+**Key Concepts from this step:**
+* **`plots` array**: We define one `Line` for each data series we stored in `$this->resultSeries`. The `key` in the `Line` constructor **must match** the key used in `calculateBatch()` (e.g., `'rsi'`, `'rsi_ma'`).
+* **`annotations` array**: We add static `HorizontalLine` components to provide context for the overbought (70) and oversold (30) RSI levels.
+* **`overlay: false`**: This is critical for oscillators like RSI, ensuring they get their own pane and don't get drawn on top of the price candles.
+
+## Using the Self-Plotting Indicator
+
+Now that our `RSIMovingAverage` indicator knows how to draw itself, using it in a strategy becomes incredibly simple.
+
+To activate the automatic plotting, you provide a third argument to the `$this->addIndicator()` method: the desired name for the plot in the chart legend. When this third argument is present, the framework automatically calls your indicator's `getPlotDefinition()` method and uses the template it provides.
+
+```php
+// In your strategy's defineIndicators() method:
+
+use App\Indicator\RSIMovingAverage;
+
+protected function defineIndicators(): void
+{
+    $this->addIndicator(
+        'my_rsi', // The key for the indicator instance
+        new RSIMovingAverage(rsiPeriod: 14, maPeriod: 9),
+        'RSI (14) with MA (9)' // This 3rd argument activates the plot!
+    );
+}
+```
+
+That's it! With this single line, you have added your custom indicator's logic to the backtest *and* configured it to be displayed beautifully on the results chart, with no plotting code needed in the strategy itself.