Package edu.cnu.mdi.splot.pdata

Class Histo2DData

java.lang.Object
edu.cnu.mdi.splot.pdata.Histo2DData
public final class Histo2DData extends Object
Container class for 2D histogram (heatmap) data.

Data coordinates are binned into a uniform grid of nx * ny cells over [xmin, xmax] and [ymin, ymax].

Bin conventions

  • Bins are uniform in x and y.
  • Values strictly below min or strictly above max are out of range.
  • Values exactly equal to max are included in the last bin.

Under/over handling

Like HistoData, values outside the range are not binned; instead they are counted in under/over counters. In 2D there are edge regions and corners (both x and y out of range).

Threading

This class is safe to fill from a worker thread while the EDT paints by using snapshotBins() in the painter. All mutations and snapshots are guarded by an internal lock.
Author:
heddle

  • Constructor Summary

    Constructors
    Constructor
    Description
    Histo2DData(String name, double xmin, double xmax, int nx, double ymin, double ymax, int ny)
    Constructor for 2D histogram data.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    bin(double x, double y)
    Get the bin content for data coordinates.
    double
    bin(int ix, int iy)
    Get the bin content.
    void
    clear()
     
    int
    entries()
    Backwards-compatible name: this returns the in-range (good) fill count.
    void
    fill(double x, double y)
    Fill the histogram with weight 1.0.
    void
    fill(double x, double y, double weight)
    Fill the histogram.
    long
    getEmptyBinCount()
     
    long
    getGoodCount()
     
    long
    getTotalCount()
     
    long
    getXOverCount()
     
    long
    getXOverYOverCount()
     
    long
    getXOverYUnderCount()
     
    long
    getXUnderCount()
     
    long
    getXUnderYOverCount()
     
    long
    getXUnderYUnderCount()
     
    long
    getYOverCount()
     
    long
    getYUnderCount()
     
    double
    localMean3x3(double datax, double datay)
    Compute the local 3x3 neighborhood average around the bin containing the given data coordinate.
    double
    maxBin()
    Get the maximum bin value.
    static double
    maxZ(double[][] bins)
    Static utility to get the maximum z value from a 2D bins array.
    double
    meanBin()
    Get the mean bin value (average of in-range bins).
    double
    minNonZero()
    Get the minimum non-zero bin value.
    String
    name()
     
    int
    nx()
     
    int
    ny()
     
    double
    percentile(double datax, double datay)
    Get the percentile rank of the bin containing the given data coordinate.
    String
    rangeSummary()
    Return a human-readable summary of in-range and out-of-range fills.
    void
    setBinsForDeserialization(double[][] bins, long goodCount, long xUnderCount, long xOverCount, long yUnderCount, long yOverCount, long xUnder_yUnder, long xUnder_yOver, long xOver_yUnder, long xOver_yOver)
    INTERNAL: set bin contents and counts during deserialization/persistence restore.
    double[][]
    snapshotBins()
    Deep-copy bins for safe use during painting.
    double[]
    xBinRange(double x)
    Get the x bin range for a data x.
    double
    xBinWidth()
     
    int
    xIndex(double x)
    Get the x-bin index for a data x.
    double
    xMax()
     
    double
    xMin()
     
    double[]
    yBinRange(double y)
    Get the y bin range for a data y.
    double
    yBinWidth()
     
    int
    yIndex(double y)
    Get the y-bin index for a data y.
    double
    yMax()
     
    double
    yMin()
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Histo2DData

      public Histo2DData(String name, double xmin, double xmax, int nx, double ymin, double ymax, int ny)
      Constructor for 2D histogram data.
      Parameters:
      name - histogram name
      xmin - the minimum x value
      xmax - the maximum x value
      nx - number of x bins
      ymin - the minimum y value
      ymax - the maximum y value
      ny - number of y bins

  • Method Details

    • name

      public String name()

    • nx

      public int nx()
      Returns:
      number of x bins

    • ny

      public int ny()
      Returns:
      number of y bins

    • xMin

      public double xMin()
      Returns:
      minimum x value

    • xMax

      public double xMax()
      Returns:
      maximum x value

    • yMin

      public double yMin()
      Returns:
      minimum y value

    • yMax

      public double yMax()
      Returns:
      maximum y value

    • xBinWidth

      public double xBinWidth()
      Returns:
      x bin width

    • yBinWidth

      public double yBinWidth()
      Returns:
      y bin width

    • xIndex

      public int xIndex(double x)
      Get the x-bin index for a data x. Returns -1 if out of range. Includes x==xMax in the last bin.

    • yIndex

      public int yIndex(double y)
      Get the y-bin index for a data y. Returns -1 if out of range. Includes y==yMax in the last bin.

    • fill

      public void fill(double x, double y)
      Fill the histogram with weight 1.0.

    • fill

      public void fill(double x, double y, double weight)
      Fill the histogram.

      Out-of-range points increment under/over counters; in-range points increment the appropriate bin. Weight may be any finite value (including negative), but note that negative weights make "max" less meaningful.

    • bin

      public double bin(double x, double y)
      Get the bin content for data coordinates. Returns 0 for out-of-range.
      Parameters:
      x - data x
      y - data y
      Returns:
      bin content (the "z" value)

    • bin

      public double bin(int ix, int iy)
      Get the bin content. Returns 0 for out-of-range indices.
      Parameters:
      ix - x bin index
      iy - y bin index
      Returns:
      bin content (the "z" value)

    • xBinRange

      public double[] xBinRange(double x)
      Get the x bin range for a data x.
      Parameters:
      x - data x
      Returns:
      [x0, x1] bin range, or null if out of range

    • yBinRange

      public double[] yBinRange(double y)
      Get the y bin range for a data y.
      Parameters:
      y - data y
      Returns:
      [y0, y1] bin range, or null if out of range

    • entries

      public int entries()
      Backwards-compatible name: this returns the in-range (good) fill count.

    • getGoodCount

      public long getGoodCount()
      Returns:
      in-range fill count (good points).

    • getTotalCount

      public long getTotalCount()
      Returns:
      total fills including out-of-range.

    • getXUnderCount

      public long getXUnderCount()
      Returns:
      x-underflow count (y in range).

    • getXOverCount

      public long getXOverCount()
      Returns:
      x-overflow count (y in range).

    • getYUnderCount

      public long getYUnderCount()
      Returns:
      y-underflow count (x in range).

    • getYOverCount

      public long getYOverCount()
      Returns:
      y-overflow count (x in range).

    • getXUnderYUnderCount

      public long getXUnderYUnderCount()
      Returns:
      corner: x under, y under.

    • getXUnderYOverCount

      public long getXUnderYOverCount()
      Returns:
      corner: x under, y over.

    • getXOverYUnderCount

      public long getXOverYUnderCount()
      Returns:
      corner: x over, y under.

    • getXOverYOverCount

      public long getXOverYOverCount()
      Returns:
      corner: x over, y over.

    • getEmptyBinCount

      public long getEmptyBinCount()
      Returns:
      number of non-empty bins.

    • maxBin

      public double maxBin()
      Get the maximum bin value.
      Returns:
      maximum bin value, or 0 if none

    • minNonZero

      public double minNonZero()
      Get the minimum non-zero bin value.
      Returns:
      minimum non-zero bin value, or 0 if none

    • clear

      public void clear()

    • snapshotBins

      public double[][] snapshotBins()
      Deep-copy bins for safe use during painting.

    • maxZ

      public static double maxZ(double[][] bins)
      Static utility to get the maximum z value from a 2D bins array.
      Parameters:
      bins - 2D array of bin values
      Returns:
      maximum finite bin value, or 0 if none

    • meanBin

      public double meanBin()
      Get the mean bin value (average of in-range bins).
      Returns:
      mean bin value, or 0 if none

    • percentile

      public double percentile(double datax, double datay)
      Get the percentile rank of the bin containing the given data coordinate.

      Percentile is computed over the distribution of occupied bins (non-zero, finite bin values). The returned value is in the range [0, 100] where 0 means "empty or no occupied bins" and 100 means "at or above the maximum occupied bin".

      Parameters:
      datax - data x coordinate
      datay - data y coordinate
      Returns:
      percentile rank in [0, 100]

    • localMean3x3

      public double localMean3x3(double datax, double datay)
      Compute the local 3x3 neighborhood average around the bin containing the given data coordinate.

      The neighborhood includes the center bin and all valid in-range neighbors. The average is computed over finite values; non-finite values are ignored.

      Parameters:
      datax - data x coordinate
      datay - data y coordinate
      Returns:
      local 3x3 average, or 0 if the coordinate is out of range or no finite bins are available

    • setBinsForDeserialization

      public void setBinsForDeserialization(double[][] bins, long goodCount, long xUnderCount, long xOverCount, long yUnderCount, long yOverCount, long xUnder_yUnder, long xUnder_yOver, long xOver_yUnder, long xOver_yOver)
      INTERNAL: set bin contents and counts during deserialization/persistence restore.

      This performs a defensive deep-copy of bins and replaces the internal counts in a single synchronized block.

      Parameters:
      bins - bin contents sized [nx][ny]
      goodCount - in-range fill count
      xUnderCount - x-underflow count (y in-range)
      xOverCount - x-overflow count (y in-range)
      yUnderCount - y-underflow count (x in-range)
      yOverCount - y-overflow count (x in-range)
      xUnder_yUnder - corner count (x under, y under)
      xUnder_yOver - corner count (x under, y over)
      xOver_yUnder - corner count (x over, y under)
      xOver_yOver - corner count (x over, y over)

    • rangeSummary

      public String rangeSummary()
      Return a human-readable summary of in-range and out-of-range fills.

      Only non-zero out-of-range categories are reported.

      Returns:
      summary string