Package sc.fiji.snt.analysis.growth

Class GrowthAnalyzer

java.lang.Object
sc.fiji.snt.analysis.growth.GrowthAnalyzer
public class GrowthAnalyzer extends Object
Core analyzer for time-lapse growth analysis of neuronal paths.

This class provides ways to quantify neuronal growth patterns over time, including linear growth analysis (overall growth rates obtained from linear regression), phase-based growth detection (identification of distinct growth phases), and analysis of retraction/elongation events (phase boundary detection). It is designed to work with paths that have been matched across time frames using "{neurite #}" tags.

Growth phases are classified from instantaneous growth rates relative to the overall growth rate of each neurite:

  • LAG: Slow positive growth (0% to base threshold)
  • STEADY: Medium growth (base threshold to rapid threshold)
  • RAPID: Fast growth (above rapid threshold)
  • PLATEAU: Minimal growth (within ±base threshold of zero)
  • RETRACTION: Negative growth (below -base threshold)

Usage Example:


 // Create analyzer with default settings
 GrowthAnalyzer analyzer = new GrowthAnalyzer();

 // Configure
 analyzer.setRapidThresholdMultiple(1.8);  // threshold for rapid growth
 analyzer.setBaseThresholdFraction(0.25);  // sensitivity for phase detection
 analyzer.setPhaseSensitivity(0.4);        // sensitivity for phase boundary detection

 // Analyze time-matched paths
 Collection<Path> timeLapsePaths = getMatchedPaths();
 GrowthAnalysisResults results = analyzer.analyze(timeLapsePaths, frameInterval, "hours");

 // Access results
 Map<String, NeuriteGrowthData> growthData = results.getNeuriteGrowthData();
 for (NeuriteGrowthData data : growthData.values()) {
     System.out.printf("Neurite %s: %.2f μm/h growth rate, %d phases\n",
         data.getNeuriteId(), data.getLinearGrowthRate(), data.getGrowthPhases().size());
 }
