Struct SeriesGroupBy 

pub struct SeriesGroupBy<'a> { /* private fields */ }

GroupBy for Series, grouping by values of another Series.

Created by Series::groupby(by). Supports standard aggregation methods that return a new Series indexed by group keys.

Implementations

impl SeriesGroupBy<'_>

pub fn keys(&self) -> Vec<IndexLabel>

Group labels in first-seen order.

pub fn indices(&self) -> HashMap<IndexLabel, Vec<usize>>

Mapping from group labels to source row positions.

pub fn groups(&self) -> HashMap<IndexLabel, Vec<usize>>

Alias for indices, matching pandas’ groups property shape.

pub fn grouper(&self) -> String

Name of the Series used as the grouper.

pub fn level(&self) -> Option<String>

Grouping level descriptor.

Series::groupby(by) currently groups by a supplied Series rather than by an index level, so this mirrors pandas’ None level state.

pub fn plot(&self) -> Result<PlotSpec, FrameError>

Return a backend-neutral pandas-style grouped plotting request.

pub fn hist(&self) -> Result<HistogramSpec, FrameError>

Return a backend-neutral pandas-style grouped histogram request.

pub fn ngroups(&self) -> usize

Number of groups.

pub fn ndim(&self) -> usize

Grouped object dimensionality.

pub fn dtype(&self) -> DType

DType of the grouped values.

pub fn sum(&self) -> Result<Series, FrameError>

Sum of each group.

pub fn mean(&self) -> Result<Series, FrameError>

Mean of each group.

pub fn count(&self) -> Result<Series, FrameError>

Count of non-null values in each group.

pub fn min(&self) -> Result<Series, FrameError>

Minimum of each group.

pub fn max(&self) -> Result<Series, FrameError>

Maximum of each group.

pub fn any(&self) -> Result<Series, FrameError>

Whether any non-missing value is truthy in each group.

pub fn all(&self) -> Result<Series, FrameError>

Whether all non-missing values are truthy in each group.

pub fn nunique(&self) -> Result<Series, FrameError>

Number of unique non-missing values in each group.

pub fn unique(&self) -> Result<Series, FrameError>

Unique values in each group, preserving first-seen group and value order.

pub fn ohlc(&self) -> Result<DataFrame, FrameError>

Open-high-low-close per group.

pub fn quantile(&self, q: f64) -> Result<Series, FrameError>

Quantile of each group using linear interpolation.

pub fn sem(&self) -> Result<Series, FrameError>

Standard error of the mean for each group.

pub fn skew(&self) -> Result<Series, FrameError>

Skewness of each group.

pub fn kurtosis(&self) -> Result<Series, FrameError>

Excess kurtosis (Fisher’s definition, bias=False) of each group.

Matches pd.Series.groupby(...).kurtosis(). Mirrors fp_types::nankurt which requires at least 4 non-missing values per group; returns Null(NaN) otherwise and when the sample standard deviation is zero.

pub fn kurt(&self) -> Result<Series, FrameError>

Alias for kurtosis() — pandas exposes both .kurt() and .kurtosis() on Series.groupby aggregations, and parity with that surface requires both spellings.

pub fn idxmin(&self) -> Result<Series, FrameError>

Original index label of the minimum value in each group.

pub fn idxmax(&self) -> Result<Series, FrameError>

Original index label of the maximum value in each group.

pub fn is_monotonic_increasing(&self) -> Result<Series, FrameError>

Per-group monotonic-increasing predicate.

pub fn is_monotonic_decreasing(&self) -> Result<Series, FrameError>

Per-group monotonic-decreasing predicate.

pub fn rank( &self, method: &str, ascending: bool, na_option: &str, ) -> Result<Series, FrameError>

Rank values within each group.

Matches series.groupby(by).rank(). method: “average” (default), “min”, “max”, “first”, “dense” ascending: rank direction (default true = smallest gets rank 1) na_option: “keep” (NaN stays NaN), “top” (NaN gets lowest ranks), “bottom” (NaN gets highest ranks)

pub fn rank_with_pct( &self, method: &str, ascending: bool, na_option: &str, pct: bool, ) -> Result<Series, FrameError>

Rank values within each group and optionally scale them to percentile ranks.

pub fn std(&self) -> Result<Series, FrameError>

Standard deviation of each group (ddof=1).

pub fn var(&self) -> Result<Series, FrameError>

Variance of each group (ddof=1).

pub fn median(&self) -> Result<Series, FrameError>

Median of each group.

