numpy-groupies

0.11.3 · active · verified Mon Apr 13

Numpy-groupies is a Python library offering optimized tools for group-indexing operations, most notably the `aggregate` function. It provides a highly performant and lightweight alternative to operations like `pandas.groupby` for specific use cases, with implementations leveraging plain NumPy, Numba, and sometimes Weave for speed. The current version is 0.11.3, and it receives active maintenance and updates.

Warnings

gotcha For optimal performance, `numba` should be installed. Without it, `numpy-groupies` will automatically fall back to a slower NumPy-only implementation, potentially leading to unexpected performance degradation.
Fix: Install `numba`: `pip install numba` alongside `numpy-groupies`.
breaking Users upgrading to NumPy 2.0 should verify `numpy-groupies` compatibility. NumPy 2.0 introduces significant breaking changes, including an ABI break, changes to type promotion rules, and API modifications that may affect packages depending on it.
Fix: Ensure `numpy-groupies` is updated to a version explicitly supporting NumPy 2.0 (check release notes) or pin `numpy` to <2.0.0 if compatibility issues arise.
gotcha When using the `aggregate` function with multidimensional arrays and the `axis` argument, carefully review the documentation regarding different 'Forms' of inputs and outputs. The behavior, especially concerning output shapes and broadcasting, can be complex and non-obvious.
Fix: Consult the official `numpy-groupies` documentation, particularly the sections describing `aggregate` input 'Forms' and the `axis` parameter, to understand the expected output shape and behavior. Experiment with small examples.
gotcha The interaction of `fill_value` and `dtype` parameters in `aggregate` can lead to implicit type coercion. If `dtype=None`, a 'sensible type' is chosen, which might not always align with user expectations, especially when handling `NaN` values or mixed data types.
Fix: Explicitly specify the desired `dtype` for the output array to prevent unexpected type conversions. Test `fill_value` behavior with your data types.

Install

pip install numpy-groupies Install stable version

Imports

aggregate
```
from numpy_groupies import aggregate
```
The recommended pattern is to import `aggregate` directly from the top-level package, which automatically selects the best available implementation (e.g., NumPy or Numba).

Quickstart

This quickstart demonstrates the core `aggregate` function, showing how to group values by an index array and apply common aggregation functions like sum, count, and mean. The `fill_value` parameter sets the value for groups that do not appear in `group_idx`.

import numpy as np
from numpy_groupies import aggregate

# Example data: values 'a' to be grouped by 'group_idx'
group_idx = np.array([3, 0, 0, 1, 0, 3, 5, 5, 0, 4])
a = np.array([13.2, 3.5, 3.5, -8.2, 3.0, 13.4, 99.2, -7.1, 0.0, 53.7])

# Aggregate sum for each group
result_sum = aggregate(group_idx, a, func='sum', fill_value=0)
print(f"Aggregated sum: {result_sum}")
# Expected: [10.  -8.2  0.  26.6 53.7 92.1]

# Aggregate count of elements in each group
result_count = aggregate(group_idx, a, func='count', fill_value=0)
print(f"Aggregated count: {result_count}")
# Expected: [4 1 0 2 1 2]

# Aggregate mean of values in each group
result_mean = aggregate(group_idx, a, func='mean', fill_value=0)
print(f"Aggregated mean: {result_mean}")
# Expected: [ 2.5   -8.2    0.   13.35 53.7  46.05]

view raw JSON →