ferric_alpha/report/
metadata.rs1use 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}