pub fn prod(&self) -> Result<Series, FrameError>

Product of each group.

pub fn cumcount(&self) -> Result<Series, FrameError>

Assign within-group cumulative count (0-based).

pub fn cumcount_with_ascending( &self, ascending: bool, ) -> Result<Series, FrameError>

Assign within-group cumulative count (0-based) with explicit direction.

pub fn ngroup(&self) -> Result<Series, FrameError>

Assign ordinal group number to each source row.

pub fn ngroup_with_ascending( &self, ascending: bool, ) -> Result<Series, FrameError>

Assign ordinal group number with explicit direction.

pub fn cumsum(&self) -> Result<Series, FrameError>

GroupBy cumulative sum.

pub fn cumprod(&self) -> Result<Series, FrameError>

GroupBy cumulative product.

pub fn cummin(&self) -> Result<Series, FrameError>

GroupBy cumulative minimum.

pub fn cummax(&self) -> Result<Series, FrameError>

GroupBy cumulative maximum.

pub fn shift(&self, periods: i64) -> Result<Series, FrameError>

GroupBy shift within each group.

Examples found in repository

examples/bench_groupby_shift.rs (line 41)

fn main() {
    let args: Vec<String> = std::env::args().collect();
    let n: usize = args.get(1).and_then(|s| s.parse().ok()).unwrap_or(1_000_000);
    let iters: usize = args.get(2).and_then(|s| s.parse().ok()).unwrap_or(30);
    let groups = 100usize;

    let labels: Vec<IndexLabel> = (0..n as i64).map(IndexLabel::Int64).collect();
    let keys: Vec<i64> = (0..n).map(|i| (i % groups) as i64).collect();
    let vals: Vec<f64> = (0..n).map(|i| (i.wrapping_mul(37) % 9973) as f64 * 0.25).collect();
    let value = Series::new(
        "v".to_string(),
        Index::new(labels.clone()),
        Column::from_f64_values(vals),
    )
    .unwrap();
    let key = Series::new(
        "k".to_string(),
        Index::new(labels),
        Column::from_i64_values(keys),
    )
    .unwrap();

    let out = value.groupby(&key).unwrap().shift(1).unwrap();
    let mut chk: u64 = 0xcbf29ce484222325;
    for v in out.values() {
        let bits = match v {
            Scalar::Float64(f) => f.to_bits(),
            _ => 0xDEAD_BEEF_DEAD_BEEF,
        };
        chk = (chk ^ bits).wrapping_mul(0x100000001b3);
    }

    let mut sink = 0usize;
    let start = Instant::now();
    for _ in 0..iters {
        let s = black_box(value.groupby(&key).unwrap().shift(1).unwrap());
        sink ^= s.len();
    }
    let elapsed = start.elapsed();
    println!(
        "groupby_shift n={n} iters={iters}: {:.3} ms/iter (chk={chk:016x} sink={sink})",
        elapsed.as_secs_f64() * 1000.0 / iters as f64
    );
}

pub fn diff(&self, periods: usize) -> Result<Series, FrameError>

GroupBy difference within each group.

pub fn pct_change(&self, periods: usize) -> Result<Series, FrameError>

GroupBy percentage change within each group.

pub fn ffill(&self, limit: Option<usize>) -> Result<Series, FrameError>

Forward-fill missing values within each group.

pub fn bfill(&self, limit: Option<usize>) -> Result<Series, FrameError>

Backward-fill missing values within each group.

pub fn fillna(&self, value: &Scalar) -> Result<Series, FrameError>

Fill missing values in each group with a scalar value.

pub fn rolling(&self, window: usize) -> SeriesGroupByRolling<'_, '_>

Grouped rolling window operations.

Matches the narrow pd.SeriesGroupBy.rolling(window) reduction shape. Results are mapped back onto the original flat Series index.

pub fn expanding( &self, min_periods: Option<usize>, ) -> SeriesGroupByExpanding<'_, '_>

Grouped expanding window operations.

Matches the narrow pd.SeriesGroupBy.expanding(min_periods=...) reduction shape. Results are mapped back onto the original flat Series index.

pub fn ewm( &self, span: Option<f64>, alpha: Option<f64>, ) -> SeriesGroupByEwm<'_, '_>

Grouped exponentially weighted moving window operations.

Matches the narrow pd.SeriesGroupBy.ewm(span=..., alpha=...) reduction shape. Results are mapped back onto the original flat Series index.

pub fn resample(&self, freq: &str) -> SeriesGroupByResample<'_, '_>

Grouped resampling.

