From 683f2eae0814c51b5fa17da775b029a475a1f7b5 Mon Sep 17 00:00:00 2001 From: Chris Sellers Date: Sat, 25 Jan 2025 09:42:08 +1100 Subject: [PATCH] Refine Actor and Strategy docs --- docs/concepts/{advanced => }/actors.md | 53 +++++++++++++------------- docs/concepts/advanced/index.md | 1 - docs/concepts/index.md | 7 +++- docs/concepts/strategies.md | 7 ++++ 4 files changed, 40 insertions(+), 28 deletions(-) rename docs/concepts/{advanced => }/actors.md (71%) diff --git a/docs/concepts/advanced/actors.md b/docs/concepts/actors.md similarity index 71% rename from docs/concepts/advanced/actors.md rename to docs/concepts/actors.md index 165d1f7919e8..a97ec10353a8 100644 --- a/docs/concepts/advanced/actors.md +++ b/docs/concepts/actors.md @@ -6,10 +6,9 @@ We are currently working on this guide. The `Actor` class provides the foundation for components that can interact with the trading system, including `Strategy` which inherits from it and additionally provides order management -methods on top. This means everything discussed in the [Strategies](../strategies.md) guide -also applies to actors. +methods on top. -## Basic Example +## Basic example Just like strategies, actors support configuration through very similar pattern. @@ -41,20 +40,22 @@ class MyActor(Actor): self.count_of_processed_bars += 1 ``` -## Data Handling and Callbacks +## Data handling and callbacks -When working with data in Nautilus, it's important to understand the relationship between data requests/subscriptions and their corresponding callback handlers. The system uses different handlers depending on whether the data is historical or real-time. +When working with data in Nautilus, it's important to understand the relationship between data +*requests/subscriptions* and their corresponding callback handlers. The system uses different handlers +depending on whether the data is historical or real-time. ### Historical vs Real-time Data The system distinguishes between two types of data flow: -1. **Historical Data** (from requests): +1. **Historical data** (from *requests*): - Obtained through methods like `request_bars()`, `request_quote_ticks()`, etc. - Processed through the `on_historical_data()` handler. - Used for initial data loading and historical analysis. -2. **Real-time Data** (from subscriptions): +2. **Real-time data** (from *subscriptions*): - Obtained through methods like `subscribe_bars()`, `subscribe_quote_ticks()`, etc. - Processed through specific handlers like `on_bar()`, `on_quote_tick()`, etc. - Used for live data processing. @@ -63,14 +64,14 @@ The system distinguishes between two types of data flow: Here's how different data operations map to their handlers: -| Operation | Method | Handler | Purpose | -|:----------|:---------|:---------|:----------| -| `request_bars()` | Historical request | `on_historical_data()` | Process historical bars | -| `subscribe_bars()` | Real-time subscription | `on_bar()` | Process live bar updates | -| `request_quote_ticks()` | Historical request | `on_historical_data()` | Process historical quotes | -| `subscribe_quote_ticks()` | Real-time subscription | `on_quote_tick()` | Process live quote updates | -| `request_trade_ticks()` | Historical request | `on_historical_data()` | Process historical trades | -| `subscribe_trade_ticks()` | Real-time subscription | `on_trade_tick()` | Process live trade updates | +| Operation | Method | Handler | Purpose | +|:--------------------------|:-----------------------|:-----------------------|:--------| +| `request_bars()` | Historical request | `on_historical_data()` | Process historical bars | +| `subscribe_bars()` | Real-time subscription | `on_bar()` | Process live bar updates | +| `request_quote_ticks()` | Historical request | `on_historical_data()` | Process historical quotes | +| `subscribe_quote_ticks()` | Real-time subscription | `on_quote_tick()` | Process live quote updates | +| `request_trade_ticks()` | Historical request | `on_historical_data()` | Process historical trades | +| `subscribe_trade_ticks()` | Real-time subscription | `on_trade_tick()` | Process live trade updates | ### Example @@ -85,7 +86,7 @@ from nautilus_trader.model.identifiers import ClientId, InstrumentId class MyActorConfig(ActorConfig): - instrument_id: InstrumentId # example value: "AAPL.NASDAQ" + instrument_id: InstrumentId # example value: "AAPL.NASDAQ" bar_type: BarType # example value: "AAPL.NASDAQ-1-MINUTE-LAST-EXTERNAL" @@ -99,20 +100,20 @@ class MyActor(Actor): self.request_bars( bar_type=self.bar_type, # Many optional parameters - start=None, # datetime, optional - end=None, # datetime, optional - callback=None, # custom handler function, optional - update_catalog=False, # bool, default False - params=None, # dict[str, Any], optional + start=None, # datetime, optional + end=None, # datetime, optional + callback=None, # custom handler function, optional + update_catalog=False, # bool, default False + params=None, # dict[str, Any], optional ) # Subscribe to real-time data - will be processed by on_bar() handler self.subscribe_bars( bar_type=self.bar_type, # Many optional parameters - client_id=None, # ClientId, optional - await_partial=False, # bool, default False - params=None, # dict[str, Any], optional + client_id=None, # ClientId, optional + await_partial=False, # bool, default False + params=None, # dict[str, Any], optional ) def on_historical_data(self, data: Data) -> None: @@ -125,8 +126,8 @@ class MyActor(Actor): self.log.info(f"Received real-time bar: {bar}") ``` -This separation between historical and real-time data handlers allows for different processing logic based on the data -context. For example, you might want to: +This separation between historical and real-time data handlers allows for different processing logic +based on the data context. For example, you might want to: - Use historical data to initialize indicators or establish baseline metrics. - Process real-time data differently for live trading decisions. diff --git a/docs/concepts/advanced/index.md b/docs/concepts/advanced/index.md index 2350515e0ecd..6a096c37eba4 100644 --- a/docs/concepts/advanced/index.md +++ b/docs/concepts/advanced/index.md @@ -12,7 +12,6 @@ highest to lowest level (although they are self-contained and can be read in any Explore more advanced concepts of NautilusTrader through these guides: -- [Actors](actors.md) - [Custom Data](custom_data.md) - [Advanced Orders](advanced_orders.md) - [Emulated Orders](emulated_orders.md) diff --git a/docs/concepts/index.md b/docs/concepts/index.md index fc96011a4f92..bd9b8392c4fc 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -12,9 +12,14 @@ The architecture guide dives deep into the foundational principles, structures, the platform. Whether you're a developer, system architect, or just curious about the inner workings of NautilusTrader. +## [Actors](actors.md) + +`Actor`s provide the foundation for user-defined components that can interact with the trading system. +The **Actors** guide covers capabilities and implementation specifics. + ## [Strategies](strategies.md) -The heart of the NautilusTrader user experience is in writing and working with +`Strategy` is at the heart of the NautilusTrader user experience when writing and working with trading strategies. The **Strategies** guide covers how to implement trading strategies for the platform. ## [Instruments](instruments.md) diff --git a/docs/concepts/strategies.md b/docs/concepts/strategies.md index d7a7ae0e2350..17f4dae4eaca 100644 --- a/docs/concepts/strategies.md +++ b/docs/concepts/strategies.md @@ -4,6 +4,13 @@ The heart of the NautilusTrader user experience is in writing and working with trading strategies. Defining a trading strategy is achieved by inheriting the `Strategy` class, and implementing the methods required by the users trading strategy logic. +`Strategy` inherits from `Actor` and additionally provides order management functionality. + +:::note +Everything discussed in the [Actors](actors.md) guide also applies to strategies, and should +be read first. +::: + Strategies can be added to Nautilus systems with any [environment context](/concepts/architecture.md#environment-contexts) and will start sending commands and receiving events based on their logic as soon as the system starts.