polars_core/chunked_array/ops/
rolling_window.rs

1use std::hash::{Hash, Hasher};
2
3use polars_compute::rolling::RollingFnParams;
4#[cfg(feature = "serde")]
5use serde::{Deserialize, Serialize};
6
7#[derive(Clone, Debug)]
8#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
9#[cfg_attr(feature = "dsl-schema", derive(schemars::JsonSchema))]
10#[cfg_attr(feature = "rolling_window", derive(PartialEq))]
11pub struct RollingOptionsFixedWindow {
12    /// The length of the window.
13    pub window_size: usize,
14    /// Amount of elements in the window that should be filled before computing a result.
15    pub min_periods: usize,
16    /// An optional slice with the same length as the window that will be multiplied
17    ///              elementwise with the values in the window.
18    pub weights: Option<Vec<f64>>,
19    /// Set the labels at the center of the window.
20    pub center: bool,
21    /// Optional parameters for the rolling
22    #[cfg_attr(any(feature = "serde", feature = "dsl-schema"), serde(default))]
23    pub fn_params: Option<RollingFnParams>,
24}
25
26impl Hash for RollingOptionsFixedWindow {
27    fn hash<H: Hasher>(&self, state: &mut H) {
28        self.window_size.hash(state);
29        self.min_periods.hash(state);
30        self.center.hash(state);
31        self.weights.is_some().hash(state);
32    }
33}
34
35impl Default for RollingOptionsFixedWindow {
36    fn default() -> Self {
37        RollingOptionsFixedWindow {
38            window_size: 3,
39            min_periods: 1,
40            weights: None,
41            center: false,
42            fn_params: None,
43        }
44    }
45}
46
47#[cfg(feature = "rolling_window")]
48mod inner_mod {
49    use num_traits::Zero;
50
51    use crate::chunked_array::cast::CastOptions;
52    use crate::prelude::*;
53
54    /// utility
55    fn check_input(window_size: usize, min_periods: usize) -> PolarsResult<()> {
56        polars_ensure!(
57            min_periods <= window_size,
58            ComputeError: "`window_size`: {} should be >= `min_periods`: {}",
59            window_size, min_periods
60        );
61        Ok(())
62    }
63
64    /// utility
65    fn window_edges(idx: usize, len: usize, window_size: usize, center: bool) -> (usize, usize) {
66        let (start, end) = if center {
67            let right_window = window_size.div_ceil(2);
68            (
69                idx.saturating_sub(window_size - right_window),
70                len.min(idx + right_window),
71            )
72        } else {
73            (idx.saturating_sub(window_size - 1), idx + 1)
74        };
75
76        (start, end - start)
77    }
78
79    impl<T: PolarsNumericType> ChunkRollApply for ChunkedArray<T> {
80        /// Apply a rolling custom function. This is pretty slow because of dynamic dispatch.
81        fn rolling_map(
82            &self,
83            f: &dyn Fn(&Series) -> PolarsResult<Series>,
84            mut options: RollingOptionsFixedWindow,
85        ) -> PolarsResult<Series> {
86            check_input(options.window_size, options.min_periods)?;
87
88            let ca = self.rechunk();
89            if options.weights.is_some() && !self.dtype().is_float() {
90                let s = self.cast_with_options(&DataType::Float64, CastOptions::NonStrict)?;
91                return s.rolling_map(f, options);
92            }
93
94            options.window_size = std::cmp::min(self.len(), options.window_size);
95
96            let len = self.len();
97            let arr = ca.downcast_as_array();
98            let mut ca = ChunkedArray::<T>::from_slice(PlSmallStr::EMPTY, &[T::Native::zero()]);
99            let ptr = ca.chunks[0].as_mut() as *mut dyn Array as *mut PrimitiveArray<T::Native>;
100            let mut series_container = ca.into_series();
101
102            let mut builder = PrimitiveChunkedBuilder::<T>::new(self.name().clone(), self.len());
103
104            if let Some(weights) = options.weights {
105                let weights_series =
106                    Float64Chunked::new(PlSmallStr::from_static("weights"), &weights).into_series();
107
108                let weights_series = weights_series.cast(self.dtype()).unwrap();
109
110                for idx in 0..len {
111                    let (start, size) = window_edges(idx, len, options.window_size, options.center);
112
113                    if size < options.min_periods {
114                        builder.append_null();
115                    } else {
116                        // SAFETY:
117                        // we are in bounds
118                        let arr_window = unsafe { arr.slice_typed_unchecked(start, size) };
119
120                        // ensure we still meet window size criteria after removing null values
121                        if size - arr_window.null_count() < options.min_periods {
122                            builder.append_null();
123                            continue;
124                        }
125
126                        // SAFETY.
127                        // ptr is not dropped as we are in scope
128                        // We are also the only owner of the contents of the Arc
129                        // we do this to reduce heap allocs.
130                        unsafe {
131                            *ptr = arr_window;
132                        }
133                        // reset flags as we reuse this container
134                        series_container.clear_flags();
135                        // ensure the length is correct
136                        series_container._get_inner_mut().compute_len();
137                        let s = if size == options.window_size {
138                            f(&series_container.multiply(&weights_series).unwrap())?
139                        } else {
140                            // Determine which side to slice weights from
141                            let weights_cutoff: Series = match self.dtype() {
142                                DataType::Float64 => {
143                                    let ws = weights_series.f64().unwrap();
144                                    if start == 0 {
145                                        ws.slice(
146                                            (ws.len() - series_container.len()) as i64,
147                                            series_container.len(),
148                                        )
149                                        .into_series()
150                                    } else {
151                                        ws.slice(0, series_container.len()).into_series()
152                                    }
153                                },
154                                _ => {
155                                    let ws = weights_series.f32().unwrap();
156                                    if start == 0 {
157                                        ws.slice(
158                                            (ws.len() - series_container.len()) as i64,
159                                            series_container.len(),
160                                        )
161                                        .into_series()
162                                    } else {
163                                        ws.slice(0, series_container.len()).into_series()
164                                    }
165                                },
166                            };
167                            f(&series_container.multiply(&weights_cutoff).unwrap())?
168                        };
169
170                        let out = self.unpack_series_matching_type(&s)?;
171                        builder.append_option(out.get(0));
172                    }
173                }
174
175                Ok(builder.finish().into_series())
176            } else {
177                for idx in 0..len {
178                    let (start, size) = window_edges(idx, len, options.window_size, options.center);
179
180                    if size < options.min_periods {
181                        builder.append_null();
182                    } else {
183                        // SAFETY:
184                        // we are in bounds
185                        let arr_window = unsafe { arr.slice_typed_unchecked(start, size) };
186
187                        // ensure we still meet window size criteria after removing null values
188                        if size - arr_window.null_count() < options.min_periods {
189                            builder.append_null();
190                            continue;
191                        }
192
193                        // SAFETY.
194                        // ptr is not dropped as we are in scope
195                        // We are also the only owner of the contents of the Arc
196                        // we do this to reduce heap allocs.
197                        unsafe {
198                            *ptr = arr_window;
199                        }
200                        // reset flags as we reuse this container
201                        series_container.clear_flags();
202                        // ensure the length is correct
203                        series_container._get_inner_mut().compute_len();
204                        let s = f(&series_container)?;
205                        let out = self.unpack_series_matching_type(&s)?;
206                        builder.append_option(out.get(0));
207                    }
208                }
209
210                Ok(builder.finish().into_series())
211            }
212        }
213    }
214}
polars_core/chunked_array/ops/rolling_window.rs

polars_core/chunked_array/ops/
rolling_window.rs