See Also:

  • Field Details

    • DEFAULT_BASE_THRESHOLD_FRACTION

      public static final double DEFAULT_BASE_THRESHOLD_FRACTION
      Default base threshold as fraction of overall growth rate for PLATEAU/LAG classification
      See Also:

    • DEFAULT_RAPID_THRESHOLD_MULTIPLE

      public static final double DEFAULT_RAPID_THRESHOLD_MULTIPLE
      Default rapid growth threshold as multiple of overall growth rate for RAPID classification
      See Also:

    • DEFAULT_PHASE_SENSITIVITY

      public static final double DEFAULT_PHASE_SENSITIVITY
      Default phase detection sensitivity (0.05-1.0 range, higher = more sensitive)
      See Also:

    • DEFAULT_RETRACTION_THRESHOLD

      public static final double DEFAULT_RETRACTION_THRESHOLD
      Default retraction threshold percentage
      See Also:

    • DEFAULT_MIN_PATH_LENGTH

      public static final double DEFAULT_MIN_PATH_LENGTH
      Default minimum path length for analysis
      See Also:

    • DEFAULT_MIN_TIME_POINTS

      public static final int DEFAULT_MIN_TIME_POINTS
      Default minimum time points required for analysis
      See Also:

    • DEFAULT_WINDOW_SIZE_FRACTION

      public static final double DEFAULT_WINDOW_SIZE_FRACTION
      Default window size fraction for change point detection
      See Also:

    • DEFAULT_ABSOLUTE_WINDOW_SIZE

      public static final int DEFAULT_ABSOLUTE_WINDOW_SIZE
      Default absolute window size in frames (used when useAbsoluteWindowSize is true)
      See Also:

    • DEFAULT_USE_ABSOLUTE_WINDOW_SIZE

      public static final boolean DEFAULT_USE_ABSOLUTE_WINDOW_SIZE
      Default setting for using absolute window size instead of fraction
      See Also:

    • DEFAULT_USE_GLOBAL_THRESHOLDS

      public static final boolean DEFAULT_USE_GLOBAL_THRESHOLDS
      Default setting for using global mean growth rate for thresholds
      See Also:

    • TAG_REGEX_PATTERN

      public static final String TAG_REGEX_PATTERN
      See Also:

  • Constructor Details

    • GrowthAnalyzer

      public GrowthAnalyzer()
      Creates a new GrowthAnalyzer with default parameters.

    • GrowthAnalyzer

      public GrowthAnalyzer(double plateauThresholdFraction, double rapidThresholdMultiple, double phaseSensitivity)
      Creates a new GrowthAnalyzer with custom threshold parameters.
      Parameters:
      plateauThresholdFraction - Fraction of overall growth rate for plateau threshold
      rapidThresholdMultiple - Multiple of overall growth rate for rapid threshold
      phaseSensitivity - Sensitivity for change point detection (0.1-2.0, lower = more sensitive)

  • Method Details

    • analyze

      public GrowthAnalysisResults analyze(Collection<Path> paths, double frameInterval, String timeUnits)
      Performs growth analysis on a collection of time-matched paths. I.e., extracts matched path groups, filters them based on minimum requirements, and performs linear growth analysis, phase detection, and event analysis for each group.
      Parameters:
      paths - Collection of paths with time-matching tags as assigned by PathMatcherCmd(e.g., "{neurite#1}", "{neurite#2}")
      frameInterval - Time interval between consecutive frames
      timeUnits - Units for time measurements (e.g., "hours", "minutes")
      Returns:
      GrowthAnalysisResults containing all analysis data
      Throws:
      IllegalArgumentException - if paths is null or empty, or if frameInterval ≤ 0

    • getBaseThresholdFraction

      public double getBaseThresholdFraction()
      Gets the current base threshold fraction for phase classification.
      Returns:
      Current base threshold fraction

    • setPlateauThreshold

      public void setPlateauThreshold(double plateauThresholdFraction)
      Sets the base threshold fraction for phase classification.

      This parameter determines the boundary between PLATEAU and other phases. Growth rates within ±(baseThreshold × overallRate) are classified as PLATEAU.

      Parameters:
      plateauThresholdFraction - Fraction of overall growth rate (typically 0.2-0.4)
      Throws:
      IllegalArgumentException - if fraction is not between 0.1 and 0.5

    • getRapidThresholdMultiple

      public double getRapidThresholdMultiple()
      Gets the current rapid threshold multiple.
      Returns:
      Current rapid threshold multiple

    • setRapidThreshold

      public void setRapidThreshold(double rapidThresholdMultiple)
      Sets the rapid threshold multiple for phase classification.

      Growth rates above (rapidThreshold × overallRate) are classified as RAPID.

      Parameters:
      rapidThresholdMultiple - Multiple of overall growth rate (typically 1.2-2.0)
      Throws:
      IllegalArgumentException - if multiple is not between 1.1 and 3.0

    • getPhaseSensitivity

      public double getPhaseSensitivity()
      Gets the current phase detection sensitivity.
      Returns:
      Current phase sensitivity

    • setPhaseSensitivity

      public void setPhaseSensitivity(double phaseSensitivity)
      Sets the phase detection sensitivity.

      Higher values make change point detection more sensitive (more phase transitions). Lower values make detection less sensitive (fewer, longer phases).

      Parameters:
      phaseSensitivity - Sensitivity parameter (0.05-1.0, higher = more sensitive)
      Throws:
      IllegalArgumentException - if sensitivity is not between 0.05 and 1.0

    • getRetractionThreshold

      public double getRetractionThreshold()
      Gets the current retraction threshold.
      Returns:
      Current retraction threshold percentage

    • setRetractionThreshold

      public void setRetractionThreshold(double retractionThreshold)
      Sets the retraction threshold as a fraction of length
      Parameters:
      retractionThreshold - Minimum decrease to classify as retraction (0.01-0.5)
      Throws:
      IllegalArgumentException - if threshold is not between 0.01 and 0.5

    • setMinPathLength

      public void setMinPathLength(double minPathLength)
      Sets the minimum path length for analysis inclusion.
      Parameters:
      minPathLength - Minimum path length in physical units
      Throws:
      IllegalArgumentException - if length is negative

    • setMinTimePoints

      public void setMinTimePoints(int minTimePoints)
      Sets the minimum number of time points required for analysis.
      Parameters:
      minTimePoints - Minimum number of time points (at least 2)
      Throws:
      IllegalArgumentException - if less than 2

    • getWindowSizeFraction

      public double getWindowSizeFraction()
      Gets the current window size fraction for change point detection.
      Returns:
      Current window size fraction (typically 0.05-0.25)

    • setWindowSizeFraction

      public void setWindowSizeFraction(double windowSizeFraction)
      Sets the window size fraction for change point detection.

      This parameter controls the size of the moving window used in change point detection algorithms. The actual window size is calculated as: windowSize = max(minSize, dataLength × fraction)

      Parameters:
      windowSizeFraction - Fraction of data length for window size (typically 0.05-0.25)
      Throws:
      IllegalArgumentException - if fraction is not between 0.05 and 0.5

    • isUseGlobalThresholds

      public boolean isUseGlobalThresholds()
      Gets whether global thresholds are used for phase classification.
      Returns:
      true if using global mean growth rate for thresholds, false if using per-neurite rates

    • setUseGlobalThresholds

      public void setUseGlobalThresholds(boolean useGlobalThresholds)
      Sets whether to use global thresholds for phase classification.

      This parameter determines how growth phase thresholds are calculated:

      • Global thresholds (true): Thresholds calculated relative to mean growth rate across all neurites
      • Per-neurite thresholds (false): Thresholds calculated relative to each individual neurite's growth rate
      Parameters:
      useGlobalThresholds - true to use global mean rate, false to use per-neurite rates

    • getAbsoluteWindowSize

      public int getAbsoluteWindowSize()
      Gets the current absolute window size in frames.
      Returns:
      Current absolute window size (used when useAbsoluteWindowSize is true)

    • setAbsoluteWindowSize

      public void setAbsoluteWindowSize(int absoluteWindowSize)
      Sets the absolute window size for change point detection in frames.

      This parameter is only used when useAbsoluteWindowSize is true.

      Parameters:
      absoluteWindowSize - Window size in frames (minimum 2)
      Throws:
      IllegalArgumentException - if window size is less than 2

    • isUseAbsoluteWindowSize

      public boolean isUseAbsoluteWindowSize()
      Gets whether absolute window size is used instead of fractional window size.
      Returns:
      true if using absolute window size, false if using fractional window size

    • setUseAbsoluteWindowSize

      public void setUseAbsoluteWindowSize(boolean useAbsoluteWindowSize)
      Sets whether to use absolute window size instead of fractional window size.

      Window size modes:

      • Absolute (true): Fixed window size in frames, consistent across all datasets
      • Fractional (false): Window size as percentage of data length, adaptive to dataset size
      Parameters:
      useAbsoluteWindowSize - true to use absolute window size, false to use fractional