1use polars::prelude::DataFrame;
2use serde::{Deserialize, Serialize};
3
4use crate::performance::event_window_result;
5use crate::performance::frame::validate_factor_data;
6use crate::performance::{EventReturnsOptions, MeanReturnByQuantileOptions};
7use crate::report::context::ReportContext;
8use crate::report::{
9 ColumnRole, DisplayFormat, DisplayUnit, ReportColumn, ReportColumnData, ReportKind,
10 ReportMetadata, ReportTable, ReportTimeUnit, factor_quantile_statistics,
11};
12use crate::{FerricAlphaError, Result, mean_return_by_quantile};
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
15pub struct EventStudyTearSheetOptions {
16 pub event_window: Option<(u32, u32)>,
17 pub rate_of_return: bool,
18 pub histogram_bins: u32,
19}
20
21#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
22pub struct EventReturnsReportData {
23 pub average_cumulative_returns: ReportTable,
24 pub coverage: ReportTable,
25}
26
27#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
28pub struct EventReturnsTearSheetData {
29 pub metadata: ReportMetadata,
30 pub options: EventReturnsOptions,
31 pub data: EventReturnsReportData,
32}
33
34#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
35pub struct EventStudyReportData {
36 pub quantile_statistics: ReportTable,
37 pub distribution: ReportTable,
38 pub event_returns: Option<EventReturnsReportData>,
39 pub mean_by_quantile: ReportTable,
40 pub daily_by_quantile: ReportTable,
41}
42
43#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
44pub struct EventStudyTearSheetData {
45 pub metadata: ReportMetadata,
46 pub options: EventStudyTearSheetOptions,
47 pub data: EventStudyReportData,
48}
49
50#[derive(Debug, Clone)]
51struct PeriodInfo {
52 label: String,
53 observations: u32,
54}
55
56impl Default for EventStudyTearSheetOptions {
57 fn default() -> Self {
58 Self {
59 event_window: Some((5, 15)),
60 rate_of_return: false,
61 histogram_bins: 50,
62 }
63 }
64}
65
66pub fn create_event_returns_tear_sheet_data(
67 factor_data: &DataFrame,
68 returns: &DataFrame,
69 options: EventReturnsOptions,
70) -> Result<EventReturnsTearSheetData> {
71 let metadata = ReportMetadata::from_factor_data(factor_data, ReportKind::EventReturns)?;
72 let result = event_window_result(factor_data, returns, options)?;
73 Ok(EventReturnsTearSheetData {
74 metadata,
75 options,
76 data: event_returns_report_data(&result.frame, &result.coverage, options.by_group)?,
77 })
78}
79
80pub fn create_event_study_tear_sheet_data(
81 factor_data: &DataFrame,
82 returns: Option<&DataFrame>,
83 options: EventStudyTearSheetOptions,
84) -> Result<EventStudyTearSheetData> {
85 if options.histogram_bins == 0 {
86 return Err(FerricAlphaError::InvalidOption {
87 option: "histogram_bins",
88 reason: "must be positive",
89 });
90 }
91
92 let context = ReportContext::new(factor_data)?;
93 let return_context = validate_factor_data(factor_data, true, false, true)?;
94 let metadata = ReportMetadata::from_factor_data(factor_data, ReportKind::EventStudy)?;
95 let date_time_unit = metadata.date_time_unit();
96 let date_timezone = metadata.date_timezone().map(ToOwned::to_owned);
97 let periods = return_context
98 .periods
99 .iter()
100 .map(|period| PeriodInfo {
101 label: period.label.clone(),
102 observations: period.observations,
103 })
104 .collect::<Vec<_>>();
105 let base = periods
106 .iter()
107 .map(|period| period.observations)
108 .min()
109 .expect("validated returns should contain at least one period");
110
111 let quantile_statistics = factor_quantile_statistics(context.normalized_factor())?;
112 let distribution = distribution_table(
113 &context,
114 options.histogram_bins,
115 date_time_unit,
116 date_timezone.clone(),
117 )?;
118 let mean_options = MeanReturnByQuantileOptions::default()
119 .with_demeaned(false)
120 .with_group_adjust(false);
121 let raw_mean_by_quantile = mean_return_by_quantile(factor_data, mean_options)?;
122 let raw_daily_by_quantile =
123 mean_return_by_quantile(factor_data, mean_options.with_by_date(true))?;
124 let mean_by_quantile = mean_quantile_table(
125 &raw_mean_by_quantile,
126 "returns.mean_by_quantile",
127 "Mean Period-Wise Return by Quantile",
128 base,
129 &periods,
130 options.rate_of_return,
131 false,
132 date_time_unit,
133 date_timezone.clone(),
134 )?;
135 let daily_by_quantile = mean_quantile_table(
136 &raw_daily_by_quantile,
137 "returns.daily_by_quantile",
138 "Daily Return by Quantile",
139 base,
140 &periods,
141 options.rate_of_return,
142 true,
143 date_time_unit,
144 date_timezone,
145 )?;
146 let event_returns = match (returns, options.event_window) {
147 (Some(returns), Some((periods_before, periods_after))) => {
148 let event_options = EventReturnsOptions {
149 periods_before,
150 periods_after,
151 demeaned: false,
152 group_adjust: false,
153 by_group: false,
154 };
155 let result = event_window_result(factor_data, returns, event_options)?;
156 Some(event_returns_report_data(
157 &result.frame,
158 &result.coverage,
159 false,
160 )?)
161 }
162 _ => None,
163 };
164
165 Ok(EventStudyTearSheetData {
166 metadata,
167 options,
168 data: EventStudyReportData {
169 quantile_statistics,
170 distribution,
171 event_returns,
172 mean_by_quantile,
173 daily_by_quantile,
174 },
175 })
176}
177
178fn event_returns_report_data(
179 frame: &DataFrame,
180 coverage: &[crate::performance::EventCoverageRow],
181 by_group: bool,
182) -> Result<EventReturnsReportData> {
183 Ok(EventReturnsReportData {
184 average_cumulative_returns: average_cumulative_returns_table(frame, by_group)?,
185 coverage: coverage_table(coverage)?,
186 })
187}
188
189fn average_cumulative_returns_table(frame: &DataFrame, by_group: bool) -> Result<ReportTable> {
190 let quantiles = frame
191 .column("factor_quantile")?
192 .as_materialized_series()
193 .u32()?;
194 let groups = frame
195 .column("group")
196 .ok()
197 .map(|column| column.as_materialized_series().str())
198 .transpose()?;
199 let offsets = frame.column("offset")?.as_materialized_series().i32()?;
200 let means = frame
201 .column("mean_cumulative_return")?
202 .as_materialized_series()
203 .f64()?;
204 let stds = frame
205 .column("std_cumulative_return")?
206 .as_materialized_series()
207 .f64()?;
208 let counts = frame.column("count")?.as_materialized_series().u64()?;
209
210 let mut columns = vec![ReportColumn::new(
211 "factor_quantile",
212 "Factor Quantile",
213 ColumnRole::Dimension,
214 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
215 ReportColumnData::UInt32(
216 (0..frame.height())
217 .map(|index| quantiles.get(index))
218 .collect(),
219 ),
220 )];
221 let mut sort_by = vec!["factor_quantile".to_string()];
222 if by_group {
223 columns.push(ReportColumn::new(
224 "group",
225 "Group",
226 ColumnRole::Dimension,
227 None,
228 ReportColumnData::String(
229 (0..frame.height())
230 .map(|index| {
231 groups
232 .as_ref()
233 .and_then(|groups| groups.get(index).map(ToOwned::to_owned))
234 })
235 .collect(),
236 ),
237 ));
238 sort_by.push("group".to_string());
239 }
240 columns.extend([
241 ReportColumn::new(
242 "offset",
243 "Offset",
244 ColumnRole::Dimension,
245 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
246 ReportColumnData::Int32(
247 (0..frame.height())
248 .map(|index| offsets.get(index))
249 .collect(),
250 ),
251 ),
252 ReportColumn::new(
253 "mean_cumulative_return",
254 "Mean Cumulative Return",
255 ColumnRole::Measure,
256 Some(DisplayFormat::new(DisplayUnit::DecimalReturn, 6)),
257 ReportColumnData::Float64((0..frame.height()).map(|index| means.get(index)).collect()),
258 ),
259 ReportColumn::new(
260 "std_cumulative_return",
261 "Std Cumulative Return",
262 ColumnRole::Statistic,
263 Some(DisplayFormat::new(DisplayUnit::DecimalReturn, 6)),
264 ReportColumnData::Float64((0..frame.height()).map(|index| stds.get(index)).collect()),
265 ),
266 ReportColumn::new(
267 "count",
268 "Count",
269 ColumnRole::Measure,
270 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
271 ReportColumnData::UInt64((0..frame.height()).map(|index| counts.get(index)).collect()),
272 ),
273 ]);
274 sort_by.push("offset".to_string());
275
276 ReportTable::new(
277 "events.average_cumulative_returns",
278 "Average Cumulative Returns by Event Offset",
279 sort_by,
280 columns,
281 )
282}
283
284fn coverage_table(rows: &[crate::performance::EventCoverageRow]) -> Result<ReportTable> {
285 ReportTable::new(
286 "events.coverage",
287 "Event Window Coverage",
288 vec!["coverage_row".to_string()],
289 vec![
290 ReportColumn::new(
291 "coverage_row",
292 "Coverage Row",
293 ColumnRole::Dimension,
294 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
295 ReportColumnData::UInt32((0..rows.len()).map(|index| Some(index as u32)).collect()),
296 ),
297 ReportColumn::new(
298 "scope",
299 "Scope",
300 ColumnRole::Dimension,
301 None,
302 ReportColumnData::String(rows.iter().map(|row| Some(row.scope.clone())).collect()),
303 ),
304 ReportColumn::new(
305 "offset",
306 "Offset",
307 ColumnRole::Dimension,
308 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
309 ReportColumnData::Int32(rows.iter().map(|row| row.offset).collect()),
310 ),
311 count_column(
312 "input_events",
313 "Input Events",
314 rows.iter().map(|row| Some(row.input_events)).collect(),
315 ),
316 count_column(
317 "used_events",
318 "Used Events",
319 rows.iter().map(|row| Some(row.used_events)).collect(),
320 ),
321 count_column(
322 "skipped_missing_date",
323 "Skipped Missing Date",
324 rows.iter()
325 .map(|row| Some(row.skipped_missing_date))
326 .collect(),
327 ),
328 count_column(
329 "imputed_return_cells",
330 "Imputed Return Cells",
331 rows.iter()
332 .map(|row| Some(row.imputed_return_cells))
333 .collect(),
334 ),
335 count_column(
336 "path_count",
337 "Path Count",
338 rows.iter().map(|row| Some(row.path_count)).collect(),
339 ),
340 ],
341 )
342}
343
344fn distribution_table(
345 context: &ReportContext,
346 requested_bins: u32,
347 date_time_unit: ReportTimeUnit,
348 date_timezone: Option<String>,
349) -> Result<ReportTable> {
350 let mut dates = context
351 .factor_data()
352 .rows
353 .iter()
354 .filter(|row| row.quantile.is_some_and(|quantile| quantile > 0))
355 .map(|row| row.date)
356 .collect::<Vec<_>>();
357 if dates.is_empty() {
358 return Err(FerricAlphaError::InsufficientData {
359 operation: "create_event_study_tear_sheet_data",
360 });
361 }
362 dates.sort_unstable();
363 let start = dates[0];
364 let end = *dates.last().expect("dates should be non-empty");
365 let bin_count = if start == end { 1 } else { requested_bins };
366 let span = end
367 .checked_sub(start)
368 .ok_or(FerricAlphaError::InvalidInput {
369 operation: "create_event_study_tear_sheet_data",
370 reason: "date range overflow",
371 })?;
372
373 let mut bin_starts = Vec::with_capacity(bin_count as usize);
374 let mut bin_ends = Vec::with_capacity(bin_count as usize);
375 let mut event_counts = Vec::with_capacity(bin_count as usize);
376 for index in 0..bin_count {
377 let bin_start = start + ((span as i128 * i128::from(index)) / i128::from(bin_count)) as i64;
378 let bin_end = if index + 1 == bin_count {
379 end
380 } else {
381 start + ((span as i128 * i128::from(index + 1)) / i128::from(bin_count)) as i64
382 };
383 let count = dates
384 .iter()
385 .filter(|date| {
386 if index + 1 == bin_count {
387 **date >= bin_start && **date <= bin_end
388 } else {
389 **date >= bin_start && **date < bin_end
390 }
391 })
392 .count() as u64;
393 bin_starts.push(Some(bin_start));
394 bin_ends.push(Some(bin_end));
395 event_counts.push(Some(count));
396 }
397
398 ReportTable::new(
399 "events.distribution",
400 "Event Distribution",
401 vec!["bin_start".to_string()],
402 vec![
403 ReportColumn::new(
404 "bin_start",
405 "Bin Start",
406 ColumnRole::Dimension,
407 None,
408 ReportColumnData::Datetime {
409 values: bin_starts,
410 time_unit: date_time_unit,
411 timezone: date_timezone.clone(),
412 },
413 ),
414 ReportColumn::new(
415 "bin_end",
416 "Bin End",
417 ColumnRole::Dimension,
418 None,
419 ReportColumnData::Datetime {
420 values: bin_ends,
421 time_unit: date_time_unit,
422 timezone: date_timezone,
423 },
424 ),
425 count_column("event_count", "Event Count", event_counts),
426 ],
427 )
428}
429
430#[allow(clippy::too_many_arguments)]
431fn mean_quantile_table(
432 frame: &DataFrame,
433 id: &'static str,
434 title: &'static str,
435 base: u32,
436 periods: &[PeriodInfo],
437 rate_of_return: bool,
438 by_date: bool,
439 date_time_unit: ReportTimeUnit,
440 date_timezone: Option<String>,
441) -> Result<ReportTable> {
442 let dates = frame
443 .column("date")
444 .ok()
445 .map(|column| column.as_materialized_series().datetime())
446 .transpose()?;
447 let quantiles = frame
448 .column("factor_quantile")?
449 .as_materialized_series()
450 .u32()?;
451 let period_labels = frame.column("period")?.as_materialized_series().str()?;
452 let means = frame
453 .column("mean_return")?
454 .as_materialized_series()
455 .f64()?;
456 let errors = frame.column("std_error")?.as_materialized_series().f64()?;
457 let counts = frame.column("count")?.as_materialized_series().u32()?;
458
459 let mut out_dates = Vec::new();
460 let mut out_quantiles = Vec::with_capacity(frame.height());
461 let mut out_periods = Vec::with_capacity(frame.height());
462 let mut out_means = Vec::with_capacity(frame.height());
463 let mut out_errors = Vec::with_capacity(frame.height());
464 let mut out_counts = Vec::with_capacity(frame.height());
465 for index in 0..frame.height() {
466 let period = period_labels.get(index).expect("period is validated");
467 if by_date {
468 out_dates.push(dates.as_ref().and_then(|dates| dates.physical().get(index)));
469 }
470 out_quantiles.push(quantiles.get(index));
471 out_periods.push(Some(period.to_string()));
472 let period_observations = period_observations(periods, period);
473 if rate_of_return {
474 out_means.push(convert_return(means.get(index), base, period_observations));
475 out_errors.push(convert_error(errors.get(index), base, period_observations));
476 } else {
477 out_means.push(means.get(index));
478 out_errors.push(errors.get(index));
479 }
480 out_counts.push(counts.get(index).map(u64::from));
481 }
482
483 let mut columns = Vec::new();
484 let mut sort_by = Vec::new();
485 if by_date {
486 columns.push(ReportColumn::new(
487 "date",
488 "Date",
489 ColumnRole::Dimension,
490 None,
491 ReportColumnData::Datetime {
492 values: out_dates,
493 time_unit: date_time_unit,
494 timezone: date_timezone,
495 },
496 ));
497 sort_by.push("date".to_string());
498 }
499 columns.extend([
500 ReportColumn::new(
501 "factor_quantile",
502 "Factor Quantile",
503 ColumnRole::Dimension,
504 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
505 ReportColumnData::UInt32(out_quantiles),
506 ),
507 ReportColumn::new(
508 "period",
509 "Period",
510 ColumnRole::Dimension,
511 None,
512 ReportColumnData::String(out_periods),
513 ),
514 ReportColumn::new(
515 "mean_return",
516 "Mean Return",
517 ColumnRole::Measure,
518 Some(DisplayFormat::new(DisplayUnit::DecimalReturn, 6)),
519 ReportColumnData::Float64(out_means),
520 ),
521 ReportColumn::new(
522 "std_error",
523 "Std Error",
524 ColumnRole::Statistic,
525 Some(DisplayFormat::new(DisplayUnit::DecimalReturn, 6)),
526 ReportColumnData::Float64(out_errors),
527 ),
528 ReportColumn::new(
529 "count",
530 "Count",
531 ColumnRole::Measure,
532 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
533 ReportColumnData::UInt64(out_counts),
534 ),
535 ]);
536 sort_by.extend(["factor_quantile".to_string(), "period".to_string()]);
537 ReportTable::new(id, title, sort_by, columns)
538}
539
540fn count_column(name: &'static str, label: &'static str, values: Vec<Option<u64>>) -> ReportColumn {
541 ReportColumn::new(
542 name,
543 label,
544 ColumnRole::Measure,
545 Some(DisplayFormat::new(DisplayUnit::Count, 0)),
546 ReportColumnData::UInt64(values),
547 )
548}
549
550fn period_observations(periods: &[PeriodInfo], label: &str) -> u32 {
551 periods
552 .iter()
553 .find(|period| period.label == label)
554 .map(|period| period.observations)
555 .expect("period should come from factor data")
556}
557
558fn convert_return(value: Option<f64>, base: u32, period: u32) -> Option<f64> {
559 let value = value?;
560 if !value.is_finite() {
561 return None;
562 }
563 let gross = 1.0 + value;
564 let exponent = base as f64 / period as f64;
565 if gross < 0.0 && exponent.fract() != 0.0 {
566 return None;
567 }
568 let converted = gross.powf(exponent) - 1.0;
569 converted.is_finite().then_some(converted)
570}
571
572fn convert_error(value: Option<f64>, base: u32, period: u32) -> Option<f64> {
573 let value = value?;
574 if !value.is_finite() {
575 return None;
576 }
577 let converted = value / (period as f64 / base as f64).sqrt();
578 converted.is_finite().then_some(converted)
579}