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}