ferric-alpha 0.1.0

alphalens-style high-performance factor analysis built with Rust and Polars
Documentation
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};

use polars::prelude::{DataFrame, DataType, IntoColumn, NamedFrom, Series, SortMultipleOptions};

use crate::data::{ensure_matching_date_timezone, required_column};
use crate::error::{FerricAlphaError, Result};
use crate::performance::EventReturnsOptions;
use crate::performance::frame::{FactorRow, ensure_dtype, mean, validate_factor_data};
use crate::statistics::sample_std;

const OPERATION: &str = "common_start_returns";

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommonStartReturnsOptions {
    pub periods_before: u32,
    pub periods_after: u32,
    pub cumulative: bool,
    pub mean_by_date: bool,
    pub demeaned: bool,
}

impl Default for CommonStartReturnsOptions {
    fn default() -> Self {
        Self {
            periods_before: 10,
            periods_after: 15,
            cumulative: false,
            mean_by_date: false,
            demeaned: false,
        }
    }
}

impl CommonStartReturnsOptions {
    pub fn with_periods_before(mut self, periods_before: u32) -> Self {
        self.periods_before = periods_before;
        self
    }

    pub fn with_periods_after(mut self, periods_after: u32) -> Self {
        self.periods_after = periods_after;
        self
    }

    pub fn with_cumulative(mut self, cumulative: bool) -> Self {
        self.cumulative = cumulative;
        self
    }

    pub fn with_mean_by_date(mut self, mean_by_date: bool) -> Self {
        self.mean_by_date = mean_by_date;
        self
    }

    pub fn with_demeaned(mut self, demeaned: bool) -> Self {
        self.demeaned = demeaned;
        self
    }
}

