FastHistograms.jl

Fast, minimal histogram algorithms.
Author Octogonapus
Popularity
5 Stars
Updated Last
2 Years Ago
Started In
March 2021

FastHistograms

Stable Dev Build Status Coverage

FastHistograms declares and implements a minimal histogram interface with a focus on speed.

Example

julia> using FastHistograms, Random

# Create a 2D histogram for 8-bit integer data.
julia> h = create_fast_histogram(
    # Use fixed-width bins with an optimized bin search algorithm (Arithmetic)
    #  for fixed-width bins.
    FastHistograms.FixedWidth(),
    FastHistograms.Arithmetic(),
    # Don't use any parallelization because our data are small.
    FastHistograms.NoParallelization(),
    [(0x00, 0xff, 4), (0x00, 0xff, 4)],
);

# Create two random images to compute the joint histogram for
julia> img1 = rand(0x00:0xff, 32, 32);

julia> img2 = rand(0x00:0xff, 32, 32);

# Compute the histogram bin counts
julia> increment_bins!(h, img1, img2)

# Get the bin counts
julia> counts(h)
4×4 Matrix{Int64}:
 61  64  67  64
 65  59  72  65
 61  66  71  61
 53  67  63  65

Benchmarks

These benchmarks were run on a t3.medium EC2 instance. Processor shielding was not used. ASLR was enabled.

Benchmarking type=UInt8, size=(40, 80)
┌───────────────┬───────────────────┬───────────────────┬─────────────────┬────────────┬───────────────┐
│               │ FastHistograms:   | FastHistograms:   │ FastHistograms: │ StatsBase: │ StatsBase:    │
|               | FixedWidth,       | VariableWidth,    | FixedWidth,     | FixedWidth | VariableWidth |
|               | Arithmetic,       | BinarySearch,     | Arithmetic,     |            |               |
|               | NoParallelization │ NoParallelization | SIMD            |            |               |
├───────────────┼───────────────────┼───────────────────┼─────────────────┼────────────┼───────────────┤
│ Min Time (ns) │           19197.0 │           49013.0 │         19061.0 │    47274.0 │       53584.0 │
│  GC Time (ns) │               0.0 │               0.0 │             0.0 │        0.0 │           0.0 │
│    Allocs (B) │               0.0 │               0.0 │             0.0 │        2.0 │           2.0 │
│    Memory (B) │               0.0 │               0.0 │             0.0 │     2224.0 │         224.0 │
└───────────────┴───────────────────┴───────────────────┴─────────────────┴────────────┴───────────────┘
Benchmarking type=UInt8, size=(256, 256)
┌───────────────┬───────────────────┬───────────────────┬─────────────────┬────────────┬───────────────┐
│               │ FastHistograms:   | FastHistograms:   │ FastHistograms: │ StatsBase: │ StatsBase:    │
|               | FixedWidth,       | VariableWidth,    | FixedWidth,     | FixedWidth | VariableWidth |
|               | Arithmetic,       | BinarySearch,     | Arithmetic,     |            |               |
|               | NoParallelization │ NoParallelization | SIMD            |            |               |
├───────────────┼───────────────────┼───────────────────┼─────────────────┼────────────┼───────────────┤
│ Min Time (ns) │          375058.0 │          987333.0 │        372359.0 │   962661.0 │     1.09619e6 │
│  GC Time (ns) │               0.0 │               0.0 │             0.0 │        0.0 │           0.0 │
│    Allocs (B) │               0.0 │               0.0 │             0.0 │        2.0 │           2.0 │
│    Memory (B) │               0.0 │               0.0 │             0.0 │     2224.0 │         224.0 │
└───────────────┴───────────────────┴───────────────────┴─────────────────┴────────────┴───────────────┘
Benchmarking type=Float32, size=(40, 80)
┌───────────────┬───────────────────┬───────────────────┬─────────────────┬────────────┬───────────────┐
│               │ FastHistograms:   | FastHistograms:   │ FastHistograms: │ StatsBase: │ StatsBase:    │
|               | FixedWidth,       | VariableWidth,    | FixedWidth,     | FixedWidth | VariableWidth |
|               | Arithmetic,       | BinarySearch,     | Arithmetic,     |            |               |
|               | NoParallelization │ NoParallelization | SIMD            |            |               |
├───────────────┼───────────────────┼───────────────────┼─────────────────┼────────────┼───────────────┤
│ Min Time (ns) │           15592.0 │          100289.0 │         17634.0 │    74005.0 │      107417.0 │
│  GC Time (ns) │               0.0 │               0.0 │             0.0 │        0.0 │           0.0 │
│    Allocs (B) │               0.0 │               0.0 │             0.0 │        2.0 │           2.0 │
│    Memory (B) │               0.0 │               0.0 │             0.0 │     2224.0 │         224.0 │
└───────────────┴───────────────────┴───────────────────┴─────────────────┴────────────┴───────────────┘
Benchmarking type=Float32, size=(256, 256)
┌───────────────┬───────────────────┬───────────────────┬─────────────────┬────────────┬───────────────┐
│               │ FastHistograms:   | FastHistograms:   │ FastHistograms: │ StatsBase: │ StatsBase:    │
|               | FixedWidth,       | VariableWidth,    | FixedWidth,     | FixedWidth | VariableWidth |
|               | Arithmetic,       | BinarySearch,     | Arithmetic,     |            |               |
|               | NoParallelization │ NoParallelization | SIMD            |            |               |
├───────────────┼───────────────────┼───────────────────┼─────────────────┼────────────┼───────────────┤
│ Min Time (ns) │          309092.0 │         2.13267e6 │        332810.0 │  1.50458e6 │     2.30337e6 │
│  GC Time (ns) │               0.0 │               0.0 │             0.0 │        0.0 │           0.0 │
│    Allocs (B) │               0.0 │               0.0 │             0.0 │        2.0 │           2.0 │
│    Memory (B) │               0.0 │               0.0 │             0.0 │     2224.0 │         224.0 │
└───────────────┴───────────────────┴───────────────────┴─────────────────┴────────────┴───────────────┘
┌───────────────┬─────────────────┬────────────┐
│               │ FastHistograms: | StatsBase: │
|               | FixedWidth,     | FixedWidth |
|               | Arithmetic,     |            |
|               | PrivateThreads  |            |
├───────────────┼─────────────────┼────────────┤
│ Min Time (ns) │       2.57596e8 │  3.01149e9 │
│  GC Time (ns) │             0.0 │        0.0 │
│    Allocs (B) │            11.0 │        2.0 │
│    Memory (B) │          1056.0 │     4288.0 │
└───────────────┴─────────────────┴────────────┘