{"id":5344,"library":"numpy-groupies","title":"numpy-groupies","description":"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.","status":"active","version":"0.11.3","language":"en","source_language":"en","source_url":"https://github.com/ml31415/numpy-groupies","tags":["numpy","grouping","aggregation","performance","data processing","numba"],"install":[{"cmd":"pip install numpy-groupies","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality relies heavily on NumPy arrays and operations.","package":"numpy","optional":false},{"reason":"Optional dependency for significantly improved performance of aggregation functions through JIT compilation.","package":"numba","optional":true}],"imports":[{"note":"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).","wrong":"import numpy_groupies.aggregate # or from numpy_groupies.aggregate import aggregate","symbol":"aggregate","correct":"from numpy_groupies import aggregate"}],"quickstart":{"code":"import numpy as np\nfrom numpy_groupies import aggregate\n\n# Example data: values 'a' to be grouped by 'group_idx'\ngroup_idx = np.array([3, 0, 0, 1, 0, 3, 5, 5, 0, 4])\na = np.array([13.2, 3.5, 3.5, -8.2, 3.0, 13.4, 99.2, -7.1, 0.0, 53.7])\n\n# Aggregate sum for each group\nresult_sum = aggregate(group_idx, a, func='sum', fill_value=0)\nprint(f\"Aggregated sum: {result_sum}\")\n# Expected: [10.  -8.2  0.  26.6 53.7 92.1]\n\n# Aggregate count of elements in each group\nresult_count = aggregate(group_idx, a, func='count', fill_value=0)\nprint(f\"Aggregated count: {result_count}\")\n# Expected: [4 1 0 2 1 2]\n\n# Aggregate mean of values in each group\nresult_mean = aggregate(group_idx, a, func='mean', fill_value=0)\nprint(f\"Aggregated mean: {result_mean}\")\n# Expected: [ 2.5   -8.2    0.   13.35 53.7  46.05]","lang":"python","description":"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`."},"warnings":[{"fix":"Install `numba`: `pip install numba` alongside `numpy-groupies`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"numpy-groupies < 0.11.x with numpy >= 2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly specify the desired `dtype` for the output array to prevent unexpected type conversions. Test `fill_value` behavior with your data types.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}