ferric-alpha-render 0.1.0

Native rendering for Ferric Alpha alphalens-style tear-sheet reports
Documentation
mod catalog;
mod layout;

use std::collections::{HashMap, HashSet};

use ferric_alpha::{ReportKind, ReportTable, TearSheetData};
use serde::{Deserialize, Serialize};

use crate::{
    MAX_LOGICAL_HEIGHT, MAX_PANELS, MAX_WIDTH, MIN_WIDTH, RENDER_PLAN_VERSION, RenderError,
    RenderResult,
};
use crate::{RenderOptions, RenderTheme};

pub use catalog::plan_report;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RenderPlan {
    pub contract_version: String,
    pub report_kind: ReportKind,
    pub title: String,
    pub width: u32,
    pub height: u32,
    pub theme: RenderTheme,
    pub panels: Vec<PanelPlan>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PanelPlan {
    pub id: String,
    pub title: String,
    pub row: u32,
    pub column: u8,
    pub column_span: u8,
    pub height: u32,
    pub table_ids: Vec<String>,
    pub kind: PanelKind,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum PanelKind {
    Table,
    QuantileReturnsBar { by_group: bool },
    QuantileReturnsDistribution { samples: u32 },
    CumulativeReturns { by_quantile: bool },
    MeanSpread,
    IcTimeSeries,
    IcHistogram { bins: u32 },
    IcQq,
    IcMonthlyHeatmap,
    IcByGroup,
    QuantileTurnover { period: String },
    RankAutocorrelation { period: String },
    EventDistribution,
    EventAverageCumulative { by_group: bool },
}

impl RenderPlan {
    pub fn new(
        report_kind: ReportKind,
        title: impl Into<String>,
        options: &RenderOptions,
        panels: Vec<PanelPlan>,
    ) -> RenderResult<Self> {
        validate_plan_options(options)?;
        let panels = layout::assign_layout(options.width, panels)?;
        let height = layout::total_height(&panels)?;
        Ok(Self {
            contract_version: RENDER_PLAN_VERSION.to_string(),
            report_kind,
            title: title.into(),
            width: options.width,
            height,
            theme: options.theme,
            panels,
        })
    }

    pub fn to_json(&self) -> RenderResult<String> {
        serde_json::to_string(self).map_err(|error| RenderError::Backend {
            format: "render-plan",
            message: error.to_string(),
        })
    }

    pub fn validate(&self, report: &TearSheetData) -> RenderResult<()> {
        if self.contract_version != RENDER_PLAN_VERSION {
            return invalid_contract("invalid render-plan contract version");
        }
        if self.report_kind != report.metadata().report_kind() {
            return invalid_contract("report kind mismatch");
        }
        if self.panels.len() > MAX_PANELS || self.height > MAX_LOGICAL_HEIGHT {
            return Err(RenderError::LayoutOverflow);
        }

        let table_map = report
            .table_ids()
            .into_iter()
            .filter_map(|id| report.table(id).map(|table| (id, table)))
            .collect::<HashMap<_, _>>();
        let mut seen_ids = HashSet::with_capacity(self.panels.len());
        let mut rows = HashMap::<u32, Vec<&PanelPlan>>::new();

        for panel in &self.panels {
            if panel.id.is_empty() || !seen_ids.insert(panel.id.as_str()) {
                return invalid_contract("duplicate panel id");
            }
            if panel.column != 0 && panel.column != 6 {
                return invalid_contract("invalid panel column");
            }
            if panel.column_span != 6 && panel.column_span != 12 {
                return invalid_contract("invalid panel span");
            }
            if panel.column + panel.column_span > 12 {
                return invalid_contract("panel row overflow");
            }
            if panel.table_ids.is_empty() {
                return invalid_contract("panel has no table ids");
            }
            for table_id in &panel.table_ids {
                let table = table_map.get(table_id.as_str()).copied().ok_or_else(|| {
                    RenderError::MissingTable {
                        id: table_id.clone(),
                    }
                })?;
                validate_panel_table(panel, table)?;
            }
            rows.entry(panel.row).or_default().push(panel);
        }

        let max_row = rows.keys().copied().max().unwrap_or(0);
        for row in 0..=max_row {
            let panels = rows.get(&row).ok_or_else(|| RenderError::InvalidContract {
                reason: "missing layout row".to_string(),
            })?;
            let first_height = panels[0].height;
            if panels.iter().any(|panel| panel.height != first_height) {
                return invalid_contract("unequal panel heights in row");
            }
            for (index, left) in panels.iter().enumerate() {
                for right in panels.iter().skip(index + 1) {
                    let left_end = left.column + left.column_span;
                    let right_end = right.column + right.column_span;
                    if left.column < right_end && right.column < left_end {
                        return invalid_contract("panel row overlap");
                    }
                }
            }
        }

        Ok(())
    }
}

pub(crate) fn panel(
    id: impl Into<String>,
    title: impl Into<String>,
    column_span: u8,
    height: u32,
    table_ids: Vec<&str>,
    kind: PanelKind,
) -> PanelPlan {
    PanelPlan {
        id: id.into(),
        title: title.into(),
        row: 0,
        column: 0,
        column_span,
        height,
        table_ids: table_ids.into_iter().map(ToOwned::to_owned).collect(),
        kind,
    }
}

fn validate_panel_table(panel: &PanelPlan, table: &ReportTable) -> RenderResult<()> {
    if table.columns().is_empty() {
        return invalid_contract("table panel has no columns");
    }
    match &panel.kind {
        PanelKind::Table => Ok(()),
        PanelKind::QuantileReturnsBar { by_group } => {
            require_columns(table, &["factor_quantile", "period", "mean_return"])?;
            if *by_group {
                require_columns(table, &["group"])?;
            }
            Ok(())
        }
        PanelKind::QuantileReturnsDistribution { .. } => {
            require_columns(table, &["date", "factor_quantile", "period", "mean_return"])
        }
        PanelKind::CumulativeReturns { by_quantile } => {
            let mut columns = vec!["date"];
            if *by_quantile {
                columns.push("factor_quantile");
            }
            columns.push("cumulative_return");
            require_columns(table, &columns)
        }
        PanelKind::MeanSpread => {
            require_columns(table, &["date", "period", "mean_return_difference"])
        }
        PanelKind::IcTimeSeries => require_columns(table, &["period"]),
        PanelKind::IcHistogram { .. } => require_columns(table, &["period", "ic"]),
        PanelKind::IcQq => require_columns(table, &["period", "theoretical", "observed"]),
        PanelKind::IcMonthlyHeatmap => {
            require_columns(table, &["time_bucket", "period", "mean_ic"])
        }
        PanelKind::IcByGroup => require_columns(table, &["group", "period", "mean_ic"]),
        PanelKind::QuantileTurnover { .. } => {
            require_columns(table, &["date", "factor_quantile", "period", "turnover"])
        }
        PanelKind::RankAutocorrelation { .. } => {
            require_columns(table, &["date", "period", "autocorrelation"])
        }
        PanelKind::EventDistribution => require_columns(table, &["bin_start", "bin_end"]),
        PanelKind::EventAverageCumulative { by_group } => {
            let mut columns = vec!["factor_quantile", "offset", "mean_cumulative_return"];
            if *by_group {
                columns.push("group");
            }
            require_columns(table, &columns)
        }
    }
}

fn require_columns(table: &ReportTable, columns: &[&str]) -> RenderResult<()> {
    let available = table.column_names();
    for column in columns {
        if !available.contains(column) {
            return Err(RenderError::MissingColumn {
                table: table.id().to_string(),
                column: (*column).to_string(),
            });
        }
    }
    Ok(())
}

fn invalid_contract<T>(reason: &str) -> RenderResult<T> {
    Err(RenderError::InvalidContract {
        reason: reason.to_string(),
    })
}

fn validate_plan_options(options: &RenderOptions) -> RenderResult<()> {
    if !(MIN_WIDTH..=MAX_WIDTH).contains(&options.width) {
        return Err(RenderError::InvalidOption {
            option: "width",
            reason: "must be in 720..=4096",
        });
    }
    if !options.scale.is_finite() || !(0.5..=4.0).contains(&options.scale) {
        return Err(RenderError::InvalidOption {
            option: "scale",
            reason: "must be finite and in 0.5..=4.0",
        });
    }
    Ok(())
}