/**
 * Histogram binning, and the quantile everything else here is built on.
 *
 * Pure arithmetic: observations in, bin edges and counts out. No DOM, no chart
 * state, no options object, so it is testable on its own and inert under SSR.
 *
 * Lifted out of the chart core's `charts/common/Stats.js`, where it bins the
 * `histogram` type and frames the trellis panels. It arrives here because a
 * third copy was about to be written: the analysis layer needs the same
 * binning to draw a distribution beside a chart rather than inside one, and
 * its `summarize` had already grown its own `quantileSorted`, identical to the
 * core's down to the interpolation. Two copies of a definition that has seven
 * competing versions is one too many.
 *
 * ## Gaps, which mean something different here
 *
 * `histogram` takes `Array<number | null>` and simply does not count the gaps.
 * That is the opposite of the moving-window functions in `indicators`, where a
 * gap inside a window makes the whole window undefined. The difference is real
 * rather than an inconsistency: an average over a window is a claim about a
 * stretch of the series, so a hole in that stretch invalidates it, while a
 * histogram is a tally of the observations that exist and a missing one is
 * simply not an observation. The count of what was skipped is returned so a
 * reader can see it was.
 *
 * @module histogram
 */
/** Named rules for choosing a bin width. See {@link computeBinning}. */
export type BinRule = 'auto' | 'fd' | 'rice' | 'scott' | 'sqrt' | 'sturges';
export interface Binning {
    /** Bin boundaries, evenly spaced. Length is the bin count plus one. */
    edges: number[];
    /** The uniform width of every bin. */
    binWidth: number;
    /** Which rule actually chose the width, which is not always the one asked for. */
    rule: string;
    /** True when {@link MAX_BINS} clamped the count that was asked for. */
    capped: boolean;
}
export interface BinOptions {
    /** A named rule, or a fixed bin count. Default `'auto'`. */
    bins?: BinRule | number;
    /** An explicit width. Wins over `bins`. */
    binWidth?: number;
    /** Frame the bins on this extent instead of the data's own, so several histograms share a scale. */
    range?: [number, number];
}
export interface Histogram extends Binning {
    /** Observations per bin, the same length as `edges` minus one. */
    counts: number[];
    /** The midpoint of each bin, which is where a bar is usually drawn. */
    midpoints: number[];
    /** How many observations were counted. */
    total: number;
    /** How many entries were gaps, and so counted nowhere. */
    missing: number;
}
/**
 * Quantile of an ascending-sorted array.
 *
 * Linear interpolation between order statistics: the "type 7" definition, which
 * is what R's default, NumPy and a spreadsheet's QUARTILE all use. Named
 * because the seven definitions disagree on small samples, and a reader
 * checking a readout against a spreadsheet needs to know which one was picked.
 *
 * @param sorted ascending and finite
 * @param q 0 to 1
 * @returns NaN for an empty array, which has no quantile to report
 */
export declare function quantileSorted(sorted: ReadonlyArray<number>, q: number): number;
/**
 * Choose bin edges for a set of observations.
 *
 * Precedence: an explicit `binWidth`, then an explicit bin count, then a named
 * rule.
 *
 * @param values finite observations, in any order
 * @returns null when there is nothing to bin
 */
export declare function computeBinning(values: ReadonlyArray<number>, opts?: BinOptions): Binning | null;
/**
 * Index of the bin holding `v`, or -1 when it falls outside the edges.
 *
 * Bins are half-open, `[lo, hi)`, except the last, which includes its upper
 * edge. Without that exception the largest observation would be counted
 * nowhere.
 */
export declare function binIndexOf(v: number, edges: ReadonlyArray<number>): number;
/** Count observations per bin. Anything outside the edges is counted nowhere. */
export declare function binCounts(values: ReadonlyArray<number>, edges: ReadonlyArray<number>): number[];
/**
 * Bin a series and count it, in one call, tolerating gaps.
 *
 * The convenience the drawing side actually wants: it takes the series as it
 * is held, with its holes, and reports both the tally and how much of the
 * series was not an observation.
 *
 * @returns null when nothing in `values` is a finite number
 */
export declare function histogram(values: ReadonlyArray<number | null>, opts?: BinOptions): Histogram | null;
//# sourceMappingURL=histogram.d.ts.map