ferric-alpha 0.1.0

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

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

use crate::data::required_column;
use crate::error::{FerricAlphaError, Result};
use crate::performance::frame::date_column;
use crate::performance::portfolio::filter_factor_data;
use crate::performance::{PortfolioOptions, WeightOptions};
use crate::{Period, factor_cumulative_returns, factor_positions, factor_returns};

#[derive(Debug, Clone)]
pub struct PyfolioInput {
    pub returns: DataFrame,
    pub positions: DataFrame,
    pub benchmark: Option<DataFrame>,
}

pub fn create_pyfolio_input(
    factor_data: &DataFrame,
    period: Period,
    capital: Option<f64>,
    options: PortfolioOptions,
    benchmark_period: Option<Period>,
    sessions: Option<&DataFrame>,
) -> Result<PyfolioInput> {
    if capital.is_some_and(|capital| !capital.is_finite() || capital <= 0.0) {
        return Err(FerricAlphaError::InvalidOption {
            option: "capital",
            reason: "capital must be finite and positive",
        });
    }

    let wealth = if period.count() == 1 {
        factor_cumulative_returns(factor_data, period, options.clone())?
    } else {
        overlapping_daily_wealth(factor_data, period, options.clone(), sessions)?
    };
    let returns = changes_from_wealth(&wealth, "return")?;
    let mut positions = factor_positions(factor_data, period, options, sessions)?;
    if let Some(capital) = capital {
        positions = scale_positions(&positions, &wealth, capital)?;
    }

    let benchmark = benchmark_period
        .filter(|period| {
            factor_data
                .column(&format!("forward_return_{}", period.label()))
                .is_ok()
        })
        .map(|period| {
            let benchmark_options = PortfolioOptions::default().with_weight_options(
                WeightOptions::default()
                    .with_demeaned(false)
                    .with_group_adjust(false)
                    .with_equal_weight(true),
            );
            let benchmark_wealth =
                factor_cumulative_returns(factor_data, period, benchmark_options)?;
            changes_from_wealth(&benchmark_wealth, "benchmark")
        })
        .transpose()?;

    Ok(PyfolioInput {
        returns,
        positions,
        benchmark,
    })
}

#[derive(Debug)]
struct ActiveReturnSleeve {
    expiry_index: usize,
    daily_return: f64,
}

fn overlapping_daily_wealth(
    factor_data: &DataFrame,
    period: Period,
    options: PortfolioOptions,
    sessions: Option<&DataFrame>,
) -> Result<DataFrame> {
    let filtered = filter_factor_data(factor_data, &options)?;
    let returns = factor_returns(
        &filtered,
        crate::performance::ReturnOptions::default().with_weight_options(options.weight_options),
    )?;
    let period_label = period.label();
    let dates = returns
        .column("date")?
        .as_materialized_series()
        .datetime()?;
    let periods = returns.column("period")?.as_materialized_series().str()?;
    let values = returns
        .column("factor_return")?
        .as_materialized_series()
        .f64()?;
    let date_dtype = returns.column("date")?.dtype().clone();
    let mut returns_by_date = BTreeMap::new();
    for index in 0..returns.height() {
        if periods.get(index) != Some(period_label.as_str()) {
            continue;
        }
        let date = dates
            .physical()
            .get(index)
            .ok_or(FerricAlphaError::NullKey)?;
        if returns_by_date
            .insert(date, values.get(index).filter(|value| value.is_finite()))
            .is_some()
        {
            return Err(FerricAlphaError::DuplicateKey);
        }
    }
    let session_values = pyfolio_sessions(sessions, &date_dtype, returns_by_date.keys().copied())?;
    let mut active = Vec::<ActiveReturnSleeve>::new();
    let mut output_dates = Vec::with_capacity(session_values.len());
    let mut output_wealth = Vec::with_capacity(session_values.len());
    let mut wealth = 1.0;

    for (session_index, session_date) in session_values.iter().enumerate() {
        active.retain(|sleeve| sleeve.expiry_index > session_index);
        if let Some(Some(forward_return)) = returns_by_date.get(session_date).copied() {
            let base = 1.0 + forward_return;
            if !base.is_finite() || base < 0.0 {
                return Err(FerricAlphaError::InvalidInput {
                    operation: "create_pyfolio_input",
                    reason: "forward return cannot be converted to daily sleeve return",
                });
            }
            active.push(ActiveReturnSleeve {
                expiry_index: session_index.saturating_add(period.count() as usize),
                daily_return: base.powf(1.0 / period.count() as f64) - 1.0,
            });
        }

        output_dates.push(*session_date);
        output_wealth.push(wealth);
        if !active.is_empty() {
            let daily_return =
                active.iter().map(|sleeve| sleeve.daily_return).sum::<f64>() / active.len() as f64;
            wealth *= 1.0 + daily_return;
            if !wealth.is_finite() {
                return Err(FerricAlphaError::InvalidInput {
                    operation: "create_pyfolio_input",
                    reason: "portfolio wealth must remain finite",
                });
            }
        }
    }

    let frame = DataFrame::new(
        output_dates.len(),
        vec![
            date_column("date", output_dates, &date_dtype)?,
            Series::new("cumulative_return".into(), output_wealth).into(),
        ],
    )?;
    Ok(frame.sort(["date"], SortMultipleOptions::default())?)
}

