{"id":6015,"library":"numbagg","title":"Numbagg: Fast N-dimensional Aggregation","description":"Numbagg provides fast N-dimensional aggregation functions accelerated by Numba's just-in-time (JIT) compiler and NumPy's generalized universal function (gufunc) machinery. It aims to outperform libraries like pandas, bottleneck, and NumPy for certain operations, especially with parallelization. The library is currently at version 0.9.4 and maintains an active development pace with regular updates.","status":"active","version":"0.9.4","language":"en","source_language":"en","source_url":"https://github.com/numbagg/numbagg","tags":["Numba","NumPy","aggregation","performance","array-processing","scientific-computing"],"install":[{"cmd":"pip install numbagg","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for JIT compilation and array function acceleration.","package":"numba"},{"reason":"Fundamental library for N-dimensional array operations.","package":"numpy"}],"imports":[{"symbol":"nansum","correct":"import numbagg\nresult = numbagg.nansum(...)"},{"symbol":"move_mean","correct":"import numbagg\nresult = numbagg.move_mean(...)"},{"note":"The `decorators` module is explicitly noted as *not* part of Numbagg's public API and is subject to change at any time. Direct imports from `numbagg` are preferred for stable functions.","wrong":"import numbagg.decorators.ndreduce","symbol":"ndreduce","correct":"from numbagg.decorators import ndreduce"}],"quickstart":{"code":"import numbagg\nimport numpy as np\n\na = np.array([1, 2, np.nan, 4, 5])\nb = np.random.rand(10, 5)\n\n# Calculate sum, ignoring NaNs\nsum_result = numbagg.nansum(a)\nprint(f\"nansum(a): {sum_result}\")\n\n# Calculate moving mean with a window of 3\nmoving_mean_result = numbagg.move_mean(b, window=3, axis=1)\nprint(f\"move_mean(b, window=3, axis=1, shape): {moving_mean_result.shape}\")","lang":"python","description":"This quickstart demonstrates how to use `numbagg` for basic array aggregation (nansum) and moving window calculations (move_mean) on NumPy arrays. Note that the first call to any numbagg function will incur JIT compilation overhead."},"warnings":[{"fix":"Monitor official releases and change logs for updates on stability and production readiness.","message":"Numbagg is currently considered experimental and not yet ready for production use, as stated on its PyPI page. While robust, its API or internal workings may evolve.","severity":"gotcha","affected_versions":"All versions up to 0.9.4"},{"fix":"Consider a warm-up run with dummy data if predictable performance from the first invocation is critical in a performance-sensitive application.","message":"The first call to any Numbagg function incurs a significant performance penalty due to Numba's Just-In-Time (JIT) compilation. Subsequent calls to the same function with compatible argument types will be much faster.","severity":"gotcha","affected_versions":"All versions up to 0.9.4"},{"fix":"For new projects or complex grouped aggregations, consider evaluating `flox` (especially with its `numbagg` engine option) instead of directly using `numbagg.grouped` functions. Monitor `numbagg` and `xarray` (and `flox`) repositories for updates on this transition.","message":"Numbagg's grouped calculation functions (e.g., `numbagg.grouped.group_nanmean`) might be deprecated in favor of using `flox` with `numbagg` as a backend. This is an ongoing discussion within the xarray community, with `flox` potentially offering better support for nD array grouped by 1D labels.","severity":"deprecated","affected_versions":"Versions 0.9.x"},{"fix":"Avoid direct imports from `numbagg.decorators` for application code. Instead, use the top-level functions directly exposed by the `numbagg` package.","message":"The `numbagg.decorators` module, used internally for creating JIT-compiled aggregation functions, is not part of Numbagg's public API. Its functions and signatures may change without prior notice.","severity":"gotcha","affected_versions":"All versions up to 0.9.4"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}