Bottleneck

Fast NumPy array functions written in C for high-performance numerical computing. Bottleneck provides optimized implementations of statistical functions, moving window operations, ranking functions, and array manipulation utilities, delivering significant speed improvements over standard NumPy implementations.

Package Information

• Package Name: bottleneck
• Language: Python
• Installation: pip install bottleneck

Core Imports

import bottleneck as bn

For testing and benchmarking:

import bottleneck as bn
# Run benchmarks
bn.bench()
# Run tests  
bn.test()

Basic Usage

import bottleneck as bn
import numpy as np

# Create sample data with NaN values
data = np.array([1, 2, np.nan, 4, 5])

# Statistical functions ignore NaN values
mean_val = bn.nanmean(data)  # 3.0
sum_val = bn.nansum(data)    # 12.0
std_val = bn.nanstd(data)    # 1.58...

# Moving window operations
series = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
moving_avg = bn.move_mean(series, window=3, min_count=1)
# array([1. , 1.5, 2. , 3. , 4. , 5. , 6. , 7. , 8. , 9. ])

# Ranking operations
ranks = bn.rankdata([3, 1, 4, 1, 5])  # array([3., 1.5, 4., 1.5, 5.])

# Array manipulation
arr = np.array([1, 2, np.nan, 4, 5])
bn.replace(arr, np.nan, 0)  # Replaces NaN with 0 in-place

Architecture

Bottleneck uses a dual-implementation approach for maximum performance:

• Fast Path: C-optimized implementations for supported data types (int32, int64, float32, float64)
• Slow Path: Pure Python/NumPy fallback implementations for all other data types
• Automatic Selection: Functions automatically choose the optimal implementation based on input array properties

The library automatically falls back to slower implementations for:

• Unsupported data types (e.g., float16, complex types)
• Byte-swapped arrays
• Special array layouts that can't be optimized

This design ensures compatibility with all NumPy arrays while providing significant performance gains where possible.

Capabilities

Reduction Functions

Statistical and aggregation functions that reduce arrays along specified axes, with optimized NaN handling and support for all common statistical operations.

def nansum(a, axis=None): ...
def nanmean(a, axis=None): ...
def nanstd(a, axis=None, ddof=0): ...
def nanvar(a, axis=None, ddof=0): ...
def nanmin(a, axis=None): ...
def nanmax(a, axis=None): ...
def nanargmin(a, axis=None): ...
def nanargmax(a, axis=None): ...
def median(a, axis=None): ...
def nanmedian(a, axis=None): ...
def ss(a, axis=None): ...
def anynan(a, axis=None): ...
def allnan(a, axis=None): ...

Reduction Functions

Moving Window Functions

High-performance moving window operations for time series analysis and sequential data processing, supporting customizable window sizes and minimum count requirements.

def move_sum(a, window, min_count=None, axis=-1): ...
def move_mean(a, window, min_count=None, axis=-1): ...
def move_std(a, window, min_count=None, axis=-1, ddof=0): ...
def move_var(a, window, min_count=None, axis=-1, ddof=0): ...
def move_min(a, window, min_count=None, axis=-1): ...
def move_max(a, window, min_count=None, axis=-1): ...
def move_argmin(a, window, min_count=None, axis=-1): ...
def move_argmax(a, window, min_count=None, axis=-1): ...
def move_median(a, window, min_count=None, axis=-1): ...
def move_rank(a, window, min_count=None, axis=-1): ...

Moving Window Functions

Array Manipulation Functions

Utilities for array transformation, ranking, and data manipulation operations that maintain array structure while modifying values or order.

def replace(a, old, new): ...
def rankdata(a, axis=None): ...
def nanrankdata(a, axis=None): ...
def partition(a, kth, axis=-1): ...
def argpartition(a, kth, axis=-1): ...
def push(a, n=None, axis=-1): ...

Array Manipulation Functions

Utility Functions

Testing, benchmarking, and introspection utilities for performance analysis and development support.

def bench(): ...
def bench_detailed(func_name, fraction_nan=0.3): ...
def test(): ...
def get_functions(module_name, as_string=False): ...

Utility Functions

Performance Notes

Bottleneck delivers substantial performance improvements over NumPy:

• Reduction operations: 2x to 100x+ faster for NaN-aware functions
• Moving window operations: 10x to 1000x+ faster than equivalent NumPy implementations
• Ranking functions: 2x to 50x faster than SciPy equivalents
• Memory efficiency: Optimized algorithms use less memory and reduce allocation overhead

Performance gains are most significant for:

• Large arrays (1000+ elements)
• Operations involving NaN values
• Moving window calculations on time series data
• Repeated statistical computations on similar data types