nautilus_model/data/
mod.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Data types for the trading domain model.
17
18pub mod bar;
19pub mod bet;
20pub mod close;
21pub mod delta;
22pub mod deltas;
23pub mod depth;
24pub mod funding;
25pub mod greeks;
26pub mod order;
27pub mod prices;
28pub mod quote;
29pub mod status;
30pub mod trade;
31
32#[cfg(any(test, feature = "stubs"))]
33pub mod stubs;
34
35use std::{
36    fmt::{Debug, Display},
37    hash::{Hash, Hasher},
38    str::FromStr,
39};
40
41use indexmap::IndexMap;
42use nautilus_core::UnixNanos;
43use serde::{Deserialize, Serialize};
44use serde_json::to_string;
45
46// Re-exports
47#[rustfmt::skip]  // Keep these grouped
48pub use bar::{Bar, BarSpecification, BarType};
49pub use close::InstrumentClose;
50pub use delta::OrderBookDelta;
51pub use deltas::{OrderBookDeltas, OrderBookDeltas_API};
52pub use depth::{DEPTH10_LEN, OrderBookDepth10};
53pub use funding::FundingRateUpdate;
54pub use greeks::{
55    BlackScholesGreeksResult, GreeksData, PortfolioGreeks, YieldCurveData, black_scholes_greeks,
56    imply_vol_and_greeks,
57};
58pub use order::{BookOrder, NULL_ORDER};
59pub use prices::{IndexPriceUpdate, MarkPriceUpdate};
60pub use quote::QuoteTick;
61pub use status::InstrumentStatus;
62pub use trade::TradeTick;
63
64use crate::identifiers::{InstrumentId, Venue};
65
66/// A built-in Nautilus data type.
67///
68/// Not recommended for storing large amounts of data, as the largest variant is significantly
69/// larger (10x) than the smallest.
70#[repr(C)]
71#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
72pub enum Data {
73    Delta(OrderBookDelta),
74    Deltas(OrderBookDeltas_API),
75    Depth10(Box<OrderBookDepth10>), // This variant is significantly larger
76    Quote(QuoteTick),
77    Trade(TradeTick),
78    Bar(Bar),
79    MarkPriceUpdate(MarkPriceUpdate), // TODO: Rename to MarkPrice once Cython gone
80    IndexPriceUpdate(IndexPriceUpdate), // TODO: Rename to IndexPrice once Cython gone
81    InstrumentClose(InstrumentClose),
82}
83
84macro_rules! impl_try_from_data {
85    ($variant:ident, $type:ty) => {
86        impl TryFrom<Data> for $type {
87            type Error = ();
88
89            fn try_from(value: Data) -> Result<Self, Self::Error> {
90                match value {
91                    Data::$variant(x) => Ok(x),
92                    _ => Err(()),
93                }
94            }
95        }
96    };
97}
98
99impl TryFrom<Data> for OrderBookDepth10 {
100    type Error = ();
101
102    fn try_from(value: Data) -> Result<Self, Self::Error> {
103        match value {
104            Data::Depth10(x) => Ok(*x),
105            _ => Err(()),
106        }
107    }
108}
109
110impl_try_from_data!(Quote, QuoteTick);
111impl_try_from_data!(Delta, OrderBookDelta);
112impl_try_from_data!(Deltas, OrderBookDeltas_API);
113impl_try_from_data!(Trade, TradeTick);
114impl_try_from_data!(Bar, Bar);
115impl_try_from_data!(MarkPriceUpdate, MarkPriceUpdate);
116impl_try_from_data!(IndexPriceUpdate, IndexPriceUpdate);
117impl_try_from_data!(InstrumentClose, InstrumentClose);
118
119/// Converts a vector of `Data` items to a specific variant type.
120///
121/// Filters and converts the data vector, keeping only items that can be
122/// successfully converted to the target type `T`.
123pub fn to_variant<T: TryFrom<Data>>(data: Vec<Data>) -> Vec<T> {
124    data.into_iter()
125        .filter_map(|d| T::try_from(d).ok())
126        .collect()
127}
128
129impl Data {
130    /// Returns the instrument ID for the data.
131    pub fn instrument_id(&self) -> InstrumentId {
132        match self {
133            Self::Delta(delta) => delta.instrument_id,
134            Self::Deltas(deltas) => deltas.instrument_id,
135            Self::Depth10(depth) => depth.instrument_id,
136            Self::Quote(quote) => quote.instrument_id,
137            Self::Trade(trade) => trade.instrument_id,
138            Self::Bar(bar) => bar.bar_type.instrument_id(),
139            Self::MarkPriceUpdate(mark_price) => mark_price.instrument_id,
140            Self::IndexPriceUpdate(index_price) => index_price.instrument_id,
141            Self::InstrumentClose(close) => close.instrument_id,
142        }
143    }
144
145    /// Returns whether the data is a type of order book data.
146    pub fn is_order_book_data(&self) -> bool {
147        matches!(self, Self::Delta(_) | Self::Deltas(_) | Self::Depth10(_))
148    }
149}
150
151/// Marker trait for types that carry a creation timestamp.
152///
153/// `ts_init` is the moment (UNIX nanoseconds) when this value was first generated or
154/// ingested by Nautilus. It can be used for sequencing, latency measurements,
155/// or monitoring data-pipeline delays.
156pub trait HasTsInit {
157    /// Returns the UNIX timestamp (nanoseconds) when the instance was created.
158    fn ts_init(&self) -> UnixNanos;
159}
160
161impl HasTsInit for Data {
162    fn ts_init(&self) -> UnixNanos {
163        match self {
164            Self::Delta(d) => d.ts_init,
165            Self::Deltas(d) => d.ts_init,
166            Self::Depth10(d) => d.ts_init,
167            Self::Quote(q) => q.ts_init,
168            Self::Trade(t) => t.ts_init,
169            Self::Bar(b) => b.ts_init,
170            Self::MarkPriceUpdate(p) => p.ts_init,
171            Self::IndexPriceUpdate(p) => p.ts_init,
172            Self::InstrumentClose(c) => c.ts_init,
173        }
174    }
175}
176
177/// Checks if the data slice is monotonically increasing by initialization timestamp.
178///
179/// Returns `true` if each element's `ts_init` is less than or equal to the next element's `ts_init`.
180pub fn is_monotonically_increasing_by_init<T: HasTsInit>(data: &[T]) -> bool {
181    data.windows(2)
182        .all(|window| window[0].ts_init() <= window[1].ts_init())
183}
184
185impl From<OrderBookDelta> for Data {
186    fn from(value: OrderBookDelta) -> Self {
187        Self::Delta(value)
188    }
189}
190
191impl From<OrderBookDeltas_API> for Data {
192    fn from(value: OrderBookDeltas_API) -> Self {
193        Self::Deltas(value)
194    }
195}
196
197impl From<OrderBookDepth10> for Data {
198    fn from(value: OrderBookDepth10) -> Self {
199        Self::Depth10(Box::new(value))
200    }
201}
202
203impl From<QuoteTick> for Data {
204    fn from(value: QuoteTick) -> Self {
205        Self::Quote(value)
206    }
207}
208
209impl From<TradeTick> for Data {
210    fn from(value: TradeTick) -> Self {
211        Self::Trade(value)
212    }
213}
214
215impl From<Bar> for Data {
216    fn from(value: Bar) -> Self {
217        Self::Bar(value)
218    }
219}
220
221impl From<MarkPriceUpdate> for Data {
222    fn from(value: MarkPriceUpdate) -> Self {
223        Self::MarkPriceUpdate(value)
224    }
225}
226
227impl From<IndexPriceUpdate> for Data {
228    fn from(value: IndexPriceUpdate) -> Self {
229        Self::IndexPriceUpdate(value)
230    }
231}
232
233impl From<InstrumentClose> for Data {
234    fn from(value: InstrumentClose) -> Self {
235        Self::InstrumentClose(value)
236    }
237}
238
239/// Represents a data type including metadata.
240#[derive(Clone, Serialize, Deserialize)]
241#[cfg_attr(
242    feature = "python",
243    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model")
244)]
245#[cfg_attr(
246    feature = "python",
247    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
248)]
249pub struct DataType {
250    type_name: String,
251    metadata: Option<IndexMap<String, String>>,
252    topic: String,
253    hash: u64,
254}
255
256impl DataType {
257    /// Creates a new [`DataType`] instance.
258    pub fn new(type_name: &str, metadata: Option<IndexMap<String, String>>) -> Self {
259        // Precompute topic
260        let topic = if let Some(ref meta) = metadata {
261            let meta_str = meta
262                .iter()
263                .map(|(k, v)| format!("{k}={v}"))
264                .collect::<Vec<_>>()
265                .join(".");
266            format!("{type_name}.{meta_str}")
267        } else {
268            type_name.to_string()
269        };
270
271        // Precompute hash
272        let mut hasher = std::collections::hash_map::DefaultHasher::new();
273        topic.hash(&mut hasher);
274
275        Self {
276            type_name: type_name.to_owned(),
277            metadata,
278            topic,
279            hash: hasher.finish(),
280        }
281    }
282
283    /// Returns the type name for the data type.
284    pub fn type_name(&self) -> &str {
285        self.type_name.as_str()
286    }
287
288    /// Returns the metadata for the data type.
289    pub fn metadata(&self) -> Option<&IndexMap<String, String>> {
290        self.metadata.as_ref()
291    }
292
293    /// Returns a string representation of the metadata.
294    pub fn metadata_str(&self) -> String {
295        self.metadata.as_ref().map_or_else(
296            || "null".to_string(),
297            |metadata| to_string(metadata).unwrap_or_default(),
298        )
299    }
300
301    /// Returns the messaging topic for the data type.
302    pub fn topic(&self) -> &str {
303        self.topic.as_str()
304    }
305
306    /// Returns an [`Option<InstrumentId>`] parsed from the metadata.
307    ///
308    /// # Panics
309    ///
310    /// This function panics if:
311    /// - There is no metadata.
312    /// - The `instrument_id` value contained in the metadata is invalid.
313    pub fn instrument_id(&self) -> Option<InstrumentId> {
314        let metadata = self.metadata.as_ref().expect("metadata was `None`");
315        let instrument_id = metadata.get("instrument_id")?;
316        Some(
317            InstrumentId::from_str(instrument_id)
318                .expect("Invalid `InstrumentId` for 'instrument_id'"),
319        )
320    }
321
322    /// Returns an [`Option<Venue>`] parsed from the metadata.
323    ///
324    /// # Panics
325    ///
326    /// This function panics if:
327    /// - There is no metadata.
328    /// - The `venue` value contained in the metadata is invalid.
329    pub fn venue(&self) -> Option<Venue> {
330        let metadata = self.metadata.as_ref().expect("metadata was `None`");
331        let venue_str = metadata.get("venue")?;
332        Some(Venue::from(venue_str.as_str()))
333    }
334
335    /// Returns an [`Option<UnixNanos>`] parsed from the metadata `start` field.
336    ///
337    /// # Panics
338    ///
339    /// This function panics if:
340    /// - There is no metadata.
341    /// - The `start` value contained in the metadata is invalid.
342    pub fn start(&self) -> Option<UnixNanos> {
343        let metadata = self.metadata.as_ref()?;
344        let start_str = metadata.get("start")?;
345        Some(UnixNanos::from_str(start_str).expect("Invalid `UnixNanos` for 'start'"))
346    }
347
348    /// Returns an [`Option<UnixNanos>`] parsed from the metadata `end` field.
349    ///
350    /// # Panics
351    ///
352    /// This function panics if:
353    /// - There is no metadata.
354    /// - The `end` value contained in the metadata is invalid.
355    pub fn end(&self) -> Option<UnixNanos> {
356        let metadata = self.metadata.as_ref()?;
357        let end_str = metadata.get("end")?;
358        Some(UnixNanos::from_str(end_str).expect("Invalid `UnixNanos` for 'end'"))
359    }
360
361    /// Returns an [`Option<usize>`] parsed from the metadata `limit` field.
362    ///
363    /// # Panics
364    ///
365    /// This function panics if:
366    /// - There is no metadata.
367    /// - The `limit` value contained in the metadata is invalid.
368    pub fn limit(&self) -> Option<usize> {
369        let metadata = self.metadata.as_ref()?;
370        let depth_str = metadata.get("limit")?;
371        Some(
372            depth_str
373                .parse::<usize>()
374                .expect("Invalid `usize` for 'limit'"),
375        )
376    }
377}
378
379impl PartialEq for DataType {
380    fn eq(&self, other: &Self) -> bool {
381        self.topic == other.topic
382    }
383}
384
385impl Eq for DataType {}
386
387impl PartialOrd for DataType {
388    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
389        Some(self.cmp(other))
390    }
391}
392
393impl Ord for DataType {
394    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
395        self.topic.cmp(&other.topic)
396    }
397}
398
399impl Hash for DataType {
400    fn hash<H: Hasher>(&self, state: &mut H) {
401        self.hash.hash(state);
402    }
403}
404
405impl Display for DataType {
406    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
407        write!(f, "{}", self.topic)
408    }
409}
410
411impl Debug for DataType {
412    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
413        write!(
414            f,
415            "DataType(type_name={}, metadata={:?})",
416            self.type_name, self.metadata
417        )
418    }
419}
420
421#[cfg(test)]
422mod tests {
423    use std::hash::DefaultHasher;
424
425    use rstest::*;
426
427    use super::*;
428
429    #[rstest]
430    fn test_data_type_creation_with_metadata() {
431        let metadata = Some(
432            [
433                ("key1".to_string(), "value1".to_string()),
434                ("key2".to_string(), "value2".to_string()),
435            ]
436            .iter()
437            .cloned()
438            .collect(),
439        );
440        let data_type = DataType::new("ExampleType", metadata.clone());
441
442        assert_eq!(data_type.type_name(), "ExampleType");
443        assert_eq!(data_type.topic(), "ExampleType.key1=value1.key2=value2");
444        assert_eq!(data_type.metadata(), metadata.as_ref());
445    }
446
447    #[rstest]
448    fn test_data_type_creation_without_metadata() {
449        let data_type = DataType::new("ExampleType", None);
450
451        assert_eq!(data_type.type_name(), "ExampleType");
452        assert_eq!(data_type.topic(), "ExampleType");
453        assert_eq!(data_type.metadata(), None);
454    }
455
456    #[rstest]
457    fn test_data_type_equality() {
458        let metadata1 = Some(
459            [("key1".to_string(), "value1".to_string())]
460                .iter()
461                .cloned()
462                .collect(),
463        );
464        let metadata2 = Some(
465            [("key1".to_string(), "value1".to_string())]
466                .iter()
467                .cloned()
468                .collect(),
469        );
470
471        let data_type1 = DataType::new("ExampleType", metadata1);
472        let data_type2 = DataType::new("ExampleType", metadata2);
473
474        assert_eq!(data_type1, data_type2);
475    }
476
477    #[rstest]
478    fn test_data_type_inequality() {
479        let metadata1 = Some(
480            [("key1".to_string(), "value1".to_string())]
481                .iter()
482                .cloned()
483                .collect(),
484        );
485        let metadata2 = Some(
486            [("key2".to_string(), "value2".to_string())]
487                .iter()
488                .cloned()
489                .collect(),
490        );
491
492        let data_type1 = DataType::new("ExampleType", metadata1);
493        let data_type2 = DataType::new("ExampleType", metadata2);
494
495        assert_ne!(data_type1, data_type2);
496    }
497
498    #[rstest]
499    fn test_data_type_ordering() {
500        let metadata1 = Some(
501            [("key1".to_string(), "value1".to_string())]
502                .iter()
503                .cloned()
504                .collect(),
505        );
506        let metadata2 = Some(
507            [("key2".to_string(), "value2".to_string())]
508                .iter()
509                .cloned()
510                .collect(),
511        );
512
513        let data_type1 = DataType::new("ExampleTypeA", metadata1);
514        let data_type2 = DataType::new("ExampleTypeB", metadata2);
515
516        assert!(data_type1 < data_type2);
517    }
518
519    #[rstest]
520    fn test_data_type_hash() {
521        let metadata = Some(
522            [("key1".to_string(), "value1".to_string())]
523                .iter()
524                .cloned()
525                .collect(),
526        );
527
528        let data_type1 = DataType::new("ExampleType", metadata.clone());
529        let data_type2 = DataType::new("ExampleType", metadata);
530
531        let mut hasher1 = DefaultHasher::new();
532        data_type1.hash(&mut hasher1);
533        let hash1 = hasher1.finish();
534
535        let mut hasher2 = DefaultHasher::new();
536        data_type2.hash(&mut hasher2);
537        let hash2 = hasher2.finish();
538
539        assert_eq!(hash1, hash2);
540    }
541
542    #[rstest]
543    fn test_data_type_display() {
544        let metadata = Some(
545            [("key1".to_string(), "value1".to_string())]
546                .iter()
547                .cloned()
548                .collect(),
549        );
550        let data_type = DataType::new("ExampleType", metadata);
551
552        assert_eq!(format!("{data_type}"), "ExampleType.key1=value1");
553    }
554
555    #[rstest]
556    fn test_data_type_debug() {
557        let metadata = Some(
558            [("key1".to_string(), "value1".to_string())]
559                .iter()
560                .cloned()
561                .collect(),
562        );
563        let data_type = DataType::new("ExampleType", metadata.clone());
564
565        assert_eq!(
566            format!("{data_type:?}"),
567            format!("DataType(type_name=ExampleType, metadata={metadata:?})")
568        );
569    }
570
571    #[rstest]
572    fn test_parse_instrument_id_from_metadata() {
573        let instrument_id_str = "MSFT.XNAS";
574        let metadata = Some(
575            [("instrument_id".to_string(), instrument_id_str.to_string())]
576                .iter()
577                .cloned()
578                .collect(),
579        );
580        let data_type = DataType::new("InstrumentAny", metadata);
581
582        assert_eq!(
583            data_type.instrument_id().unwrap(),
584            InstrumentId::from_str(instrument_id_str).unwrap()
585        );
586    }
587
588    #[rstest]
589    fn test_parse_venue_from_metadata() {
590        let venue_str = "BINANCE";
591        let metadata = Some(
592            [("venue".to_string(), venue_str.to_string())]
593                .iter()
594                .cloned()
595                .collect(),
596        );
597        let data_type = DataType::new(stringify!(InstrumentAny), metadata);
598
599        assert_eq!(data_type.venue().unwrap(), Venue::new(venue_str));
600    }
601
602    #[rstest]
603    fn test_parse_start_from_metadata() {
604        let start_ns = 1600054595844758000;
605        let metadata = Some(
606            [("start".to_string(), start_ns.to_string())]
607                .iter()
608                .cloned()
609                .collect(),
610        );
611        let data_type = DataType::new(stringify!(TradeTick), metadata);
612
613        assert_eq!(data_type.start().unwrap(), UnixNanos::from(start_ns),);
614    }
615
616    #[rstest]
617    fn test_parse_end_from_metadata() {
618        let end_ns = 1720954595844758000;
619        let metadata = Some(
620            [("end".to_string(), end_ns.to_string())]
621                .iter()
622                .cloned()
623                .collect(),
624        );
625        let data_type = DataType::new(stringify!(TradeTick), metadata);
626
627        assert_eq!(data_type.end().unwrap(), UnixNanos::from(end_ns),);
628    }
629
630    #[rstest]
631    fn test_parse_limit_from_metadata() {
632        let limit = 1000;
633        let metadata = Some(
634            [("limit".to_string(), limit.to_string())]
635                .iter()
636                .cloned()
637                .collect(),
638        );
639        let data_type = DataType::new(stringify!(TradeTick), metadata);
640
641        assert_eq!(data_type.limit().unwrap(), limit);
642    }
643}
nautilus_model/data/mod.rs

nautilus_model/data/
mod.rs
