Package edu.cnu.mdi.splot.pdata

Class HistoFitPrep

java.lang.Object
edu.cnu.mdi.splot.pdata.HistoFitPrep
public final class HistoFitPrep extends Object
Stateless utility class for histogram fit preparation.

This class extracts the peak-finding and fit-vector building logic that was previously embedded in HistoData, keeping HistoData focused on data storage.

Fit-vector layout

All prepare* methods return a FitVectors (or the richer HistoFitPrep.FitWindowData subtype) whose arrays follow this convention:

  • x[i] — bin center (mid-point of bin i)
  • y[i] — bin count as a double
  • w[i] — optional Poisson weight 1/count for count > 0, 1.0 for zero bins (when weights are requested and the bin is included)

Peak-finding strategies

Author:
heddle (original), refactored for extraction
See Also:

  • Method Details

    • prepareForFit

      public static FitVectors prepareForFit(HistoData h, boolean includeZeroBins)
      Prepares fit vectors over the full x-range using unit weights.
      Parameters:
      h - source histogram (non-null)
      includeZeroBins - if true, bins with zero count are included
      Returns:
      fit vectors (weights = null)

    • prepareForFit

      public static FitVectors prepareForFit(HistoData h, boolean includeZeroBins, double xmin, double xmax, boolean poissonWeights)
      Prepares fit vectors over a data-space x-range.
      Parameters:
      h - source histogram (non-null)
      includeZeroBins - if true, include bins with zero count
      xmin - minimum x to include (data space, inclusive)
      xmax - maximum x to include (data space, inclusive)
      poissonWeights - if true, include Poisson (1/count) weights
      Returns:
      fit vectors; weights array is null unless poissonWeights is true

    • prepareForFit

      public static FitVectors prepareForFit(HistoData h, boolean includeZeroBins, int bin0, int bin1, boolean poissonWeights)
      Prepares fit vectors over an inclusive bin-index range.
      Parameters:
      h - source histogram (non-null)
      includeZeroBins - if true, include bins with zero count
      bin0 - inclusive start bin (0-based; clamped to valid range)
      bin1 - inclusive end bin (0-based; clamped to valid range)
      poissonWeights - if true, include Poisson weights
      Returns:
      fit vectors

    • prepareForFitAroundPeak

      public static FitVectors prepareForFitAroundPeak(HistoData h, boolean includeZeroBins, int peakBin, int halfWindowBins, boolean poissonWeights)
      Prepares fit vectors in a symmetric window around a given peak bin.
      Parameters:
      h - source histogram (non-null)
      includeZeroBins - if true, include bins with zero count
      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
      Throws:
      IllegalArgumentException - if halfWindowBins < 0

    • findPeakBin

      public static int findPeakBin(HistoData h)
      Returns the zero-based index of the bin with the highest count (raw maximum). On ties, the first occurrence is returned.
      Parameters:
      h - source histogram (non-null)
      Returns:
      peak bin index, or -1 if the histogram has no bins

    • findPeakBin

      public static int findPeakBin(HistoData h, int bin0, int bin1)
      Returns the zero-based index of the bin with the highest count within an inclusive bin range. On ties, the first occurrence is returned.
      Parameters:
      h - source histogram (non-null)
      bin0 - inclusive start bin (0-based; clamped)
      bin1 - inclusive end bin (0-based; clamped)
      Returns:
      peak bin index in the range, or -1 if there are no bins

    • findPeakBinSmoothed

      public static int findPeakBinSmoothed(HistoData h, int bin0, int bin1, int radius, boolean ignoreZeroBins)
      Finds the peak bin using a flat moving-average smoothing kernel.

      For each candidate bin i in [bin0, bin1], the score is the average count over [i-radius, i+radius]. The bin with the highest score wins; on a tie the bin with the higher raw count is preferred. Falls back to findPeakBin(HistoData, int, int) if no candidate is found.

      Parameters:
      h - source histogram (non-null)
      bin0 - inclusive start bin for the search (0-based; clamped)
      bin1 - inclusive end bin for the search (0-based; clamped)
      radius - smoothing half-width in bins (>= 0)
      ignoreZeroBins - if true, zero-count bins are skipped as candidates
      Returns:
      peak bin index, or -1 if there are no bins
      Throws:
      IllegalArgumentException - if radius < 0

    • findPeakBinSmoothed

      public static int findPeakBinSmoothed(HistoData h, int radius, boolean ignoreZeroBins)
      Convenience overload of findPeakBinSmoothed(edu.cnu.mdi.splot.pdata.HistoData, int, int, int, boolean) over the full histogram range.
      Parameters:
      h - source histogram (non-null)
      radius - smoothing half-width in bins (>= 0)
      ignoreZeroBins - if true, zero-count bins are skipped
      Returns:
      peak bin index, or -1 if there are no bins

    • findPeakBinTriangularSmoothed

      public static int findPeakBinTriangularSmoothed(HistoData h, int bin0, int bin1, int radius, boolean ignoreZeroBins)
      Finds the peak bin using a triangular (linear-decay) smoothing kernel.

      Bins closer to the candidate bin i contribute more to the score. Weight of bin j is (radius + 1 - |j - i|). On a tie, prefer the bin with the higher raw count; if still tied, prefer the bin closer to the center of the search range.

      Parameters:
      h - source histogram (non-null)
      bin0 - inclusive start bin (0-based; clamped)
      bin1 - inclusive end bin (0-based; clamped)
      radius - smoothing half-width (>= 0)
      ignoreZeroBins - if true, zero-count bins are skipped
      Returns:
      peak bin index, or -1 if there are no bins
      Throws:
      IllegalArgumentException - if radius < 0

    • findPeakBinTriangularSmoothed

      public static int findPeakBinTriangularSmoothed(HistoData h, int radius, boolean ignoreZeroBins)
      Convenience overload of findPeakBinTriangularSmoothed(edu.cnu.mdi.splot.pdata.HistoData, int, int, int, boolean) over the full histogram range.
      Parameters:
      h - source histogram (non-null)
      radius - smoothing half-width (>= 0)
      ignoreZeroBins - if true, zero-count bins are skipped
      Returns:
      peak bin index, or -1 if there are no bins

    • findPeakBinBest

      public static int findPeakBinBest(HistoData h, int bin0, int bin1, int smoothRadius, boolean ignoreZeroBins)
      Finds the best peak using triangular smoothing plus robust plateau handling.

      When multiple adjacent bins share the top smoothed score (a plateau), this method picks the best raw-count bin within that plateau, resolving further ties by proximity to the plateau's own midpoint and then to the search-range midpoint. This strategy is preferred over pure triangular-smoothed search for most fitting use cases.

      Parameters:
      h - source histogram (non-null)
      bin0 - inclusive start bin (0-based; clamped)
      bin1 - inclusive end bin (0-based; clamped)
      smoothRadius - smoothing half-width (>= 0); 0 degenerates to raw-peak-with-plateau
      ignoreZeroBins - if true, zero-count bins are skipped as candidates
      Returns:
      peak bin index, or -1 if there are no bins
      Throws:
      IllegalArgumentException - if smoothRadius < 0

    • findPeakBinBest

      public static int findPeakBinBest(HistoData h, int smoothRadius, boolean ignoreZeroBins)
      Convenience overload of findPeakBinBest(edu.cnu.mdi.splot.pdata.HistoData, int, int, int, boolean) over the full histogram range.
      Parameters:
      h - source histogram (non-null)
      smoothRadius - smoothing half-width (>= 0)
      ignoreZeroBins - if true, zero-count bins are skipped
      Returns:
      peak bin index, or -1 if there are no bins

    • prepareForFitAroundBestPeakGuarded

      public static HistoFitPrep.FitWindowData prepareForFitAroundBestPeakGuarded(HistoData h, boolean includeZeroBins, int halfWindowBins, int smoothRadius, boolean ignoreZeroBins, boolean poissonWeights, int minPoints)
      Prepares fit vectors around the best peak with edge-safety and minimum-points guarantees.

      The strategy:

      1. Prefer peaks that can support the full requested window without clipping (search in the "inner" sub-range first).
      2. Auto-shrink the half-window if the peak is near an edge.
      3. If the result has fewer than minPoints entries, expand to the maximum available window.
      4. Last resort: if the caller excluded zero bins, retry with zeros included.
      5. If still insufficient, return an empty HistoFitPrep.FitWindowData with metadata preserved.
      Parameters:
      h - source histogram (non-null)
      includeZeroBins - if true, include zero-count bins normally
      halfWindowBins - requested half-window in bins (>= 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 number of points required (>= 1)
      Returns:
      HistoFitPrep.FitWindowData including metadata about the selected window
      Throws:
      IllegalArgumentException - if halfWindowBins < 0 or minPoints < 1

    • prepareForFitAroundBestPeakGuarded

      public static HistoFitPrep.FitWindowData prepareForFitAroundBestPeakGuarded(HistoData h, boolean includeZeroBins, int searchBin0, int searchBin1, int halfWindowBins, int smoothRadius, boolean ignoreZeroBins, boolean poissonWeights, int minPoints)
      Prepares fit vectors around the best peak within a restricted search range, with edge-safety and minimum-points guarantees.
      Parameters:
      h - source histogram (non-null)
      includeZeroBins - if true, include zero-count bins normally
      searchBin0 - inclusive start bin to search for a peak (0-based; clamped)
      searchBin1 - inclusive end bin to search for a peak (0-based; clamped)
      halfWindowBins - requested half-window in bins (>= 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 number of points required (>= 1)
      Returns:
      HistoFitPrep.FitWindowData including metadata about the selected window
      Throws:
      IllegalArgumentException - if halfWindowBins < 0 or minPoints < 1