Matches the narrow pd.SeriesGroupBy.resample(freq) reduction shape. Until row MultiIndex support is real, group and bucket labels are represented as flat "{group}, {bucket}" labels.

pub fn nlargest(&self, n: usize) -> Result<Series, FrameError>

Return up to n largest non-missing values from each group.

Examples found in repository

examples/bench_take_gather.rs (line 75)

fn golden() -> String {
    let mut out = String::new();

    // Series::take across dtypes, negative + duplicate indices.
    let s = s_i64(vec![10, 20, 30, 40, 50]);
    let r = s.take(&[4, 0, -1, 2, -5, 2]).unwrap();
    out.push_str(&format!("take_lbls={:?}\n", r.index().labels()));
    out.push_str(&format!("take_vals={:?}\n", r.values()));
    out.push_str(&format!("take_oob_err={}\n", s.take(&[99]).is_err()));

    let f = s_scalars(vec![
        Scalar::Float64(1.5),
        Scalar::Float64(f64::NAN),
        Scalar::Float64(-3.0),
    ]);
    out.push_str(&format!(
        "take_f64={:?}\n",
        f.take(&[2, 1, 0]).unwrap().values()
    ));
    let ni = s_scalars(vec![
        Scalar::Int64(7),
        Scalar::Null(NullKind::NaN),
        Scalar::Int64(9),
    ]);
    out.push_str(&format!(
        "take_ni={:?}\n",
        ni.take(&[1, 2, 0]).unwrap().values()
    ));
    let u = s_scalars(
        vec!["a", "b", "c"]
            .into_iter()
            .map(|x| Scalar::Utf8(x.into()))
            .collect(),
    );
    out.push_str(&format!(
        "take_utf8={:?}\n",
        u.take(&[2, -3]).unwrap().values()
    ));

    // SeriesGroupBy gather paths (nlargest / head) route through take_positions.
    let data = s_i64(vec![5, 1, 9, 3, 7, 2, 8]);
    let keys = s_scalars(
        vec!["a", "b", "a", "b", "a", "b", "a"]
            .into_iter()
            .map(|x| Scalar::Utf8(x.into()))
            .collect(),
    );
    let gb = data.groupby(&keys).unwrap();
    let nl = gb.nlargest(2).unwrap();
    out.push_str(&format!("gb_nlargest_lbls={:?}\n", nl.index().labels()));
    out.push_str(&format!("gb_nlargest_vals={:?}\n", nl.values()));
    let hd = data.groupby(&keys).unwrap().head(1).unwrap();
    out.push_str(&format!("gb_head_vals={:?}\n", hd.values()));
    out
}

pub fn nsmallest(&self, n: usize) -> Result<Series, FrameError>

Return up to n smallest non-missing values from each group.

pub fn value_counts(&self) -> Result<Series, FrameError>

Count non-missing values within each group.

pub fn describe(&self) -> Result<DataFrame, FrameError>

Summary statistics per group.

Matches pd.SeriesGroupBy.describe() for numeric grouped values.

pub fn corr(&self, other: &Series) -> Result<Series, FrameError>

Pairwise Pearson correlation with another Series per group.

pub fn cov(&self, other: &Series) -> Result<Series, FrameError>

Pairwise sample covariance with another Series per group.

pub fn transform(&self, func: &str) -> Result<Series, FrameError>

Broadcast a named per-group reduction back to the original Series shape.

Matches series.groupby(by).transform("mean") for supported reduction names. The output keeps the original index and length.

pub fn apply<F>(&self, func: F) -> Result<Series, FrameError>

where F: Fn(&Series) -> Result<Series, FrameError>,

Apply a Series-returning function to each group and concatenate results.

Matches the Rust callback shape for series.groupby(by).apply(func). Returned rows are emitted in the existing SeriesGroupBy first-seen group order, with flat labels retaining both group key and returned index label until Series row MultiIndex metadata exists.

pub fn apply_scalar<F>(&self, name: &str, func: F) -> Result<Series, FrameError>

where F: Fn(&Series) -> Result<Scalar, FrameError>,

Apply a scalar-returning function to each group.

This exposes pandas’ scalar SeriesGroupBy.apply result shape as a typed Rust API: one value per group, indexed by group keys.

pub fn filter<F>(&self, func: F) -> Result<Series, FrameError>

where F: Fn(&Series) -> Result<bool, FrameError>,

Keep or discard whole groups with a caller-supplied predicate.

