Implementation:Haifengl Smile Histogram

Knowledge Sources	Haifengl_Smile
Domains	Mathematics, Statistics, Data Analysis
Last Updated	2026-02-08 22:00 GMT

Overview

Histogram is an interface providing static utility methods for computing frequency histograms, determining optimal bin counts, and calculating breakpoints for data binning.

Description

The Histogram interface in the smile.math package provides tools for tabulating data into frequency distributions. It supports multiple data types (int[], float[], double[]) and offers several strategies for choosing the number of bins:

• Square-root rule -- the default, using sqrt(n) bins
• Sturges' rule -- ceil(log2(n) + 1) bins, suitable for roughly normal data
• Scott's rule -- bin width determined by 3.5 * sigma / n^(1/3)

The interface also provides methods to compute custom breakpoints given a desired bin width or count, and to generate histograms with explicit breakpoint arrays. Note that this class provides only frequency counting and bin computation; it does not provide plotting services.

Usage

Use Histogram when you need to bin numeric data into frequency distributions for exploratory data analysis, density estimation preprocessing, or generating input for visualization libraries.

Code Reference

Source Location

• Repository: Haifengl_Smile
• File: base/src/main/java/smile/math/Histogram.java
• Lines: 1-419

Signature

public interface Histogram {
    // Generate histogram with automatic bin count (square-root rule)
    static double[][] of(int[] data);
    static double[][] of(float[] data);
    static double[][] of(double[] data);

    // Generate histogram with specified number of bins
    static double[][] of(int[] data, int k);
    static double[][] of(float[] data, int k);
    static double[][] of(double[] data, int k);

    // Generate histogram with explicit breakpoints
    static double[][] of(int[] data, double[] breaks);
    static double[][] of(float[] data, float[] breaks);
    static double[][] of(double[] data, double[] breaks);

    // Compute breakpoints
    static double[] breaks(double[] x, double h);
    static double[] breaks(double min, double max, double h);
    static double[] breaks(double[] x, int k);
    static double[] breaks(double min, double max, int k);

    // Compute number of bins
    static int bins(double[] x, double h);
    static int bins(int n);        // square-root rule
    static int sturges(int n);     // Sturges' rule
    static int scott(double[] x);  // Scott's rule
}

Import

import smile.math.Histogram;

I/O Contract

Inputs

Name	Type	Required	Description
data	int[], float[], or double[]	Yes	The data points to bin into a histogram
k	int	No	The number of bins (if not provided, computed automatically via square-root rule)
breaks	double[] or float[]	No	An array of size k+1 giving breakpoints between histogram cells, in ascending order
h	double	No	Suggested bin width for computing breakpoints or bin count
n	int	No	The number of data points (for bin count calculation only)

Outputs

Name	Type	Description
histogram	double[][]	A 3-by-k array where row 0 is the lower bound of bins, row 1 is the upper bound, and row 2 is the frequency count
breaks	double[]	An array of breakpoints between histogram cells (from breaks() methods)
bins	int	The computed number of bins (from bins(), sturges(), or scott() methods)

Usage Examples

Basic Usage

// Generate a histogram with automatic bin count
double[] data = {1.2, 2.3, 2.5, 3.1, 3.8, 4.0, 4.5, 5.1, 5.9, 6.0};
double[][] hist = Histogram.of(data);
// hist[0] = lower bounds, hist[1] = upper bounds, hist[2] = counts

Specifying Number of Bins

// Generate a histogram with exactly 5 bins
double[] data = {1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0};
double[][] hist = Histogram.of(data, 5);

for (int i = 0; i < hist[0].length; i++) {
    System.out.printf("[%.2f, %.2f): %.0f%n", hist[0][i], hist[1][i], hist[2][i]);
}

Using Bin Count Rules

double[] data = new double[1000];
// ... populate data ...

// Sturges' rule for bin count
int k = Histogram.sturges(data.length);
double[][] hist = Histogram.of(data, k);

// Scott's rule for bin count
int kScott = Histogram.scott(data);
double[][] histScott = Histogram.of(data, kScott);

Custom Breakpoints

double[] data = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0};
double[] breaks = Histogram.breaks(1.0, 9.0, 1.0); // bin width of 1.0
double[][] hist = Histogram.of(data, breaks);

Related Pages

• Implementation:Haifengl_Smile_MathEx