Skip to main content

ferric_alpha/report/
metadata.rs

1use std::collections::BTreeSet;
2
3use polars::prelude::{DataFrame, DataType, TimeUnit};
4use serde::{Deserialize, Serialize};
5
6use crate::Result;
7use crate::performance::frame::validate_factor_data;
8use crate::report::ReportTimeUnit;
9
10pub const CONTRACT_VERSION: &str = "ferric-alpha.tear-sheet/v1";
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
13#[serde(rename_all = "snake_case")]
14pub enum ReportKind {
15    Summary,
16    Returns,
17    Information,
18    Turnover,
19    Full,
20    EventReturns,
21    EventStudy,
22}
23
24#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
25pub struct ReportMetadata {
26    contract_version: String,
27    report_kind: ReportKind,
28    source_rows: u64,
29    date_start: Option<i64>,
30    date_end: Option<i64>,
31    date_time_unit: ReportTimeUnit,
32    date_timezone: Option<String>,
33    periods: Vec<String>,
34    quantiles: Vec<u32>,
35    groups: Vec<String>,
36}
37
38impl ReportMetadata {
39    pub fn from_factor_data(frame: &DataFrame, report_kind: ReportKind) -> Result<Self> {
40        let data = validate_factor_data(frame, false, false, false)?;
41        let mut quantiles = BTreeSet::new();
42        let mut groups = BTreeSet::new();
43        let mut date_start = None;
44        let mut date_end = None;
45
46        for row in &data.rows {
47            date_start = Some(date_start.map_or(row.date, |value: i64| value.min(row.date)));
48            date_end = Some(date_end.map_or(row.date, |value: i64| value.max(row.date)));
49            if let Some(quantile) = row.quantile
50                && quantile > 0
51            {
52                quantiles.insert(quantile);
53            }
54            if let Some(group) = &row.group {
55                groups.insert(group.clone());
56            }
57        }
58
59        let (date_time_unit, date_timezone) = date_metadata(&data.date_dtype)?;
60
61        Ok(Self {
62            contract_version: CONTRACT_VERSION.to_string(),
63            report_kind,
64            source_rows: data.rows.len() as u64,
65            date_start,
66            date_end,
67            date_time_unit,
68            date_timezone,
69            periods: data
70                .periods
71                .iter()
72                .map(|period| period.label.clone())
73                .collect(),
74            quantiles: quantiles.into_iter().collect(),
75            groups: groups.into_iter().collect(),
76        })
77    }
78
79    pub fn contract_version(&self) -> &str {
80        &self.contract_version
81    }
82
83    pub fn report_kind(&self) -> ReportKind {
84        self.report_kind
85    }
86
87    pub fn source_rows(&self) -> u64 {
88        self.source_rows
89    }
90
91    pub fn date_start(&self) -> Option<i64> {
92        self.date_start
93    }
94
95    pub fn date_end(&self) -> Option<i64> {
96        self.date_end
97    }
98
99    pub fn date_time_unit(&self) -> ReportTimeUnit {
100        self.date_time_unit
101    }
102
103    pub fn date_timezone(&self) -> Option<&str> {
104        self.date_timezone.as_deref()
105    }
106
107    pub fn periods(&self) -> &[String] {
108        &self.periods
109    }
110
111    pub fn quantiles(&self) -> &[u32] {
112        &self.quantiles
113    }
114
115    pub fn groups(&self) -> &[String] {
116        &self.groups
117    }
118}
119
120fn date_metadata(dtype: &DataType) -> Result<(ReportTimeUnit, Option<String>)> {
121    match dtype {
122        DataType::Datetime(unit, timezone) => {
123            Ok(((*unit).into(), timezone.as_ref().map(ToString::to_string)))
124        }
125        actual => Err(crate::FerricAlphaError::InvalidDtype {
126            column: "date",
127            expected: "Datetime",
128            actual: actual.to_string(),
129        }),
130    }
131}
132
133impl From<TimeUnit> for ReportTimeUnit {
134    fn from(value: TimeUnit) -> Self {
135        match value {
136            TimeUnit::Nanoseconds => Self::Nanoseconds,
137            TimeUnit::Microseconds => Self::Microseconds,
138            TimeUnit::Milliseconds => Self::Milliseconds,
139        }
140    }
141}