Package sc.fiji.snt.analysis.sholl.math

Class PolarProfileStats

java.lang.Object
sc.fiji.snt.analysis.sholl.math.PolarProfileStats
All Implemented Interfaces:
ShollStats
public class PolarProfileStats extends Object implements ShollStats
PolarProfileStats computes angle-resolved (‘Polar Sholl’) metrics from a Sholl Profile, providing analysis and visualization methods for directional patterns in Sholl profiles.

This class analyzes the directional distribution of Sholl intersections/cable length by dividing the 360° space around a center point into angular sectors. The angular resolution is specified using step size in degrees (e.g., 10° for 36 bins).

Author:
Tiago Ferreira

  • Constructor Details

    • PolarProfileStats

      public PolarProfileStats(Profile profile)
      Instantiates a new PolarProfileStats from an existing Sholl Profile, with the default angular resolution (10°).
      Parameters:
      profile - the Sholl Profile containing radii and intersection counts.

    • PolarProfileStats

      public PolarProfileStats(Profile profile, ShollStats.DataMode dataMode, double angleStepSize)
      Instantiates a new PolarProfileStats from a Profile with custom angular resolution.
      Parameters:
      profile - the Sholl Profile
      angleStepSize - the angular step size in degrees (e.g., 10.0 for 10° bins)

    • PolarProfileStats

      public PolarProfileStats(LinearProfileStats linerStats, double angleStepSize)
      Instantiates a new PolarProfileStats from a Profile with custom angular resolution.
      Parameters:
      linerStats - the LinearProfileStats instance from which profile is extracted. If a polynomial fit has been applied the fitted profile is used. The data mode used is that of LinearProfileStats and cannot be changed.
      angleStepSize - the angular step size in degrees (e.g., 10.0 for 10° bins)

  • Method Details

    • getAngleStepSize

      public double getAngleStepSize()
      Gets the angular step size in degrees.
      Returns:
      the angular step size in degrees

    • setAngleStepSize

      public void setAngleStepSize(double angleStepSize)
      Sets the angular step size in degrees.
      Parameters:
      angleStepSize - the angular step size in degrees (e.g., a step size of 10° splits the data into 36 bins)
      Throws:
      IllegalArgumentException - if angleStepSize is not a positive divisor of 360

    • getDataMode

      public ShollStats.DataMode getDataMode()
      Specified by:
      getDataMode in interface ShollStats

    • setDataMode

      public void setDataMode(ShollStats.DataMode mode)
      Specified by:
      setDataMode in interface ShollStats

    • getMatrix

      public double[][] getMatrix()
      Returns the length matrix with shape [nRadialBins][nAngleBins]. When data mode is intersections: Each entry stores the number of intersected components assigned to the ring-sector bin at the given radial and angular index. When data mode is length: Each entry stores the total cable length (in calibrated physical units) assigned to the ring-sector bin at the given radial and angular index.

      Indexing: row = radial bin (inner to outer), column = angular bin (0..nAngleBins-1). Angular bins partition [0°, 360°[ using an equal step size given by getAngleStepSize() and are referenced by their bin center angle when aggregating directions.

      Returns:
      a non-null 2D array where C[r][a] is the count in bin (r,a), or L[r][a] is the length in bin (r,a),

    • getAngularDistribution

      public double[] getAngularDistribution()
      Returns the angular distribution obtained by summing the intersections matrix or the length matrix across all radial bins.

      Units: For intersections: counts per angular bin (dimensionless). For length: calibrated length per angular bin (e.g., micrometers).

      Length: nAngleBins. Entry k corresponds to the angular bin centered at (k + 0.5) * getAngleStepSize().

      Returns:
      a non-null array w of size nAngleBins, where w[k] is the total number of components in angular bin k.

    • getAngularDistribution

      public double[] getAngularDistribution(double rMin, double rMax)
      Returns the angular distribution obtained by summing only those radial bins whose ring centers fall within the half-open interval [rMin, rMax[.

      Units match getAngularDistribution() (counts or calibrated length). The selection uses the center of each ring at startRadius + (r+0.5)*step. This keeps binning stable and avoids partial-ring weighting.

    • getPreferredDirection

      public double getPreferredDirection(double rMin, double rMax)
      Convenience: preferred direction computed from a radial band [rMin,rMax).

    • getPreferredOrientation

      public double getPreferredOrientation(double rMin, double rMax)
      Convenience: preferred orientation computed from a radial band [rMin,rMax).

    • findDirectionPeaks

      public List<PolarProfileStats.PolarPeak> findDirectionPeaks(double rMin, double rMax, int maxPeaks, double minProminence)
      Finds up to maxPeaks local maxima in the direction (0–360°) distribution within a Sholl band. Peaks are detected after a small circular moving-average smoothing (window=3). Candidates must exceed minProminence above the mean of their two neighbors and are greedily selected with a minimum separation of 2× angleStepSize.
      Parameters:
      rMin - the smallest Sholl radius to be considered
      rMax - the largest Sholl radius to be considered
      maxPeaks - the number of peaks to be retrieved
      minProminence - Minimum required local prominence measured on the smoothed angular distribution s[k] (3-point circular moving average). Prominence is defined as s[k] - 0.5*(s[k-1] + s[k+1]) and has the same units as the underlying distribution: Intersections mode: counts per angular bin (dimensionless count); Length mode: calibrated length per angular bin (e.g., µm)
      See Also:

    • findOrientationPeaks

      public List<PolarProfileStats.PolarPeak> findOrientationPeaks(double rMin, double rMax, int maxPeaks, double minProminence)
      Finds up to maxPeaks local maxima in the orientation (0–180°) distribution within a Sholl band. Peaks are detected after a small circular moving-average smoothing (window=3). Candidates must exceed minProminence above the mean of their two neighbors and are greedily selected with a minimum separation of 2× angleStepSize.
      Parameters:
      rMin - the smallest Sholl radius to be considered
      rMax - the largest Sholl radius to be considered
      maxPeaks - the number of peaks to be retrieved
      minProminence - Minimum required local prominence measured on the smoothed angular distribution s[k] (3-point circular moving average). Prominence is defined as s[k] - 0.5*(s[k-1] + s[k+1]) and has the same units as the underlying distribution: Intersections mode: counts per angular bin (dimensionless count); Length mode: calibrated length per angular bin (e.g., µm)
      See Also:

    • findDirectionPeaks

      public List<PolarProfileStats.PolarPeak> findDirectionPeaks(double rMin, double rMax)
      Automatically finds directional peaks (0–360°) over a Sholl radial band by deriving a data-driven prominence threshold (median + 1.5×MAD (Median Absolute Deviation), of local prominences after light smoothing) and applying a minimum separation of two angular bins. The number of returned peaks is the predicted number of meaningful directions in the band.
      Parameters:
      rMin - the smallest Sholl radius to be considered
      rMax - the largest Sholl radius to be considered

    • findOrientationPeaks

      public List<PolarProfileStats.PolarPeak> findOrientationPeaks(double rMin, double rMax)
      Automatically finds orientation (0–180°) peaks over a radial band using the same settings used by findDirectionPeaks(double, double).
      Parameters:
      rMin - the smallest Sholl radius to be considered
      rMax - the largest Sholl radius to be considered

    • getReport

      public PolarProfileStats.Report getReport()
      Returns a cached summary report of the analysis. Recomputed lazily whenever the underlying matrices change (on changing angle step, data mode, etc.).

    • detailReport

      public void detailReport(SNTTable table)
      Writes PolarProfileStats.Report details to a table.
      Parameters:
      table - destination table (non-null)

    • appendSummaryReport

      public void appendSummaryReport(SNTTable table)
      Appends summary data of PolarProfileStats.Report to the last row of the specified table Columns written:
      • Angular Distribution Coherence [0,1]
      • Orientation Distribution Coherence [0,1]
      • Preferred Direction in degrees [0,360[
      • Preferred Orientation in degrees [0,180[
      • Number of directional peaks
      • Angle, Value of first two directional peaks
      • Number of orientation peaks
      • Angle, Value of first two orientation peaks
      Parameters:
      table - the SNTTable to append to (must be non-null)

    • getAngularDistributionCoherence

      public double getAngularDistributionCoherence()
      Convenience getter for PolarProfileStats.Report.adc()
      Returns:
      direction distribution coherence ([0-1], unitless)

    • getOrientationDistributionCoherence

      public double getOrientationDistributionCoherence()
      Convenience getter for PolarProfileStats.Report.odc()
      Returns:
      orientation distribution coherence ([0-1], unitless)

    • getPreferredDirection

      public double getPreferredDirection()
      Convenience getter for PolarProfileStats.Report.pd()
      Returns:
      preferred direction in degrees, normalized to [0, 360[ degrees

    • getPreferredOrientation

      public double getPreferredOrientation()
      Convenience getter for PolarProfileStats.Report.po()
      Returns:
      preferred orientation in degrees, normalized to [0, 180[ degrees

    • getPlot

      public SNTChart getPlot()
      Returns:
      The polar plot using default settings

    • getPlot

      public SNTChart getPlot(String colormap)
      Returns the polar plot using the specified colormap.
      Parameters:
      colormap - the color name (e.g., "fire", "viridis", etc.)
      Returns:
      The polar plot using default settings
      See Also:

    • getPlot

      public SNTChart getPlot(net.imglib2.display.ColorTable colorTable)
      Returns the polar plot using the specified colormap.
      Parameters:
      colorTable - the colorTable. Ignored if null
      Returns:
      The polar plot
      See Also:
      • ColorTables

    • getXValues

      public double[] getXValues()
      Specified by:
      getXValues in interface ShollStats

    • getYValues

      public double[] getYValues()
      Specified by:
      getYValues in interface ShollStats

    • getYValues

      public double[] getYValues(boolean asCumulativeFrequencies)
      Specified by:
      getYValues in interface ShollStats

    • getFitYValues

      public double[] getFitYValues()
      Specified by:
      getFitYValues in interface ShollStats

    • getFitYValues

      public double[] getFitYValues(boolean asCumulativeFrequencies)
      Specified by:
      getFitYValues in interface ShollStats

    • validFit

      public boolean validFit()
      Specified by:
      validFit in interface ShollStats

    • getN

      public int getN()
      Specified by:
      getN in interface ShollStats

    • getProfile

      public Profile getProfile()
      Specified by:
      getProfile in interface ShollStats