fn pyfolio_sessions(
    sessions: Option<&DataFrame>,
    date_dtype: &DataType,
    inferred: impl Iterator<Item = i64>,
) -> Result<Vec<i64>> {
    let Some(sessions) = sessions else {
        return Ok(inferred.collect::<BTreeSet<_>>().into_iter().collect());
    };
    if sessions.width() != 1 {
        return Err(FerricAlphaError::InvalidInput {
            operation: "create_pyfolio_input",
            reason: "sessions must contain exactly one date column",
        });
    }
    let date = required_column(sessions, "date")?;
    if !matches!(date.dtype(), DataType::Datetime(_, _)) {
        return Err(FerricAlphaError::InvalidDtype {
            column: "date",
            expected: "Datetime",
            actual: date.dtype().to_string(),
        });
    }
    if date.dtype() != date_dtype {
        return Err(FerricAlphaError::TimezoneMismatch);
    }
    if date.null_count() > 0 {
        return Err(FerricAlphaError::NullKey);
    }
    let values = date
        .as_materialized_series()
        .datetime()?
        .physical()
        .iter()
        .map(|value| value.expect("validated session date"))
        .collect::<BTreeSet<_>>();
    Ok(values.into_iter().collect())
}

fn changes_from_wealth(wealth: &DataFrame, name: &str) -> Result<DataFrame> {
    let values = wealth
        .column("cumulative_return")?
        .as_materialized_series()
        .f64()?;
    let mut returns = Vec::with_capacity(wealth.height());
    let mut previous: Option<f64> = None;
    for value in values.iter() {
        let value = value.ok_or(FerricAlphaError::InvalidInput {
            operation: "create_pyfolio_input",
            reason: "cumulative wealth must not contain null values",
        })?;
        let change = match previous {
            None => 0.0,
            Some(previous) if previous != 0.0 => value / previous - 1.0,
            Some(_) => {
                return Err(FerricAlphaError::InvalidInput {
                    operation: "create_pyfolio_input",
                    reason: "cannot compute return after zero wealth",
                });
            }
        };
        if !change.is_finite() {
            return Err(FerricAlphaError::InvalidInput {
                operation: "create_pyfolio_input",
                reason: "portfolio returns must remain finite",
            });
        }
        returns.push(change);
        previous = Some(value);
    }
    Ok(DataFrame::new(
        wealth.height(),
        vec![
            wealth.column("date")?.clone(),
            Series::new(name.into(), returns).into(),
        ],
    )?)
}

fn scale_positions(positions: &DataFrame, wealth: &DataFrame, capital: f64) -> Result<DataFrame> {
    let wealth_dates = wealth.column("date")?.as_materialized_series().datetime()?;
    let wealth_values = wealth
        .column("cumulative_return")?
        .as_materialized_series()
        .f64()?;
    let wealth_by_date = wealth_dates
        .physical()
        .iter()
        .zip(wealth_values.iter())
        .map(|(date, value)| {
            Ok((
                date.ok_or(FerricAlphaError::NullKey)?,
                value.ok_or(FerricAlphaError::InvalidInput {
                    operation: "create_pyfolio_input",
                    reason: "cumulative wealth must not contain null values",
                })?,
            ))
        })
        .collect::<Result<BTreeMap<_, _>>>()?;
    let position_dates = positions
        .column("date")?
        .as_materialized_series()
        .datetime()?;
    let position_values = positions
        .column("position")?
        .as_materialized_series()
        .f64()?;
    let scaled = position_dates
        .physical()
        .iter()
        .zip(position_values.iter())
        .map(|(date, position)| {
            let date = date.ok_or(FerricAlphaError::NullKey)?;
            let wealth = wealth_by_date
                .range(..=date)
                .next_back()
                .map(|(_, wealth)| *wealth)
                .unwrap_or(1.0);
            let scaled = position.ok_or(FerricAlphaError::InvalidInput {
                operation: "create_pyfolio_input",
                reason: "positions must not contain null values",
            })? * wealth
                * capital;
            if scaled.is_finite() {
                Ok(scaled)
            } else {
                Err(FerricAlphaError::InvalidInput {
                    operation: "create_pyfolio_input",
                    reason: "capital positions must remain finite",
                })
            }
        })
        .collect::<Result<Vec<_>>>()?;

    Ok(DataFrame::new(
        positions.height(),
        vec![
            positions.column("date")?.clone(),
            positions.column("asset")?.clone(),
            Series::new("position".into(), scaled).into(),
        ],
    )?)
}