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

Class LinearProfileStats

java.lang.Object
org.scijava.AbstractContextual
org.scijava.command.ContextCommand
sc.fiji.snt.analysis.sholl.math.LinearProfileStats
All Implemented Interfaces:
Runnable, org.scijava.Cancelable, org.scijava.command.Command, org.scijava.Contextual, org.scijava.plugin.SciJavaPlugin, ShollStats
public class LinearProfileStats extends org.scijava.command.ContextCommand implements ShollStats
Retrieves descriptive statistics and calculates Sholl Metrics from sampled Sholl profiles, including those relying on polynomial fitting. Fitting to polynomials of arbitrary degree is supported. Relies heavily on the org.apache.commons.math3 package.
Author:
Tiago Ferreira

  • Field Details

    • UNASSIGNED_VALUE

      protected static final double UNASSIGNED_VALUE
      See Also:

    • inputRadii

      protected final double[] inputRadii

    • inputCounts

      protected final double[] inputCounts

    • profile

      protected final Profile profile

    • nPoints

      protected int nPoints

    • fCounts

      protected double[] fCounts

    • plot

      protected ShollPlot plot

    • logger

      protected Logger logger

  • Constructor Details

    • LinearProfileStats

      public LinearProfileStats(Profile profile)
      Instantiates the Linear Profile Statistics.
      Parameters:
      profile - the profile to be analyzed

    • LinearProfileStats

      public LinearProfileStats(Profile profile, ShollStats.DataMode dataMode)
      Instantiates the Linear Profile Statistics.
      Parameters:
      profile - the profile to be analyzed

  • Method Details

    • getCentroid

      public ShollPoint getCentroid(boolean fittedData)
      Retrieves the centroid from all pairs of data (radius, inters. counts).
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the centroid {x,y} coordinates

    • getCentroid

      public ShollPoint getCentroid()
      Returns:
      getCentroid(false)

    • getPolygonCentroid

      public ShollPoint getPolygonCentroid(boolean fittedData)
      Calculates the centroid from all (radius, inters. counts) pairs assuming such points define a non-self-intersecting closed polygon. Implementation from wikipedia.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the point by the centroid {x,y} coordinates

    • getPolygonCentroid

      public ShollPoint getPolygonCentroid()
      Returns:
      getPolygonCentroid(false)

    • getEnclosingRadius

      public double getEnclosingRadius(boolean fittedData, double cutoff)
      Returns the largest radius associated with at least the number of specified counts.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      cutoff - the cutoff for intersection counts
      Returns:
      the largest radius associated with the same or more cutoff counts

    • getEnclosingRadius

      public double getEnclosingRadius(double cutoff)
      Parameters:
      cutoff - the cutoff for intersection counts
      Returns:
      getEnclosingRadius(false, cutoff)

    • getIntersectingRadii

      public int getIntersectingRadii(boolean fittedData)
      Returns the number of intersecting radii.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the count of all radii associated with at least one intersection

    • getIntersectingRadii

      public int getIntersectingRadii()
      Returns:
      getIntersectingRadii(false)

    • getKurtosis

      public double getKurtosis(boolean fittedData)
      Calculates the kurtosis.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      kurtosis of intersection counts

    • getKurtosis

      public double getKurtosis()
      Returns:
      getKurtosis(false)

    • getMaxima

      public ArrayList<ShollPoint> getMaxima(boolean fittedData)
      Returns a list of all the points in the linear Sholl profile associated with the highest intersections count
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the list of points of all maxima

    • getMaxima

      public ArrayList<ShollPoint> getMaxima()
      Returns:
      getMaxima(false)

    • getCenteredMaximum

      public ShollPoint getCenteredMaximum(boolean fittedData)
      Returns the average coordinates of all maxima.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the averaged x,y coordinates of maxima

    • getCenteredMaximum

      public ShollPoint getCenteredMaximum()
      Returns:
      getCenteredMaximum(false)

    • getMean

      public double getMean(boolean fittedData)
      Calculates the arithmetic mean.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the mean of intersection counts

    • getMean

      public double getMean()
      Returns:
      getMean(false)

    • getIndexOfRadius

      public int getIndexOfRadius(double radius)
      Returns the closest index of sampled distances associated with the specified value
      Parameters:
      radius - the query value
      Returns:
      the position index (zero-based) or -1 if no index could be calculated

    • getIndexOfInters

      public int getIndexOfInters(boolean fittedData, double inters)
      Returns the closest index of the intersections data associated with the specified value
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      inters - the query value
      Returns:
      the position index (zero-based) or -1 if no index could be calculated

    • fitPolynomial

      public void fitPolynomial(int degree)
      Fits sampled data to a polynomial function and keeps the fit in memory.
      Parameters:
      degree - Degree of the polynomial to be fitted
      Throws:
      org.apache.commons.math3.exception.NullArgumentException - if the computed polynomial coefficients were null
      org.apache.commons.math3.exception.NoDataException - if the computed polynomial coefficients were empty
      org.apache.commons.math3.exception.ConvergenceException - if optimization failed

    • findBestFit

      public int findBestFit(int fromDegree, int toDegree, double minRSquared, double pvalue)
      Computes the 'best fit' polynomial between a specified range of degrees for this profile and keeps the fit in memory.

      Note that in some edge cases specified constrains may be bypassed: E.g., If the profile is constant, a constant function is fitted. If the profile contains only two data points, a linear function is fitted

      Parameters:
      fromDegree - the lowest degree to be considered. Will be set to (ShollStats.getN()-1) if higher than (ShollStats.getN()-1).
      toDegree - the highest degree to be considered. Will be set to (ShollStats.getN()-1) if higher than (ShollStats.getN()-1)
      minRSquared - the lowest value for adjusted RSquared. Only fits associated with an equal or higher value will be considered
      pvalue - the two-sample Kolmogorov-Smirnov (K-S) test statistic (p-value) used to discard 'unsuitable fits'. It is used to evaluate the null hypothesis that profiled data and polynomial fit represent samples drawn from the same probability distribution. Set it to -1 to skip K-S testing.
      Returns:
      the degree of the 'best fit' polynomial or -1 if no suitable fit could be performed.

    • findBestFit

      public int findBestFit(int fromDegree, int toDegree, org.scijava.prefs.PrefService prefService)
      Runs findBestFit(int, int, double, double) using the preferences specified by the user using the ShollAnalysisPrefsCmd command.
      Parameters:
      fromDegree - the lowest degree to be considered. See findBestFit(int, int, double, double)
      toDegree - the highest degree to be considered. See findBestFit(int, int, double, double)
      prefService - the PrefService used to read preferences
      Returns:
      the degree of the 'best fit' polynomial. See findBestFit(int, int, double, double)

    • getXValues

      public double[] getXValues()
      Returns the abscissae of the sampled linear plot for sampled data.
      Specified by:
      getXValues in interface ShollStats
      Returns:
      the sampled distances.

    • getYValues

      public double[] getYValues()
      Returns the ordinates of the sampled linear plot of sampled data.
      Specified by:
      getYValues in interface ShollStats
      Returns:
      the sampled intersection counts.

    • getFitYValues

      public double[] getFitYValues()
      Returns the ordinates of the sampled linear plot of fitted data.
      Specified by:
      getFitYValues in interface ShollStats
      Returns:
      the y-values of the polynomial fit retrieved at sampling distances
      Throws:
      NullPointerException - if fitPolynomial(int) has not been called

    • getPolynomial

      public org.apache.commons.math3.analysis.polynomials.PolynomialFunction getPolynomial()
      Gets the polynomial function.
      Returns:
      the polynomial
      Throws:
      NullPointerException - if fitPolynomial(int) has not been called

    • getPolynomialDegree

      public int getPolynomialDegree()
      Returns the degree of the polynomial.
      Returns:
      the polynomial degree
      Throws:
      NullPointerException - if fitPolynomial(int) has not been called

    • getPolynomialAsString

      public String getPolynomialAsString(boolean detailed)
      Returns a string describing the polynomial fit
      Parameters:
      detailed - if true description includes extended details on the fit
      Returns:
      the description, e.g., "8th degree", or an empty string if no valid fit exists

    • getPolynomialMaxima

      public Set<ShollPoint> getPolynomialMaxima(double lowerBound, double upperBound, double initialGuess)
      Calculates local maxima (critical points at which the derivative of the polynomial is zero) within the specified interval.
      Parameters:
      lowerBound - the lower bound of the interval
      upperBound - the upper bound of the interval
      initialGuess - initial guess for a solution (solver's starting point)
      Returns:
      the set of Points defined by the {x,y} coordinates of maxima (sorted by descendant order)
      Throws:
      org.apache.commons.math3.exception.TooManyEvaluationsException - if the maximum number of evaluations is exceeded when solving for one of the roots
      NullPointerException - if fitPolynomial(int) has not been called

    • getMaxEvaluations

      public int getMaxEvaluations()
      Gets the function evaluation limit for solvers
      Returns:
      the set maximum of evaluations (1000 by default)

    • setMaxEvaluations

      public void setMaxEvaluations(int maxEval)
      Sets the function evaluation limit for solvers.
      Parameters:
      maxEval - the new maximum of evaluations

    • getRSquaredOfFit

      public double getRSquaredOfFit(boolean adjusted)
      Returns RSquared of the polynomial fit. Implementation from wikipedia. \( R^2 = 1 - (SSres/SStot) \) with \( SSres = SUM(i) (yi - fi)^2 \) \( SStot = SUM(i) (yi - yavg)^2 \)
      Parameters:
      adjusted - if true returns adjusted RSquared, i.e., adjusted for the number of terms of the polynomial model
      Returns:
      RSquared, a measure for the goodness of fit
      Throws:
      NullPointerException - if fitPolynomial(int) has not been called

    • getMeanValueOfPolynomialFit

      public double getMeanValueOfPolynomialFit(String integrator, double lowerBound, double upperBound)
      Gets the mean value of polynomial fit.
      Parameters:
      integrator - the integration method to retrieve the integral of the polynomial fit. Either "Simpson" (the default), or "Romberg" (case-insensitive)
      lowerBound - the lower bound (smallest radius) for the interval
      upperBound - the upper bound (largest radius) for the interval
      Returns:
      the mean value of polynomial fit
      Throws:
      org.apache.commons.math3.exception.MathIllegalArgumentException - if bounds do not satisfy the integrator requirements
      org.apache.commons.math3.exception.TooManyEvaluationsException - if the maximum number of function evaluations is exceeded by the integrator
      org.apache.commons.math3.exception.MaxCountExceededException - if the maximum iteration count is exceeded by the integrator
      NullPointerException - if fitPolynomial(int) has not been called

    • getMeanValueOfPolynomialFit

      public double getMeanValueOfPolynomialFit(double lowerBound, double upperBound)
      Calculates the mean value of polynomial fit using the default integration method (Simpson's).
      Parameters:
      lowerBound - the lower bound (smallest radius) for the interval
      upperBound - the upper bound (largest radius) for the interval
      Returns:
      the mean value of polynomial fit, or Double.NaN if calculation failed.
      Throws:
      NullPointerException - if fitPolynomial(int) has not been called

    • getMedian

      public double getMedian(boolean fittedData)
      Calculates the median.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the median of intersection counts

    • getMedian

      public double getMedian()
      Returns:
      getMedian(false)

    • setPrimaryBranches

      public void setPrimaryBranches(int nBranches)
      Sets the number of primary branches associated with this profile, used to calculate ramification indices. When the number is set to -1 (the default), the number of primary branches is inferred from the number of intersections at starting radius.
      Parameters:
      nBranches - the new primary branches
      See Also:

    • isPrimaryBranchesInferred

      public boolean isPrimaryBranchesInferred()
      Checks whether the number of primary branches is being inferred from the number of intersections at starting radius or if it has been set explicitly.
      Returns:
      true, if number of primary branches is being inferred
      See Also:

    • getPrimaryBranches

      public double getPrimaryBranches(boolean fittedData)
      Returns intersection counts at the smallest radius (inferred no. of primary branches), or the number of the actual number of primary branches specified by setPrimaryBranches(int).
      Parameters:
      fittedData - If true, and setPrimaryBranches(int) has not been called, calculation is performed on polynomial fitted values, otherwise from sampled data. It is ignored if the number of primary branches has been successfully specified by calling setPrimaryBranches(int)
      Returns:
      the number of primary branches
      See Also:

    • getPrimaryBranches

      public double getPrimaryBranches()
      Returns:
      getPrimaryBranches(false)
      See Also:

    • getRamificationIndex

      public double getRamificationIndex(boolean fittedData)
      Calculates the ramification index (the highest intersections count divided by the n. of primary branches). If the number of primary branches has not been specified, it is assumed to be the n. intersections at starting radius.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the ramification index
      See Also:

    • getBranchingIndex

      public double getBranchingIndex(boolean fittedData)
      Calculates the branching index (BI) as defined in PMID 24503022(doi: 10.1016/j.jneumeth.2014.01.016). Note that this index is very sensitive to radius step size.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the branching index
      See Also:

    • getRamificationIndex

      public double getRamificationIndex()
      Returns:
      getRamificationIndex(false)

    • getMax

      public double getMax(boolean fittedData)
      Returns the largest value of intersection count.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the largest value of intersection counts

    • getMax

      public double getMax()
      Returns:
      getMax(false)

    • getMin

      public double getMin(boolean fittedData)
      Returns the lowest value of intersection count.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the lowest value of intersection counts

    • getMin

      public double getMin()
      Returns:
      getMin(false)

    • getSkewness

      public double getSkewness(boolean fittedData)
      Calculates the skewness.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the skewness of intersection counts

    • getSkewness

      public double getSkewness()
      Returns:
      getSkewness(false)

    • getSum

      public double getSum(boolean fittedData)
      Calculates the sum.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the sum of intersection counts

    • getSum

      public double getSum()
      Returns:
      getSum(false)

    • getSumSq

      public double getSumSq(boolean fittedData)
      Calculates the sum of the squared values.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the sum of the squared values of intersection counts

    • getSumSq

      public double getSumSq()
      Returns:
      getSumSq(false)

    • getVariance

      public double getVariance(boolean fittedData)
      Calculates the variance.
      Parameters:
      fittedData - If true, calculation is performed on polynomial fitted values, otherwise from sampled data
      Returns:
      the variance of intersection counts

    • plot

      public ShollPlot plot()

    • getProfileCopy

      protected Profile getProfileCopy()

    • getVariance

      public double getVariance()
      Returns:
      getVariance(false)

    • validFit

      public boolean validFit()
      Checks if valid fitted data exists.
      Specified by:
      validFit in interface ShollStats
      Returns:
      true if polynomial fitted data exists

    • getKStestOfFit

      public double getKStestOfFit()
      Returns the two-sample Kolmogorov-Smirnov (K-S) test between the polynomial fit and sampled intersections as a measurement of goodness of fit.
      Returns:
      the test statistic (p-value) used to evaluate the null hypothesis that sampled data and polynomial fit represent samples drawn from the same probability distribution
      Throws:
      NullPointerException - if curve fitting has not been performed
      org.apache.commons.math3.exception.InsufficientDataException - if sampled data contains fewer than two data points

    • getRSquaredOfFit

      public double getRSquaredOfFit()

    • getPlot

      public ShollPlot getPlot(boolean cumulativeFrequencies)

    • getAdjustedRSquaredOfFit

      protected double getAdjustedRSquaredOfFit(int p)

    • getIndex

      protected int getIndex(double[] array, double value)

    • validateFit

      protected void validateFit()

    • debug

      protected void debug(Object msg)

    • setLogger

      public void setLogger(Logger logger)

    • setLogger

      public void setLogger(Logger logger, boolean debug)

    • setDebug

      public void setDebug(boolean debug)

    • setContext

      public void setContext(org.scijava.Context context)
      Specified by:
      setContext in interface org.scijava.Contextual

    • getYValues

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

    • getN

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

    • getFitYValues

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

    • getProfile

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

    • getDataMode

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

    • setDataMode

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

    • run

      public void run()
      Specified by:
      run in interface Runnable