Skip to main content

ferric_alpha/report/
table.rs

1use std::cmp::Ordering;
2use std::collections::HashSet;
3
4use polars::prelude::{Column, DataFrame, IntoColumn, NamedFrom, Series, TimeUnit, TimeZone};
5use serde::{Deserialize, Serialize};
6
7use crate::{FerricAlphaError, Result};
8
9const NEW_OPERATION: &str = "ReportTable::new";
10
11#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
12pub struct ReportTable {
13    id: String,
14    title: String,
15    row_count: usize,
16    sort_by: Vec<String>,
17    columns: Vec<ReportColumn>,
18}
19
20#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
21pub struct ReportColumn {
22    name: String,
23    label: String,
24    role: ColumnRole,
25    display: Option<DisplayFormat>,
26    data: ReportColumnData,
27}
28
29#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
30#[serde(rename_all = "snake_case")]
31pub enum ReportColumnData {
32    Boolean(Vec<Option<bool>>),
33    Int32(Vec<Option<i32>>),
34    Int64(Vec<Option<i64>>),
35    UInt32(Vec<Option<u32>>),
36    UInt64(Vec<Option<u64>>),
37    Float64(Vec<Option<f64>>),
38    String(Vec<Option<String>>),
39    Datetime {
40        values: Vec<Option<i64>>,
41        time_unit: ReportTimeUnit,
42        timezone: Option<String>,
43    },
44}
45
46#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
47#[serde(rename_all = "snake_case")]
48pub enum ColumnRole {
49    Dimension,
50    Measure,
51    Statistic,
52}
53
54#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
55#[serde(rename_all = "snake_case")]
56pub enum ReportTimeUnit {
57    Nanoseconds,
58    Microseconds,
59    Milliseconds,
60}
61
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
63pub struct DisplayFormat {
64    unit: DisplayUnit,
65    decimals: u8,
66}
67
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
69#[serde(rename_all = "snake_case")]
70pub enum DisplayUnit {
71    Raw,
72    DecimalReturn,
73    BasisPoints,
74    Percent,
75    Ratio,
76    Count,
77}
78
79#[derive(Debug, Clone, Copy, PartialEq)]
80enum SortValue<'a> {
81    Boolean(bool),
82    Int32(i32),
83    Int64(i64),
84    UInt32(u32),
85    UInt64(u64),
86    Float64(f64),
87    String(&'a str),
88    Datetime(i64),
89}
90
91impl ReportTable {
92    pub fn new(
93        id: impl Into<String>,
94        title: impl Into<String>,
95        sort_by: Vec<String>,
96        columns: Vec<ReportColumn>,
97    ) -> Result<Self> {
98        let id = id.into();
99        if !valid_table_id(&id) {
100            return invalid("invalid table id");
101        }
102
103        let mut names = HashSet::with_capacity(columns.len());
104        for column in &columns {
105            if !names.insert(column.name.as_str()) {
106                return invalid("duplicate column name");
107            }
108            if matches!(&column.data, ReportColumnData::Float64(values) if values
109                .iter()
110                .flatten()
111                .any(|value| !value.is_finite()))
112            {
113                return invalid("float value is not finite");
114            }
115        }
116
117        let row_count = match columns.first() {
118            Some(column) => column.data.len(),
119            None => 0,
120        };
121        if columns.iter().any(|column| column.data.len() != row_count) {
122            return invalid("column lengths differ");
123        }
124
125        let sort_columns = sort_by
126            .iter()
127            .map(|name| {
128                columns.iter().find(|column| column.name == *name).ok_or(
129                    FerricAlphaError::InvalidReport {
130                        operation: NEW_OPERATION,
131                        reason: "sort key missing",
132                    },
133                )
134            })
135            .collect::<Result<Vec<_>>>()?;
136
137        for row in 0..row_count {
138            if sort_columns
139                .iter()
140                .any(|column| column.data.sort_value(row).is_none())
141            {
142                return invalid("sort key contains null");
143            }
144        }
145
146        for row in 1..row_count {
147            let ordering = compare_rows(&sort_columns, row - 1, row);
148            if ordering == Some(Ordering::Greater) {
149                return invalid("rows are not sorted by sort_by");
150            }
151        }
152
153        Ok(Self {
154            id,
155            title: title.into(),
156            row_count,
157            sort_by,
158            columns,
159        })
160    }
161
162    pub fn id(&self) -> &str {
163        &self.id
164    }
165
166    pub fn title(&self) -> &str {
167        &self.title
168    }
169
170    pub fn row_count(&self) -> usize {
171        self.row_count
172    }
173
174    pub fn sort_by(&self) -> &[String] {
175        &self.sort_by
176    }
177
178    pub fn columns(&self) -> &[ReportColumn] {
179        &self.columns
180    }
181
182    pub fn column_names(&self) -> Vec<&str> {
183        self.columns
184            .iter()
185            .map(|column| column.name.as_str())
186            .collect()
187    }
188
189    pub fn to_polars(&self) -> Result<DataFrame> {
190        let columns = self
191            .columns
192            .iter()
193            .map(ReportColumn::to_polars)
194            .collect::<Result<Vec<_>>>()?;
195        Ok(DataFrame::new(self.row_count, columns)?)
196    }
197}
198
199impl ReportColumn {
200    pub fn new(
201        name: impl Into<String>,
202        label: impl Into<String>,
203        role: ColumnRole,
204        display: Option<DisplayFormat>,
205        data: ReportColumnData,
206    ) -> Self {
207        Self {
208            name: name.into(),
209            label: label.into(),
210            role,
211            display,
212            data,
213        }
214    }
215
216    pub fn name(&self) -> &str {
217        &self.name
218    }
219
220    pub fn label(&self) -> &str {
221        &self.label
222    }
223
224    pub fn role(&self) -> ColumnRole {
225        self.role
226    }
227
228    pub fn display(&self) -> Option<&DisplayFormat> {
229        self.display.as_ref()
230    }
231
232    pub fn data(&self) -> &ReportColumnData {
233        &self.data
234    }
235
236    fn to_polars(&self) -> Result<Column> {
237        let column = match &self.data {
238            ReportColumnData::Boolean(values) => {
239                Series::new(self.name.as_str().into(), values).into_column()
240            }
241            ReportColumnData::Int32(values) => {
242                Series::new(self.name.as_str().into(), values).into_column()
243            }
244            ReportColumnData::Int64(values) => {
245                Series::new(self.name.as_str().into(), values).into_column()
246            }
247            ReportColumnData::UInt32(values) => {
248                Series::new(self.name.as_str().into(), values).into_column()
249            }
250            ReportColumnData::UInt64(values) => {
251                Series::new(self.name.as_str().into(), values).into_column()
252            }
253            ReportColumnData::Float64(values) => {
254                Series::new(self.name.as_str().into(), values).into_column()
255            }
256            ReportColumnData::String(values) => {
257                Series::new(self.name.as_str().into(), values).into_column()
258            }
259            ReportColumnData::Datetime {
260                values,
261                time_unit,
262                timezone,
263            } => Series::new(self.name.as_str().into(), values)
264                .into_datetime(
265                    (*time_unit).into(),
266                    TimeZone::opt_try_new(timezone.as_deref())?,
267                )
268                .into_column(),
269        };
270        Ok(column)
271    }
272}
273
274impl ReportColumnData {
275    pub fn len(&self) -> usize {
276        match self {
277            Self::Boolean(values) => values.len(),
278            Self::Int32(values) => values.len(),
279            Self::Int64(values) => values.len(),
280            Self::UInt32(values) => values.len(),
281            Self::UInt64(values) => values.len(),
282            Self::Float64(values) => values.len(),
283            Self::String(values) => values.len(),
284            Self::Datetime { values, .. } => values.len(),
285        }
286    }
287
288    pub fn is_empty(&self) -> bool {
289        self.len() == 0
290    }
291
292    fn sort_value(&self, row: usize) -> Option<SortValue<'_>> {
293        match self {
294            Self::Boolean(values) => values.get(row).copied().flatten().map(SortValue::Boolean),
295            Self::Int32(values) => values.get(row).copied().flatten().map(SortValue::Int32),
296            Self::Int64(values) => values.get(row).copied().flatten().map(SortValue::Int64),
297            Self::UInt32(values) => values.get(row).copied().flatten().map(SortValue::UInt32),
298            Self::UInt64(values) => values.get(row).copied().flatten().map(SortValue::UInt64),
299            Self::Float64(values) => values.get(row).copied().flatten().map(SortValue::Float64),
300            Self::String(values) => values
301                .get(row)
302                .and_then(Option::as_deref)
303                .map(SortValue::String),
304            Self::Datetime { values, .. } => {
305                values.get(row).copied().flatten().map(SortValue::Datetime)
306            }
307        }
308    }
309}
310
311impl DisplayFormat {
312    pub fn new(unit: DisplayUnit, decimals: u8) -> Self {
313        Self { unit, decimals }
314    }
315
316    pub fn unit(&self) -> DisplayUnit {
317        self.unit
318    }
319
320    pub fn decimals(&self) -> u8 {
321        self.decimals
322    }
323}
324
325impl From<ReportTimeUnit> for TimeUnit {
326    fn from(value: ReportTimeUnit) -> Self {
327        match value {
328            ReportTimeUnit::Nanoseconds => Self::Nanoseconds,
329            ReportTimeUnit::Microseconds => Self::Microseconds,
330            ReportTimeUnit::Milliseconds => Self::Milliseconds,
331        }
332    }
333}
334
335fn invalid<T>(reason: &'static str) -> Result<T> {
336    Err(FerricAlphaError::InvalidReport {
337        operation: NEW_OPERATION,
338        reason,
339    })
340}
341
342fn compare_rows(columns: &[&ReportColumn], left: usize, right: usize) -> Option<Ordering> {
343    for column in columns {
344        let left = column.data.sort_value(left)?;
345        let right = column.data.sort_value(right)?;
346        let ordering = left.partial_cmp(&right)?;
347        if ordering != Ordering::Equal {
348            return Some(ordering);
349        }
350    }
351    Some(Ordering::Equal)
352}
353
354fn valid_table_id(id: &str) -> bool {
355    !id.is_empty() && id.split('.').all(valid_table_id_segment)
356}
357
358fn valid_table_id_segment(segment: &str) -> bool {
359    if segment.is_empty()
360        || segment.starts_with('_')
361        || segment.ends_with('_')
362        || segment.contains("__")
363    {
364        return false;
365    }
366
367    segment.chars().enumerate().all(|(index, character)| {
368        character.is_ascii_lowercase()
369            || (index > 0 && (character.is_ascii_digit() || character == '_'))
370    })
371}
372
373impl PartialOrd for SortValue<'_> {
374    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
375        match (self, other) {
376            (Self::Boolean(left), Self::Boolean(right)) => left.partial_cmp(right),
377            (Self::Int32(left), Self::Int32(right)) => left.partial_cmp(right),
378            (Self::Int64(left), Self::Int64(right)) => left.partial_cmp(right),
379            (Self::UInt32(left), Self::UInt32(right)) => left.partial_cmp(right),
380            (Self::UInt64(left), Self::UInt64(right)) => left.partial_cmp(right),
381            (Self::Float64(left), Self::Float64(right)) => left.partial_cmp(right),
382            (Self::String(left), Self::String(right)) => left.partial_cmp(right),
383            (Self::Datetime(left), Self::Datetime(right)) => left.partial_cmp(right),
384            _ => None,
385        }
386    }
387}