Skip to main content

ferric_alpha/
forward_returns.rs

1use std::collections::{BTreeSet, HashMap};
2
3use polars::prelude::{
4    Column, DataFrame, DataType, IntoColumn, NamedFrom, Series, SortMultipleOptions, TimeUnit,
5};
6
7use crate::calendar::{Period, TradingCalendar, validate_periods};
8use crate::data::{ensure_matching_date_timezone, required_column, validate_factor_frame};
9use crate::error::{FerricAlphaError, Result};
10
11#[derive(Debug, Clone, Copy, PartialEq)]
12pub struct ForwardReturnsOptions {
13    pub cumulative_returns: bool,
14    pub filter_zscore: Option<f64>,
15}
16
17impl Default for ForwardReturnsOptions {
18    fn default() -> Self {
19        Self {
20            cumulative_returns: true,
21            filter_zscore: None,
22        }
23    }
24}
25
26pub fn compute_forward_returns(
27    factor: &DataFrame,
28    prices: &DataFrame,
29    periods: &[Period],
30) -> Result<DataFrame> {
31    compute_forward_returns_with_options(factor, prices, periods, ForwardReturnsOptions::default())
32}
33
34pub fn compute_forward_returns_with_options(
35    factor: &DataFrame,
36    prices: &DataFrame,
37    periods: &[Period],
38    options: ForwardReturnsOptions,
39) -> Result<DataFrame> {
40    let periods = validate_periods(periods)?;
41    validate_filter_zscore(options.filter_zscore)?;
42    let date_dtype = ensure_matching_date_timezone(factor, prices)?;
43    let factor = validate_factor_frame(factor)?;
44    let prices = validate_forward_price_frame(prices)?;
45
46    let calendar = calendar_from_prices(&prices)?;
47    let price_lookup = price_lookup(&prices)?;
48    let period_labels = period_labels(&calendar, &periods, &date_dtype);
49
50    let factor_dates = factor.column("date")?.as_materialized_series().datetime()?;
51    let factor_assets = factor.column("asset")?.as_materialized_series().str()?;
52
53    let mut out_dates = Vec::with_capacity(factor.height());
54    let mut out_assets = Vec::with_capacity(factor.height());
55    let mut out_returns = vec![Vec::with_capacity(factor.height()); periods.len()];
56
57    for (date, asset) in factor_dates.physical().iter().zip(factor_assets.iter()) {
58        let date = date.expect("validated factor date should not be null");
59        let asset = asset.expect("validated factor asset should not be null");
60        out_dates.push(date);
61        out_assets.push(asset.to_owned());
62
63        for (period_index, period) in periods.iter().enumerate() {
64            let forward_return = calendar.offset(date, *period).and_then(|terminal_date| {
65                let start_date = if options.cumulative_returns || period.count() == 1 {
66                    date
67                } else {
68                    calendar.offset(date, Period::new(period.count() - 1).ok()?)?
69                };
70                let start = price_lookup
71                    .get(&(asset.to_owned(), start_date))?
72                    .as_ref()?;
73                let end = price_lookup
74                    .get(&(asset.to_owned(), terminal_date))?
75                    .as_ref()?;
76                Some(round_return(end / start - 1.0))
77            });
78            out_returns[period_index].push(forward_return);
79        }
80    }
81    if let Some(filter_zscore) = options.filter_zscore {
82        filter_outlier_forward_returns(&out_assets, &mut out_returns, filter_zscore);
83    }
84
85    let mut columns = vec![
86        datetime_column("date", out_dates, &date_dtype)?,
87        Series::new("asset".into(), out_assets).into(),
88    ];
89    for (label, values) in period_labels.iter().zip(out_returns) {
90        columns.push(Series::new(format!("forward_return_{label}").into(), values).into());
91    }
92
93    Ok(DataFrame::new(factor.height(), columns)?
94        .sort(["date", "asset"], SortMultipleOptions::default())?)
95}
96
97fn validate_filter_zscore(filter_zscore: Option<f64>) -> Result<()> {
98    if let Some(value) = filter_zscore
99        && (!value.is_finite() || value < 0.0)
100    {
101        return Err(FerricAlphaError::InvalidQuantiles {
102            reason: "filter_zscore must be finite and non-negative",
103        });
104    }
105    Ok(())
106}
107
108fn filter_outlier_forward_returns(
109    assets: &[String],
110    returns_by_period: &mut [Vec<Option<f64>>],
111    filter_zscore: f64,
112) {
113    for returns in returns_by_period {
114        let mut values_by_asset: HashMap<&str, Vec<f64>> = HashMap::new();
115        for (asset, value) in assets.iter().zip(returns.iter()) {
116            if let Some(value) = value {
117                values_by_asset
118                    .entry(asset.as_str())
119                    .or_default()
120                    .push(*value);
121            }
122        }
123        let stats_by_asset = values_by_asset
124            .into_iter()
125            .filter_map(|(asset, values)| asset_stats(&values).map(|stats| (asset, stats)))
126            .collect::<HashMap<_, _>>();
127        for (asset, value) in assets.iter().zip(returns.iter_mut()) {
128            let Some(current) = *value else {
129                continue;
130            };
131            let Some((mean, std)) = stats_by_asset.get(asset.as_str()) else {
132                continue;
133            };
134            if (current - mean).abs() > filter_zscore * std {
135                *value = None;
136            }
137        }
138    }
139}
140
141fn asset_stats(values: &[f64]) -> Option<(f64, f64)> {
142    if values.len() < 2 {
143        return None;
144    }
145    let mean = values.iter().sum::<f64>() / values.len() as f64;
146    let variance = values
147        .iter()
148        .map(|value| (value - mean).powi(2))
149        .sum::<f64>()
150        / (values.len() - 1) as f64;
151    let std = variance.sqrt();
152    if std == 0.0 { None } else { Some((mean, std)) }
153}
154
155fn period_labels(calendar: &TradingCalendar, periods: &[Period], dtype: &DataType) -> Vec<String> {
156    let Some(day_units) = units_per_day(dtype) else {
157        return periods.iter().map(|period| period.label()).collect();
158    };
159    if !has_subdaily_sessions(calendar.sessions(), day_units) {
160        return periods.iter().map(|period| period.label()).collect();
161    }
162
163    periods
164        .iter()
165        .map(|period| {
166            period_span(calendar, *period)
167                .and_then(|(start, terminal)| duration_label(calendar, start, terminal, day_units))
168                .unwrap_or_else(|| period.label())
169        })
170        .collect()
171}
172
173fn has_subdaily_sessions(sessions: &[i64], day_units: i64) -> bool {
174    sessions
175        .windows(2)
176        .any(|pair| pair[1] > pair[0] && pair[1] - pair[0] < day_units)
177}
178
179fn period_span(calendar: &TradingCalendar, period: Period) -> Option<(i64, i64)> {
180    calendar.sessions().iter().copied().find_map(|date| {
181        calendar
182            .offset(date, period)
183            .map(|terminal| (date, terminal))
184    })
185}
186
187fn duration_label(
188    calendar: &TradingCalendar,
189    start: i64,
190    terminal: i64,
191    day_units: i64,
192) -> Option<String> {
193    let delta = terminal - start;
194    if delta <= 0 {
195        return None;
196    }
197    if delta >= day_units && start.rem_euclid(day_units) == terminal.rem_euclid(day_units) {
198        return matching_session_day_label(calendar.sessions(), start, terminal, day_units);
199    }
200    let hour_units = day_units / 24;
201    let minute_units = hour_units / 60;
202    let second_units = minute_units / 60;
203    if delta % day_units == 0 {
204        Some(format!("{}D", delta / day_units))
205    } else if hour_units > 0 && delta % hour_units == 0 {
206        Some(format!("{}h", delta / hour_units))
207    } else if minute_units > 0 && delta % minute_units == 0 {
208        Some(format!("{}m", delta / minute_units))
209    } else if second_units > 0 && delta % second_units == 0 {
210        Some(format!("{}s", delta / second_units))
211    } else {
212        Some(format!("{}ms", delta / (day_units / 86_400_000).max(1)))
213    }
214}
215
216fn matching_session_day_label(
217    sessions: &[i64],
218    start: i64,
219    terminal: i64,
220    day_units: i64,
221) -> Option<String> {
222    let time_of_day = start.rem_euclid(day_units);
223    let day_count = sessions
224        .iter()
225        .copied()
226        .filter(|session| {
227            *session > start && *session <= terminal && session.rem_euclid(day_units) == time_of_day
228        })
229        .count();
230    if day_count == 0 {
231        None
232    } else {
233        Some(format!("{day_count}D"))
234    }
235}
236
237fn units_per_day(dtype: &DataType) -> Option<i64> {
238    match dtype {
239        DataType::Datetime(TimeUnit::Nanoseconds, _) => Some(86_400_000_000_000),
240        DataType::Datetime(TimeUnit::Microseconds, _) => Some(86_400_000_000),
241        DataType::Datetime(TimeUnit::Milliseconds, _) => Some(86_400_000),
242        _ => None,
243    }
244}
245
246fn validate_forward_price_frame(frame: &DataFrame) -> Result<DataFrame> {
247    let date = required_column(frame, "date")?;
248    let asset = required_column(frame, "asset")?;
249    let price = required_column(frame, "price")?;
250
251    if !matches!(date.dtype(), DataType::Datetime(_, _)) {
252        return Err(FerricAlphaError::InvalidDtype {
253            column: "date",
254            expected: "Datetime",
255            actual: date.dtype().to_string(),
256        });
257    }
258    if !matches!(asset.dtype(), DataType::String) {
259        return Err(FerricAlphaError::InvalidDtype {
260            column: "asset",
261            expected: "String",
262            actual: asset.dtype().to_string(),
263        });
264    }
265    if !matches!(price.dtype(), DataType::Float64) {
266        return Err(FerricAlphaError::InvalidDtype {
267            column: "price",
268            expected: "Float64",
269            actual: price.dtype().to_string(),
270        });
271    }
272
273    if date.null_count() > 0 || asset.null_count() > 0 {
274        return Err(FerricAlphaError::NullKey);
275    }
276
277    let dates = date.as_materialized_series().datetime()?;
278    let assets = asset.as_materialized_series().str()?;
279    let prices = price.as_materialized_series().f64()?;
280    let mut keys = BTreeSet::new();
281    for ((date, asset), price) in dates
282        .physical()
283        .iter()
284        .zip(assets.iter())
285        .zip(prices.iter())
286    {
287        let (Some(date), Some(asset)) = (date, asset) else {
288            return Err(FerricAlphaError::NullKey);
289        };
290        if let Some(price) = price
291            && (!price.is_finite() || price <= 0.0)
292        {
293            return Err(FerricAlphaError::InvalidPrice);
294        }
295        if !keys.insert((date, asset)) {
296            return Err(FerricAlphaError::DuplicateKey);
297        }
298    }
299
300    Ok(frame.sort(["date", "asset"], SortMultipleOptions::default())?)
301}
302
303pub(crate) fn datetime_column(name: &str, values: Vec<i64>, dtype: &DataType) -> Result<Column> {
304    match dtype {
305        DataType::Datetime(unit, zone) => Ok(Series::new(name.into(), values)
306            .into_datetime(*unit, zone.clone())
307            .into_column()),
308        actual => Err(crate::error::FerricAlphaError::InvalidDtype {
309            column: "date",
310            expected: "Datetime",
311            actual: actual.to_string(),
312        }),
313    }
314}
315
316fn calendar_from_prices(prices: &DataFrame) -> Result<TradingCalendar> {
317    let date_column = prices.column("date")?.as_materialized_series().datetime()?;
318    let sessions = date_column
319        .physical()
320        .iter()
321        .map(|date| date.expect("validated price date should not be null"))
322        .collect::<BTreeSet<_>>()
323        .into_iter()
324        .collect();
325    let timezone = match prices.column("date")?.dtype() {
326        DataType::Datetime(_, zone) => zone.as_ref().map(ToString::to_string),
327        _ => None,
328    };
329    TradingCalendar::new(sessions, timezone)
330}
331
332fn price_lookup(prices: &DataFrame) -> Result<HashMap<(String, i64), Option<f64>>> {
333    let dates = prices.column("date")?.as_materialized_series().datetime()?;
334    let assets = prices.column("asset")?.as_materialized_series().str()?;
335    let prices = prices.column("price")?.as_materialized_series().f64()?;
336    let mut lookup = HashMap::with_capacity(prices.len());
337    for ((date, asset), price) in dates
338        .physical()
339        .iter()
340        .zip(assets.iter())
341        .zip(prices.iter())
342    {
343        let date = date.expect("validated price date should not be null");
344        let asset = asset.expect("validated price asset should not be null");
345        lookup.insert((asset.to_owned(), date), price);
346    }
347    Ok(lookup)
348}
349
350fn round_return(value: f64) -> f64 {
351    (value * 1_000_000_000_000.0).round() / 1_000_000_000_000.0
352}