ferric_alpha_render/plan/
mod.rs1mod 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}