Matches series.groupby(by).filter(func): the predicate sees one per-group Series and the returned Series preserves the original row order and index labels for groups that pass.

pub fn pipe<T, F>(&self, func: F) -> Result<T, FrameError>

where F: Fn(&Self) -> Result<T, FrameError>,

Pipe this grouped Series through a caller-provided function.

pub fn head(&self, n: i64) -> Result<Series, FrameError>

Select first n rows per group, preserving original row order.

Matches pd.SeriesGroupBy.head(n), including pandas’ negative n: head(-k) keeps all but the last k rows of each group. Verified vs live pandas 2.2.3.

Examples found in repository

examples/bench_take_gather.rs (line 78)

fn golden() -> String {
    let mut out = String::new();

    // Series::take across dtypes, negative + duplicate indices.
    let s = s_i64(vec![10, 20, 30, 40, 50]);
    let r = s.take(&[4, 0, -1, 2, -5, 2]).unwrap();
    out.push_str(&format!("take_lbls={:?}\n", r.index().labels()));
    out.push_str(&format!("take_vals={:?}\n", r.values()));
    out.push_str(&format!("take_oob_err={}\n", s.take(&[99]).is_err()));

    let f = s_scalars(vec![
        Scalar::Float64(1.5),
        Scalar::Float64(f64::NAN),
        Scalar::Float64(-3.0),
    ]);
    out.push_str(&format!(
        "take_f64={:?}\n",
        f.take(&[2, 1, 0]).unwrap().values()
    ));
    let ni = s_scalars(vec![
        Scalar::Int64(7),
        Scalar::Null(NullKind::NaN),
        Scalar::Int64(9),
    ]);
    out.push_str(&format!(
        "take_ni={:?}\n",
        ni.take(&[1, 2, 0]).unwrap().values()
    ));
    let u = s_scalars(
        vec!["a", "b", "c"]
            .into_iter()
            .map(|x| Scalar::Utf8(x.into()))
            .collect(),
    );
    out.push_str(&format!(
        "take_utf8={:?}\n",
        u.take(&[2, -3]).unwrap().values()
    ));

    // SeriesGroupBy gather paths (nlargest / head) route through take_positions.
    let data = s_i64(vec![5, 1, 9, 3, 7, 2, 8]);
    let keys = s_scalars(
        vec!["a", "b", "a", "b", "a", "b", "a"]
            .into_iter()
            .map(|x| Scalar::Utf8(x.into()))
            .collect(),
    );
    let gb = data.groupby(&keys).unwrap();
    let nl = gb.nlargest(2).unwrap();
    out.push_str(&format!("gb_nlargest_lbls={:?}\n", nl.index().labels()));
    out.push_str(&format!("gb_nlargest_vals={:?}\n", nl.values()));
    let hd = data.groupby(&keys).unwrap().head(1).unwrap();
    out.push_str(&format!("gb_head_vals={:?}\n", hd.values()));
    out
}

pub fn tail(&self, n: i64) -> Result<Series, FrameError>

Select last n rows per group, preserving original row order.

Matches pd.SeriesGroupBy.tail(n), including pandas’ negative n: tail(-k) drops the first k rows of each group. Verified vs live pandas 2.2.3.

pub fn take(&self, indices: &[i64]) -> Result<Series, FrameError>

Return positional rows from each group.

Matches pd.SeriesGroupBy.take(indices), resolving negative positions relative to each group’s length.

pub fn sample( &self, n: Option<usize>, frac: Option<f64>, replace: bool, seed: Option<u64>, ) -> Result<Series, FrameError>

Randomly sample rows from each group.

Matches pd.SeriesGroupBy.sample(n=..., frac=..., replace=...).

pub fn nth(&self, n: i64) -> Result<Series, FrameError>

Select the nth row from each group. Negative n counts from the end.

pub fn get_group(&self, name: &str) -> Result<Series, FrameError>

Retrieve a single group by its display label.

pub fn first(&self) -> Result<Series, FrameError>

First value of each group.

pub fn last(&self) -> Result<Series, FrameError>

Last value of each group.

pub fn size(&self) -> Result<Series, FrameError>

Number of elements in each group (including nulls).

pub fn agg(&self, funcs: &[&str]) -> Result<DataFrame, FrameError>

Aggregate with multiple functions, returning a DataFrame.

Matches series.groupby(by).agg(['sum', 'mean']). Returns a DataFrame with group keys as index and one column per function.

pub fn aggregate(&self, funcs: &[&str]) -> Result<DataFrame, FrameError>

pandas spelling alias for Self::agg.