Skip to main content

ferric_alpha_render/plan/
mod.rs

1mod catalog;
2mod layout;
3
4use std::collections::{HashMap, HashSet};
5
6use ferric_alpha::{ReportKind, ReportTable, TearSheetData};
7use serde::{Deserialize, Serialize};
8
9use crate::{
10    MAX_LOGICAL_HEIGHT, MAX_PANELS, MAX_WIDTH, MIN_WIDTH, RENDER_PLAN_VERSION, RenderError,
11    RenderResult,
12};
13use crate::{RenderOptions, RenderTheme};
14
15pub use catalog::plan_report;
16
17#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
18pub struct RenderPlan {
19    pub contract_version: String,
20    pub report_kind: ReportKind,
21    pub title: String,
22    pub width: u32,
23    pub height: u32,
24    pub theme: RenderTheme,
25    pub panels: Vec<PanelPlan>,
26}
27
28#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
29pub struct PanelPlan {
30    pub id: String,
31    pub title: String,
32    pub row: u32,
33    pub column: u8,
34    pub column_span: u8,
35    pub height: u32,
36    pub table_ids: Vec<String>,
37    pub kind: PanelKind,
38}
39
40#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
41#[serde(tag = "type", rename_all = "snake_case")]
42pub enum PanelKind {
43    Table,
44    QuantileReturnsBar { by_group: bool },
45    QuantileReturnsDistribution { samples: u32 },
46    CumulativeReturns { by_quantile: bool },
47    MeanSpread,
48    IcTimeSeries,
49    IcHistogram { bins: u32 },
50    IcQq,
51    IcMonthlyHeatmap,
52    IcByGroup,
53    QuantileTurnover { period: String },
54    RankAutocorrelation { period: String },
55    EventDistribution,
56    EventAverageCumulative { by_group: bool },
57}
58
59impl RenderPlan {
60    pub fn new(
61        report_kind: ReportKind,
62        title: impl Into<String>,
63        options: &RenderOptions,
64        panels: Vec<PanelPlan>,
65    ) -> RenderResult<Self> {
66        validate_plan_options(options)?;
67        let panels = layout::assign_layout(options.width, panels)?;
68        let height = layout::total_height(&panels)?;
69        Ok(Self {
70            contract_version: RENDER_PLAN_VERSION.to_string(),
71            report_kind,
72            title: title.into(),
73            width: options.width,
74            height,
75            theme: options.theme,
76            panels,
77        })
78    }
79
80    pub fn to_json(&self) -> RenderResult<String> {
81        serde_json::to_string(self).map_err(|error| RenderError::Backend {
82            format: "render-plan",
83            message: error.to_string(),
84        })
85    }
86
87    pub fn validate(&self, report: &TearSheetData) -> RenderResult<()> {
88        if self.contract_version != RENDER_PLAN_VERSION {
89            return invalid_contract("invalid render-plan contract version");
90        }
91        if self.report_kind != report.metadata().report_kind() {
92            return invalid_contract("report kind mismatch");
93        }
94        if self.panels.len() > MAX_PANELS || self.height > MAX_LOGICAL_HEIGHT {
95            return Err(RenderError::LayoutOverflow);
96        }
97
98        let table_map = report
99            .table_ids()
100            .into_iter()
101            .filter_map(|id| report.table(id).map(|table| (id, table)))
102            .collect::<HashMap<_, _>>();
103        let mut seen_ids = HashSet::with_capacity(self.panels.len());
104        let mut rows = HashMap::<u32, Vec<&PanelPlan>>::new();
105
106        for panel in &self.panels {
107            if panel.id.is_empty() || !seen_ids.insert(panel.id.as_str()) {
108                return invalid_contract("duplicate panel id");
109            }
110            if panel.column != 0 && panel.column != 6 {
111                return invalid_contract("invalid panel column");
112            }
113            if panel.column_span != 6 && panel.column_span != 12 {
114                return invalid_contract("invalid panel span");
115            }
116            if panel.column + panel.column_span > 12 {
117                return invalid_contract("panel row overflow");
118            }
119            if panel.table_ids.is_empty() {
120                return invalid_contract("panel has no table ids");
121            }
122            for table_id in &panel.table_ids {
123                let table = table_map.get(table_id.as_str()).copied().ok_or_else(|| {
124                    RenderError::MissingTable {
125                        id: table_id.clone(),
126                    }
127                })?;
128                validate_panel_table(panel, table)?;
129            }
130            rows.entry(panel.row).or_default().push(panel);
131        }
132
133        let max_row = rows.keys().copied().max().unwrap_or(0);
134        for row in 0..=max_row {
135            let panels = rows.get(&row).ok_or_else(|| RenderError::InvalidContract {
136                reason: "missing layout row".to_string(),
137            })?;
138            let first_height = panels[0].height;
139            if panels.iter().any(|panel| panel.height != first_height) {
140                return invalid_contract("unequal panel heights in row");
141            }
142            for (index, left) in panels.iter().enumerate() {
143                for right in panels.iter().skip(index + 1) {
144                    let left_end = left.column + left.column_span;
145                    let right_end = right.column + right.column_span;
146                    if left.column < right_end && right.column < left_end {
147                        return invalid_contract("panel row overlap");
148                    }
149                }
150            }
151        }
152
153        Ok(())
154    }
155}
156
157pub(crate) fn panel(
158    id: impl Into<String>,
159    title: impl Into<String>,
160    column_span: u8,
161    height: u32,
162    table_ids: Vec<&str>,
163    kind: PanelKind,
164) -> PanelPlan {
165    PanelPlan {
166        id: id.into(),
167        title: title.into(),
168        row: 0,
169        column: 0,
170        column_span,
171        height,
172        table_ids: table_ids.into_iter().map(ToOwned::to_owned).collect(),
173        kind,
174    }
175}
176
177fn validate_panel_table(panel: &PanelPlan, table: &ReportTable) -> RenderResult<()> {
178    if table.columns().is_empty() {
179        return invalid_contract("table panel has no columns");
180    }
181    match &panel.kind {
182        PanelKind::Table => Ok(()),
183        PanelKind::QuantileReturnsBar { by_group } => {
184            require_columns(table, &["factor_quantile", "period", "mean_return"])?;
185            if *by_group {
186                require_columns(table, &["group"])?;
187            }
188            Ok(())
189        }
190        PanelKind::QuantileReturnsDistribution { .. } => {
191            require_columns(table, &["date", "factor_quantile", "period", "mean_return"])
192        }
193        PanelKind::CumulativeReturns { by_quantile } => {
194            let mut columns = vec!["date"];
195            if *by_quantile {
196                columns.push("factor_quantile");
197            }
198            columns.push("cumulative_return");
199            require_columns(table, &columns)
200        }
201        PanelKind::MeanSpread => {
202            require_columns(table, &["date", "period", "mean_return_difference"])
203        }
204        PanelKind::IcTimeSeries => require_columns(table, &["period"]),
205        PanelKind::IcHistogram { .. } => require_columns(table, &["period", "ic"]),
206        PanelKind::IcQq => require_columns(table, &["period", "theoretical", "observed"]),
207        PanelKind::IcMonthlyHeatmap => {
208            require_columns(table, &["time_bucket", "period", "mean_ic"])
209        }
210        PanelKind::IcByGroup => require_columns(table, &["group", "period", "mean_ic"]),
211        PanelKind::QuantileTurnover { .. } => {
212            require_columns(table, &["date", "factor_quantile", "period", "turnover"])
213        }
214        PanelKind::RankAutocorrelation { .. } => {
215            require_columns(table, &["date", "period", "autocorrelation"])
216        }
217        PanelKind::EventDistribution => require_columns(table, &["bin_start", "bin_end"]),
218        PanelKind::EventAverageCumulative { by_group } => {
219            let mut columns = vec!["factor_quantile", "offset", "mean_cumulative_return"];
220            if *by_group {
221                columns.push("group");
222            }
223            require_columns(table, &columns)
224        }
225    }
226}
227
228fn require_columns(table: &ReportTable, columns: &[&str]) -> RenderResult<()> {
229    let available = table.column_names();
230    for column in columns {
231        if !available.contains(column) {
232            return Err(RenderError::MissingColumn {
233                table: table.id().to_string(),
234                column: (*column).to_string(),
235            });
236        }
237    }
238    Ok(())
239}
240
241fn invalid_contract<T>(reason: &str) -> RenderResult<T> {
242    Err(RenderError::InvalidContract {
243        reason: reason.to_string(),
244    })
245}
246
247fn validate_plan_options(options: &RenderOptions) -> RenderResult<()> {
248    if !(MIN_WIDTH..=MAX_WIDTH).contains(&options.width) {
249        return Err(RenderError::InvalidOption {
250            option: "width",
251            reason: "must be in 720..=4096",
252        });
253    }
254    if !options.scale.is_finite() || !(0.5..=4.0).contains(&options.scale) {
255        return Err(RenderError::InvalidOption {
256            option: "scale",
257            reason: "must be finite and in 0.5..=4.0",
258        });
259    }
260    Ok(())
261}