Module group 

Group-level iteration over a DataFrame key column.

Two rungs, cheapest first:

1. Typed rows, grouped Rust-side — after Vec::<Row>::from_dataframe(&df)?, grouping is plain Rust. group_rows makes the idiom discoverable:

   let rows: Vec<Obs> = Vec::from_dataframe(&df)?;
   let by_site = group_rows(rows, |r| r.site.clone());
   // by_site: BTreeMap<String, Vec<Obs>> — plain Rust data, rayon-safe.

2. Untyped, index-based — DataFrame::group_by computes group indices once (single pass, main thread) without extracting rows:

   let grouped = df.group_by("site")?;
   for (key, rows) in grouped.iter() { /* key: &GroupKey, rows: &[usize] */ }
   let mut out = NamedDataFrameListBuilder::with_capacity(grouped.len());
   for (key, sub) in grouped.frames() {
       out = out.push(key.label(), sub);
   }

Key semantics (vs R split())

• Group order: factor keys follow level order (empty levels kept, like split()); character keys sort in byte order (R sorts in locale collation order — identical for ASCII); integer keys sort numerically; logical keys order FALSE, TRUE.
• NA keys form one group, ordered last — a deliberate deviation from split(), which silently drops NA-keyed rows. A literal NA level (addNA(f)) also surfaces as GroupKey::Na.
• Double key columns are an error: grouping on floating point is a footgun — cut() or factor() the column first.

Structs

GroupedDataFrame

A DataFrame partitioned by the values of one key column.

Enums

GroupKey

The key of one group produced by DataFrame::group_by.

Functions

character_groups 🔒

Character keys: byte-order sort (BTreeMap), NA last.

factor_groups 🔒

Factor fast path: levels are the keys (level order, empty levels kept). NA codes — and a literal NA level from addNA() — land in GroupKey::Na.

group_rows

Group already-extracted rows by a key function.

integer_groups 🔒

Integer keys: numeric sort (BTreeMap), NA (i32::MIN) last.

logical_groups 🔒

Logical keys: FALSE then TRUE (R’s sort order), NA last. Only keys present in the data appear.