Package edu.cnu.mdi.splot.pdata

Class HistoData

java.lang.Object
edu.cnu.mdi.splot.pdata.HistoData
public class HistoData extends Object
Container for 1D histogram data.

Bin edges are stored in grid[] of length (numBins + 1). Counts are stored in counts[] of length numBins.

Responsibilities

This class is responsible only for data storage and bin arithmetic:

  • Filling, clearing, and querying bin counts
  • Underflow and overflow tracking
  • Basic statistics (mean, sigma, rms)
  • Display preferences (rms vs sigma in legend, stat error flag)

Out-of-scope (separated into dedicated classes)

Author:
heddle
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    HistoData(String name, double[] grid)
    Creates a histogram with arbitrary (non-uniform) bin spacing.
    HistoData(String name, double valMin, double valMax, int numBins)
    Creates a uniform-bin histogram.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(double value)
    Adds a single value to the histogram.
    void
    addAll(double[] values)
    Adds many values to the histogram in bulk.
    void
    clear()
    Resets all counts and invalidates the statistics cache.
    boolean
    drawStatisticalErrors()
    Returns whether sqrt(n) statistical error bars should be drawn.
    int
    findPeakBin()
    Convenience delegation: finds the raw peak bin (maximum count).
    int
    findPeakBin(int bin0, int bin1)
    Convenience delegation: finds the raw peak bin in a restricted range.
    double[]
    getBasicStatistics()
    Computes (and caches) the mean, standard deviation, and RMS of the histogram, weighted by bin counts.
    int
    getBin(double val)
    Returns the zero-based bin index for a given value.
    double
    getBinMaxX(int bin)
    Returns the right edge of a bin.
    double
    getBinMidValue(int bin)
    Returns the midpoint x value of a bin.
    double
    getBinMinX(int bin)
    Returns the left edge of a bin.
    double
    getBinWidth(int bin)
    Returns the width of a bin (right - left).
    long
    getCount(int bin)
    Returns the count for a specific bin.
    long[]
    getCounts()
    Returns the live counts array.
    long[]
    getCountsCopy()
    Returns a defensive copy of the counts array.
    long
    getGoodCount()
    Returns the total number of in-range entries (excludes underflow/overflow).
    double[]
    getGridCopy()
    Returns a defensive copy of the bin-edge grid.
    double
    getMaxX()
    Returns the right edge (maximum x) of the histogram range, i.e.
    double
    getMaxY()
    Returns the maximum y value, i.e.
    double
    getMinX()
    Returns the left edge (minimum x) of the histogram range, i.e.
    double
    getMinY()
    Returns the minimum y value.
    int
    getNumberBins()
    Returns the number of bins.
    long
    getOverCount()
    Returns the number of values that fell above the histogram range.
    long
    getTotalCount()
    Returns the total entry count including underflow and overflow.
    long
    getUnderCount()
    Returns the number of values that fell below the histogram range.
    String
    maxBinString()
    Returns a string describing the bin(s) with the maximum count (1-based indices).
    String
    name()
    Returns the histogram name.
    FitVectors
    prepareForFit(boolean includeZeroBins)
    Convenience delegation: prepares fit vectors over the full x-range.
    FitVectors
    prepareForFit(boolean includeZeroBins, double xmin, double xmax, boolean poissonWeights)
    Convenience delegation: prepares fit vectors over a data-space x-range.
    FitVectors
    prepareForFit(boolean includeZeroBins, int bin0, int bin1, boolean poissonWeights)
    Convenience delegation: prepares fit vectors over an inclusive bin-index range.
    HistoFitPrep.FitWindowData
    prepareForFitAroundBestPeakGuarded(boolean includeZeroBins, int halfWindowBins, int smoothRadius, boolean ignoreZeroBins, boolean poissonWeights, int minPoints)
    Convenience delegation: finds the best peak using smoothing and robust plateau handling, then prepares fit vectors in a guarded window around it.
    FitVectors
    prepareForFitAroundPeak(boolean includeZeroBins, int peakBin, int halfWindowBins, boolean poissonWeights)
    Convenience delegation: prepares fit vectors in a symmetric window around a given peak bin.
    void
    setCount(double val, int count)
    Sets the count for the bin that contains val.
    void
    setCountsForDeserialization(long[] countsSrc, long underCount, long overCount)
    Replaces the histogram counts from an external array.
    void
    setDrawStatisticalErrors(boolean statErr)
    Sets whether sqrt(n) statistical error bars are drawn on histogram bins.
    void
    setName(String name)
    Sets the histogram name.
    void
    setRmsInHistoLegend(boolean useRMS)
    Sets whether rms (rather than sigma) is shown in histogram legends.
    String
    statStr()
    Returns a single-line status string showing mean and either rms or sigma, plus under/overflow counts.
    String
    toString()
     
    boolean
    useRmsInHistoLegend()
    Returns whether rms (rather than sigma) is shown in histogram legends.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • HistoData

      public HistoData(String name, double valMin, double valMax, int numBins)
      Creates a uniform-bin histogram.
      Parameters:
      name - histogram name (used as curve label)
      valMin - range minimum (must be strictly less than valMax)
      valMax - range maximum
      numBins - number of bins (>= 1)
      Throws:
      IllegalArgumentException - if numBins < 1 or valMax <= valMin

    • HistoData

      public HistoData(String name, double[] grid)
      Creates a histogram with arbitrary (non-uniform) bin spacing.
      Parameters:
      name - histogram name (used as curve label)
      grid - bin-edge array in strictly ascending order (length >= 2)
      Throws:
      NullPointerException - if grid is null
      IllegalArgumentException - if grid.length < 2 or the array is not strictly ascending

  • Method Details

    • name

      public String name()
      Returns the histogram name.
      Returns:
      histogram name (never null after construction)

    • setName

      public void setName(String name)
      Sets the histogram name.
      Parameters:
      name - new name

    • getNumberBins

      public int getNumberBins()
      Returns the number of bins.
      Returns:
      grid.length - 1

    • getGridCopy

      public double[] getGridCopy()
      Returns a defensive copy of the bin-edge grid.
      Returns:
      copy of the grid array (length = getNumberBins() + 1)

    • getMinX

      public double getMinX()
      Returns the left edge (minimum x) of the histogram range, i.e. grid[0].
      Returns:
      minimum x value

    • getMaxX

      public double getMaxX()
      Returns the right edge (maximum x) of the histogram range, i.e. grid[grid.length - 1].
      Returns:
      maximum x value

    • getMinY

      public double getMinY()
      Returns the minimum y value. For histograms this is always 0.
      Returns:
      0.0

    • getMaxY

      public double getMaxY()
      Returns the maximum y value, i.e. the largest bin count. Returns at least 1 so that an empty histogram still has a drawable y range.
      Returns:
      max bin count as a double (>= 1)

    • getBinMidValue

      public double getBinMidValue(int bin)
      Returns the midpoint x value of a bin.
      Parameters:
      bin - zero-based bin index
      Returns:
      bin midpoint, or Double.NaN if bin is out of range

    • getBinMinX

      public double getBinMinX(int bin)
      Returns the left edge of a bin.
      Parameters:
      bin - zero-based bin index
      Returns:
      left edge, or Double.NaN if bin is out of range

    • getBinMaxX

      public double getBinMaxX(int bin)
      Returns the right edge of a bin.
      Parameters:
      bin - zero-based bin index
      Returns:
      right edge, or Double.NaN if bin is out of range

    • getBinWidth

      public double getBinWidth(int bin)
      Returns the width of a bin (right - left).
      Parameters:
      bin - zero-based bin index
      Returns:
      bin width, or Double.NaN if bin is out of range

    • getBin

      public int getBin(double val)
      Returns the zero-based bin index for a given value.
      Parameters:
      val - the value to look up
      Returns:
      bin index in [0, numBins - 1], or UNDERFLOW / OVERFLOW for out-of-range values

    • clear

      public void clear()
      Resets all counts and invalidates the statistics cache.

    • add

      public void add(double value)
      Adds a single value to the histogram.
      Parameters:
      value - the value to fill

    • addAll

      public void addAll(double[] values)
      Adds many values to the histogram in bulk.

      Equivalent to calling add(double) for each element, but invalidates the statistics cache only once.

      Parameters:
      values - array of sample values (non-null)
      Throws:
      NullPointerException - if values is null

    • setCount

      public void setCount(double val, int count)
      Sets the count for the bin that contains val.

      Values outside the range are added to the under/overflow accumulators.

      Parameters:
      val - value identifying the target bin
      count - count to assign

    • setCountsForDeserialization

      public void setCountsForDeserialization(long[] countsSrc, long underCount, long overCount)
      Replaces the histogram counts from an external array.

      Intended for deserialization / persistence only; not for normal filling.

      Parameters:
      countsSrc - source counts array (length must equal getNumberBins())
      underCount - underflow count to restore
      overCount - overflow count to restore
      Throws:
      IllegalArgumentException - if countsSrc length mismatches

    • getCounts

      public long[] getCounts()
      Returns the live counts array.

      The returned array is the internal storage — do not modify it. For a safe copy use getCountsCopy().

      Returns:
      live counts array (length = getNumberBins())

    • getCountsCopy

      public long[] getCountsCopy()
      Returns a defensive copy of the counts array.
      Returns:
      copy of the counts array

    • getCount

      public long getCount(int bin)
      Returns the count for a specific bin.
      Parameters:
      bin - zero-based bin index
      Returns:
      count, or 0 if bin is out of range

    • getGoodCount

      public long getGoodCount()
      Returns the total number of in-range entries (excludes underflow/overflow).
      Returns:
      sum of all bin counts

    • getTotalCount

      public long getTotalCount()
      Returns the total entry count including underflow and overflow.
      Returns:
      getGoodCount() + getUnderCount() + getOverCount()

    • getUnderCount

      public long getUnderCount()
      Returns the number of values that fell below the histogram range.
      Returns:
      underflow count

    • getOverCount

      public long getOverCount()
      Returns the number of values that fell above the histogram range.
      Returns:
      overflow count

    • getBasicStatistics

      public double[] getBasicStatistics()
      Computes (and caches) the mean, standard deviation, and RMS of the histogram, weighted by bin counts.
      Returns:
      array [mean, stdDev, rms], all Double.NaN if the histogram is empty

    • statStr

      public String statStr()
      Returns a single-line status string showing mean and either rms or sigma, plus under/overflow counts. The choice between rms and sigma is controlled by useRmsInHistoLegend().
      Returns:
      formatted statistics string

    • maxBinString

      public String maxBinString()
      Returns a string describing the bin(s) with the maximum count (1-based indices).
      Returns:
      descriptive string, or "" if the histogram is empty

    • setRmsInHistoLegend

      public void setRmsInHistoLegend(boolean useRMS)
      Sets whether rms (rather than sigma) is shown in histogram legends.
      Parameters:
      useRMS - true to show rms; false to show sigma

    • useRmsInHistoLegend

      public boolean useRmsInHistoLegend()
      Returns whether rms (rather than sigma) is shown in histogram legends.
      Returns:
      true if rms is shown

    • setDrawStatisticalErrors

      public void setDrawStatisticalErrors(boolean statErr)
      Sets whether sqrt(n) statistical error bars are drawn on histogram bins.
      Parameters:
      statErr - true to draw error bars

    • drawStatisticalErrors

      public boolean drawStatisticalErrors()
      Returns whether sqrt(n) statistical error bars should be drawn.
      Returns:
      true if statistical errors are drawn

    • prepareForFit

      public FitVectors prepareForFit(boolean includeZeroBins)
      Convenience delegation: prepares fit vectors over the full x-range.

      Equivalent to HistoFitPrep.prepareForFit(HistoData, boolean).

      Parameters:
      includeZeroBins - if true, bins with zero counts are included
      Returns:
      fit vectors (x, y, weights = null)
      See Also:

    • prepareForFit

      public FitVectors prepareForFit(boolean includeZeroBins, double xmin, double xmax, boolean poissonWeights)
      Convenience delegation: prepares fit vectors over a data-space x-range.
      Parameters:
      includeZeroBins - if true, bins with zero counts are included
      xmin - minimum x to include (data space)
      xmax - maximum x to include (data space)
      poissonWeights - if true, include Poisson (1/count) weights
      Returns:
      fit vectors
      See Also:

    • prepareForFit

      public FitVectors prepareForFit(boolean includeZeroBins, int bin0, int bin1, boolean poissonWeights)
      Convenience delegation: prepares fit vectors over an inclusive bin-index range.
      Parameters:
      includeZeroBins - if true, bins with zero counts are included
      bin0 - inclusive start bin (clamped to valid range)
      bin1 - inclusive end bin (clamped to valid range)
      poissonWeights - if true, include Poisson weights
      Returns:
      fit vectors
      See Also:

    • prepareForFitAroundPeak

      public FitVectors prepareForFitAroundPeak(boolean includeZeroBins, int peakBin, int halfWindowBins, boolean poissonWeights)
      Convenience delegation: prepares fit vectors in a symmetric window around a given peak bin.
      Parameters:
      includeZeroBins - if true, bins with zero counts are included
      peakBin - center bin of the window (0-based)
      halfWindowBins - half-width of the window in bins (>= 0)
      poissonWeights - if true, include Poisson weights
      Returns:
      fit vectors
      See Also:

    • findPeakBin

      public int findPeakBin()
      Convenience delegation: finds the raw peak bin (maximum count).
      Returns:
      peak bin index (0-based), or -1 if there are no bins
      See Also:

    • findPeakBin

      public int findPeakBin(int bin0, int bin1)
      Convenience delegation: finds the raw peak bin in a restricted range.
      Parameters:
      bin0 - inclusive start bin (0-based)
      bin1 - inclusive end bin (0-based)
      Returns:
      peak bin index (0-based), or -1 if there are no bins
      See Also:

    • prepareForFitAroundBestPeakGuarded

      public HistoFitPrep.FitWindowData prepareForFitAroundBestPeakGuarded(boolean includeZeroBins, int halfWindowBins, int smoothRadius, boolean ignoreZeroBins, boolean poissonWeights, int minPoints)
      Convenience delegation: finds the best peak using smoothing and robust plateau handling, then prepares fit vectors in a guarded window around it.
      Parameters:
      includeZeroBins - if true, include zero-count bins in fit vectors
      halfWindowBins - requested half-window size (>= 0)
      smoothRadius - smoothing radius for peak detection (>= 0)
      ignoreZeroBins - if true, zero-count bins are skipped as peak candidates
      poissonWeights - if true, include Poisson weights
      minPoints - minimum points required after filtering (>= 1)
      Returns:
      fit window data including metadata about the window that was used
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object