#[derive(Debug, Clone)]
struct ReturnCalendar {
    dates: Vec<i64>,
    values: HashMap<(String, i64), Option<f64>>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct CommonStartRow {
    date: i64,
    asset: String,
    quantile: Option<u32>,
    group: Option<String>,
}

pub fn common_start_returns(
    factor_data: &DataFrame,
    returns: &DataFrame,
    options: CommonStartReturnsOptions,
) -> Result<DataFrame> {
    let data = validate_factor_data(factor_data, false, false, false)?;
    let calendar = validate_returns(factor_data, returns, options.cumulative)?;
    if calendar.dates.is_empty() {
        return Err(FerricAlphaError::InsufficientData {
            operation: OPERATION,
        });
    }

    let rows = common_start_rows(&data.rows, false);
    let values_by_offset = aligned_common_start_values(
        &rows,
        options.demeaned.then_some(rows.as_slice()),
        &calendar,
        options.periods_before,
        options.periods_after,
        options.mean_by_date,
    );

    common_start_summary_frame(values_by_offset)
}

pub fn average_cumulative_return_by_quantile_from_prices(
    factor_data: &DataFrame,
    returns: &DataFrame,
    options: EventReturnsOptions,
) -> Result<DataFrame> {
    let data = validate_factor_data(
        factor_data,
        true,
        options.group_adjust || options.by_group,
        false,
    )?;
    if options.group_adjust || options.by_group {
        return Err(FerricAlphaError::InvalidInput {
            operation: "average_cumulative_return_by_quantile_from_prices",
            reason: "group-adjusted price compatibility is not implemented yet",
        });
    }
    let calendar = validate_returns(factor_data, returns, true)?;
    if calendar.dates.is_empty() {
        return Err(FerricAlphaError::InsufficientData {
            operation: "average_cumulative_return_by_quantile_from_prices",
        });
    }

    let rows = common_start_rows(&data.rows, true);
    let universe = options.demeaned.then_some(rows.as_slice());
    let mut rows_by_quantile = BTreeMap::<u32, Vec<CommonStartRow>>::new();
    for row in &rows {
        if let Some(quantile) = row.quantile {
            rows_by_quantile
                .entry(quantile)
                .or_default()
                .push(row.clone());
        }
    }

    let mut factor_quantiles = Vec::new();
    let mut offsets = Vec::new();
    let mut means = Vec::new();
    let mut stds = Vec::new();
    let mut counts = Vec::new();
    for (quantile, quantile_rows) in rows_by_quantile {
        let values_by_offset = aligned_common_start_values(
            &quantile_rows,
            universe,
            &calendar,
            options.periods_before,
            options.periods_after,
            true,
        );
        for (offset, values) in values_by_offset {
            if values.is_empty() {
                continue;
            }
            factor_quantiles.push(quantile);
            offsets.push(offset);
            means.push(mean(&values));
            stds.push(sample_std(&values)?);
            counts.push(values.len() as u64);
        }
    }

    if factor_quantiles.is_empty() {
        return Err(FerricAlphaError::InsufficientData {
            operation: "average_cumulative_return_by_quantile_from_prices",
        });
    }

    let frame = DataFrame::new(
        factor_quantiles.len(),
        vec![
            Series::new("factor_quantile".into(), factor_quantiles).into_column(),
            Series::new("offset".into(), offsets).into_column(),
            Series::new("mean_cumulative_return".into(), means).into_column(),
            Series::new("std_cumulative_return".into(), stds).into_column(),
            Series::new("count".into(), counts).into_column(),
        ],
    )?
    .sort(
        ["factor_quantile", "offset"],
        SortMultipleOptions::default(),
    )?;
    Ok(frame)
}

fn common_start_summary_frame(values_by_offset: BTreeMap<i32, Vec<f64>>) -> Result<DataFrame> {
    let mut offsets = Vec::new();
    let mut means = Vec::new();
    let mut stds = Vec::new();
    let mut counts = Vec::new();
    for (offset, values) in values_by_offset {
        if values.is_empty() {
            continue;
        }
        offsets.push(offset);
        means.push(mean(&values));
        stds.push(sample_std(&values)?);
        counts.push(values.len() as u64);
    }

    if offsets.is_empty() {
        return Err(FerricAlphaError::InsufficientData {
            operation: OPERATION,
        });
    }

    let frame = DataFrame::new(
        offsets.len(),
        vec![
            Series::new("offset".into(), offsets).into_column(),
            Series::new("mean".into(), means).into_column(),
            Series::new("std".into(), stds).into_column(),
            Series::new("count".into(), counts).into_column(),
        ],
    )?
    .sort(["offset"], SortMultipleOptions::default())?;
    Ok(frame)
}

fn common_start_rows(rows: &[FactorRow], require_quantile: bool) -> Vec<CommonStartRow> {
    rows.iter()
        .filter(|row| row.factor.is_some())
        .filter(|row| !require_quantile || matches!(row.quantile, Some(value) if value > 0))
        .map(|row| CommonStartRow {
            date: row.date,
            asset: row.asset.clone(),
            quantile: row.quantile,
            group: row.group.clone(),
        })
        .collect()
}

fn aligned_common_start_values(
    rows: &[CommonStartRow],
    demean_rows: Option<&[CommonStartRow]>,
    calendar: &ReturnCalendar,
    periods_before: u32,
    periods_after: u32,
    mean_by_date: bool,
) -> BTreeMap<i32, Vec<f64>> {
    let date_index = calendar
        .dates
        .iter()
        .enumerate()
        .map(|(index, date)| (*date, index))
        .collect::<HashMap<_, _>>();
    let rows_by_date = rows.iter().fold(
        BTreeMap::<i64, Vec<&CommonStartRow>>::new(),
        |mut acc, row| {
            acc.entry(row.date).or_default().push(row);
            acc
        },
    );
    let demean_assets_by_date = demean_rows.map(|rows| {
        rows.iter()
            .fold(BTreeMap::<i64, BTreeSet<String>>::new(), |mut acc, row| {
                acc.entry(row.date).or_default().insert(row.asset.clone());
                acc
            })
    });

    let mut values_by_offset = BTreeMap::<i32, Vec<f64>>::new();
    let start = -(periods_before as i32);
    let end = periods_after as i32;
    for offset in start..=end {
        values_by_offset.entry(offset).or_default();
    }

    for (event_date, rows) in rows_by_date {
        let Some(day_zero_index) = date_index.get(&event_date).copied() else {
            continue;
        };
        let event_assets = rows
            .iter()
            .map(|row| row.asset.clone())
            .collect::<BTreeSet<_>>()
            .into_iter()
            .collect::<Vec<_>>();
        if event_assets.is_empty() {
            continue;
        }

        for offset in start..=end {
            let target_index = day_zero_index as i32 + offset;
            if target_index < 0 || target_index >= calendar.dates.len() as i32 {
                continue;
            }
            let target_date = calendar.dates[target_index as usize];
            let universe_mean = demean_assets_by_date
                .as_ref()
                .and_then(|assets_by_date| assets_by_date.get(&event_date))
                .map(|assets| {
                    let universe_values = assets
                        .iter()
                        .filter_map(|asset| return_value(calendar, target_date, asset))
                        .collect::<Vec<_>>();
                    mean(&universe_values).unwrap_or(0.0)
                })
                .unwrap_or(0.0);
            let event_values = event_assets
                .iter()
                .filter_map(|asset| {
                    return_value(calendar, target_date, asset).map(|value| value - universe_mean)
                })
                .collect::<Vec<_>>();
            if event_values.is_empty() {
                continue;
            }
            if mean_by_date {
                values_by_offset
                    .entry(offset)
                    .or_default()
                    .push(mean(&event_values).expect("event values are non-empty"));
            } else {
                values_by_offset
                    .entry(offset)
                    .or_default()
                    .extend(event_values);
            }
        }
    }
    values_by_offset
}

fn validate_returns(
    factor_data: &DataFrame,
    returns: &DataFrame,
    cumulative: bool,
) -> Result<ReturnCalendar> {
    ensure_matching_date_timezone(factor_data, returns)?;
    let date = required_column(returns, "date")?;
    let asset = required_column(returns, "asset")?;
    let ret = required_column(returns, "return")?;
    ensure_dtype("date", date.dtype(), "Datetime", |dtype| {
        matches!(dtype, DataType::Datetime(_, _))
    })?;
    ensure_dtype("asset", asset.dtype(), "String", |dtype| {
        matches!(dtype, DataType::String)
    })?;
    ensure_dtype("return", ret.dtype(), "Float64", |dtype| {
        matches!(dtype, DataType::Float64)
    })?;
    if date.null_count() > 0 || asset.null_count() > 0 {
        return Err(FerricAlphaError::NullKey);
    }

    let dates = date.as_materialized_series().datetime()?;
    let assets = asset.as_materialized_series().str()?;
    let returns_values = ret.as_materialized_series().f64()?;
    let mut seen = HashSet::with_capacity(returns.height());
    let mut calendar_dates = BTreeSet::new();
    let mut raw_by_asset = BTreeMap::<String, Vec<(i64, Option<f64>)>>::new();
    for ((date, asset), ret) in dates
        .physical()
        .iter()
        .zip(assets.iter())
        .zip(returns_values.iter())
    {
        let (Some(date), Some(asset)) = (date, asset) else {
            return Err(FerricAlphaError::NullKey);
        };
        if !seen.insert((date, asset.to_owned())) {
            return Err(FerricAlphaError::DuplicateKey);
        }
        calendar_dates.insert(date);
        raw_by_asset
            .entry(asset.to_owned())
            .or_default()
            .push((date, ret.filter(|value| value.is_finite())));
    }

    let calendar_dates = calendar_dates.into_iter().collect::<Vec<_>>();
    let mut values = HashMap::with_capacity(returns.height());
    for (asset, mut rows) in raw_by_asset {
        rows.sort_by_key(|(date, _)| *date);
        let mut wealth = 1.0;
        for (date, value) in rows {
            let value = if cumulative {
                value
            } else {
                let ret = value.unwrap_or(0.0);
                wealth *= 1.0 + ret;
                Some(wealth)
            };
            values.insert((asset.clone(), date), value);
        }
    }

    Ok(ReturnCalendar {
        dates: calendar_dates,
        values,
    })
}

fn return_value(calendar: &ReturnCalendar, date: i64, asset: &str) -> Option<f64> {
    calendar
        .values
        .get(&(asset.to_owned(), date))
        .copied()
        .flatten()
}