atelier_quant 0.0.12

Quantitative Finance Tools & Models for the atelier-rs engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

//! Configuration schemas for inter-arrival model binaries.
//!
//! These structs are shared between `inter_fit` and `inter_serve`,
//! and can be reused by any downstream tool that needs to parse the
//! same TOML configuration format.

use serde::Deserialize;
use std::path::PathBuf;

// ── Top-level config ─────────────────────────────────────────────

/// Root configuration for the inter-arrival fitting pipeline.
#[derive(Debug, Deserialize)]
pub struct FitConfig {
    pub input: InputConfig,
    pub model: ModelConfig,
    pub output: OutputConfig,
    /// Forecast evaluation settings (optional — sensible defaults).
    #[serde(default)]
    pub forecast: ForecastConfig,
}

// ── Input ────────────────────────────────────────────────────────

/// Specifies where to find the input parquet data.
#[derive(Debug, Deserialize)]
pub struct InputConfig {
    /// Directory containing parquet files.
    pub path: PathBuf,
    /// `"trades"` or `"orderbook"`.
    pub data_type: String,
    /// `"latest"` or a specific filename.
    #[serde(default = "default_selection")]
    pub selection: String,
}

fn default_selection() -> String {
    "latest".into()
}

// ── Model ────────────────────────────────────────────────────────

/// MLE estimation hyperparameters and train/test split ratio.
#[derive(Debug, Deserialize)]
pub struct ModelConfig {
    #[serde(default = "default_max_iter")]
    pub max_iter: usize,
    #[serde(default = "default_tolerance")]
    pub tolerance: f64,
    #[serde(default = "default_learning_rate")]
    pub learning_rate: f64,
    /// Fraction of data used for training (remainder is test).
    #[serde(default = "default_train_ratio")]
    pub train_ratio: f64,
    /// Large-gap detection threshold in seconds.
    #[serde(default = "default_gap_threshold")]
    pub gap_threshold_secs: f64,
}

fn default_max_iter() -> usize {
    50_000
}
fn default_tolerance() -> f64 {
    1e3
}
fn default_learning_rate() -> f64 {
    1e-2
}
fn default_train_ratio() -> f64 {
    0.8
}
fn default_gap_threshold() -> f64 {
    5.0
}

// ── Output ───────────────────────────────────────────────────────

/// Where and how to write the model artifact.
#[derive(Debug, Deserialize)]
pub struct OutputConfig {
    /// Directory to write the model artifact into.
    pub artifact_dir: PathBuf,
    /// `"json"` (only supported format for now).
    #[serde(default = "default_format", rename = "format")]
    pub _format: String,
    /// Include diagnostics in the artifact.
    #[serde(default = "default_include_diag")]
    pub include_diagnostics: bool,
}

fn default_format() -> String {
    "json".into()
}
fn default_include_diag() -> bool {
    true
}

// ── Forecast ─────────────────────────────────────────────────────

/// Monte-Carlo ensemble forecast settings.
///
/// When `mc_paths > 1`, the forecast evaluation runs multiple
/// stochastic simulations and reduces each event-index column
/// with the chosen [`EnsembleStatistic`].
#[derive(Debug, Deserialize)]
pub struct ForecastConfig {
    /// Number of Monte Carlo paths.
    /// 1 = single stochastic run (backward-compatible default).
    #[serde(default = "default_mc_paths")]
    pub mc_paths: usize,
    /// Reduction statistic applied across the ensemble.
    #[serde(default)]
    pub mc_statistic: EnsembleStatistic,
}

impl Default for ForecastConfig {
    fn default() -> Self {
        Self {
            mc_paths: default_mc_paths(),
            mc_statistic: EnsembleStatistic::default(),
        }
    }
}

fn default_mc_paths() -> usize {
    1
}

/// Statistic used to reduce an ensemble of Monte-Carlo forecast
/// trajectories into a single consensus trajectory.
#[derive(Default, Debug, Clone, Copy, PartialEq, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum EnsembleStatistic {
    #[default]
    Median,
    Mean,
    P25,
    P75,
}