Skip to main content

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_samples: 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_samples.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_samples: 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_samples: usize) -> PolarsResult<()> {
56        polars_ensure!(
57            min_samples <= window_size,
58            ComputeError: "`window_size`: {} should be >= `min_samples`: {}",
59            window_size, min_samples
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_samples)?;
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_samples {
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_samples {
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(Slice::tail(series_container.len())).into_series()
146                                    } else {
147                                        ws.slice(Slice::head(series_container.len())).into_series()
148                                    }
149                                },
150                                _ => {
151                                    let ws = weights_series.f32().unwrap();
152                                    if start == 0 {
153                                        ws.slice(Slice::tail(series_container.len())).into_series()
154                                    } else {
155                                        ws.slice(Slice::head(series_container.len())).into_series()
156                                    }
157                                },
158                            };
159                            f(&series_container.multiply(&weights_cutoff).unwrap())?
160                        };
161
162                        let out = self.unpack_series_matching_type(&s)?;
163                        builder.append_option(out.get(0));
164                    }
165                }
166
167                Ok(builder.finish().into_series())
168            } else {
169                for idx in 0..len {
170                    let (start, size) = window_edges(idx, len, options.window_size, options.center);
171
172                    if size < options.min_samples {
173                        builder.append_null();
174                    } else {
175                        // SAFETY:
176                        // we are in bounds
177                        let arr_window = unsafe { arr.slice_typed_unchecked(start, size) };
178
179                        // ensure we still meet window size criteria after removing null values
180                        if size - arr_window.null_count() < options.min_samples {
181                            builder.append_null();
182                            continue;
183                        }
184
185                        // SAFETY.
186                        // ptr is not dropped as we are in scope
187                        // We are also the only owner of the contents of the Arc
188                        // we do this to reduce heap allocs.
189                        unsafe {
190                            *ptr = arr_window;
191                        }
192                        // reset flags as we reuse this container
193                        series_container.clear_flags();
194                        // ensure the length is correct
195                        series_container._get_inner_mut().compute_len();
196                        let s = f(&series_container)?;
197                        let out = self.unpack_series_matching_type(&s)?;
198                        builder.append_option(out.get(0));
199                    }
200                }
201
202                Ok(builder.finish().into_series())
203            }
204        }
205    }
206}