Skip to main content

ferric_alpha/report/
events.rs

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}