Package sc.fiji.snt.analysis

Class TreeStatistics

java.lang.Object
org.scijava.AbstractContextual
org.scijava.command.ContextCommand
sc.fiji.snt.analysis.TreeStatistics
All Implemented Interfaces:
Runnable, org.scijava.Cancelable, org.scijava.command.Command, org.scijava.Contextual, org.scijava.plugin.SciJavaPlugin
Direct Known Subclasses:
MultiTreeStatistics, PathOrderAnalysisCmd, PathStatistics, TreeAnalyzer
public class TreeStatistics extends org.scijava.command.ContextCommand
Computes summary and descriptive statistics from properties of Paths and Nodes in a Tree, including convenience methods to plot distributions of such data. For analysis of groups of Trees have a look at MultiTreeStatistics and GroupedTreeStatistics.
Author:
Tiago Ferreira, Cameron Arshadi

  • Field Details

  • Constructor Details

    • TreeStatistics

      public TreeStatistics(Tree tree)
      Instantiates a new instance from a collection of Paths
      Parameters:
      tree - the collection of paths to be analyzed

    • TreeStatistics

      public TreeStatistics(Collection<Path> paths, String label)
      Instantiates Tree statistics from a collection of paths.
      Parameters:
      paths - Collection of Paths to be analyzed. Note that null Paths are discarded. Also, when a Path has been fitted and Path.getUseFitted() is true, its fitted 'flavor' is used.
      label - the label describing the path collection
      See Also:

  • Method Details

    • getAllMetrics

      public static List<String> getAllMetrics()
      Gets the list of supported metrics.
      Returns:
      the list of available metrics

    • getMetrics

      public static List<String> getMetrics(String type)
      Gets a subset of supported metrics.
      Parameters:
      type - the type. Either 'legacy' (metrics supported up to SNTv4.0.5), "safe" (metrics that can be computed from invalid graphs), 'common' (commonly used metrics), 'quick' (used by the 'quick measure' GUI commands), or 'all' (shortcut to getAllMetrics())
      Returns:
      the list metrics

    • getMetrics

      @Deprecated public static List<String> getMetrics()
      Deprecated.
      Gets the list of most commonly used metrics.
      Returns:
      the list of commonly used metrics.
      See Also:

    • getAnnotatedLength

      protected static Map<BrainAnnotation,Double> getAnnotatedLength(DirectedWeightedGraph graph, int level, char lr, boolean norm)

    • getAnnotatedLengthsByHemisphere

      protected static Map<BrainAnnotation,double[]> getAnnotatedLengthsByHemisphere(DirectedWeightedGraph graph, int level, boolean norm)

    • fromCollection

      public static TreeStatistics fromCollection(Collection<Tree> trees, String metric)
      Creates a TreeStatistics instance from a group of Trees and a specific metric for convenient retrieval of histograms
      Parameters:
      trees - the collection of trees
      metric - the measurement
      Returns:
      the TreeStatistics instance

    • tryReallyHardToGuessMetric

      protected static String tryReallyHardToGuessMetric(String guess)

    • getNormalizedMeasurement

      protected static String getNormalizedMeasurement(String measurement)

    • isExactMetricMatch

      public static boolean isExactMetricMatch()
      Checks if 'fuzzy matching' of metrics is active.
      Returns:
      true if exact string matching is active, false if approximate matching is active

    • setExactMetricMatch

      public static void setExactMetricMatch(boolean exactMetricMatch)
      Sets whether approximate string matching ('fuzzy matching') should be used when retrieving metrics.
      Parameters:
      exactMetricMatch - exact string matching is used if true, approximate if false

    • getMetric

      public Number getMetric(String metric) throws UnknownMetricException
      Computes the specified metric.
      Parameters:
      metric - the single-value metric to be computed (case-insensitive). While it is expected to be an element of getAllMetrics(), if isExactMetricMatch() is set, metric can be specified in a loose manner: If metric is not initially recognized, a heuristic will match it to the closest entry in the list of possible metrics. E.g., "# bps", "n junctions", will be both mapped to N_BRANCH_POINTS. Details on the matching are printed to the Console when in debug mode.
      Returns:
      the computed value (average if metric is associated with multiple values)
      Throws:
      UnknownMetricException - if metric is not recognized
      See Also:

    • restrictToSWCType

      public void restrictToSWCType(int... types)
      Restricts analysis to Paths sharing the specified SWC flag(s).
      Parameters:
      types - the allowed SWC flags (e.g., Path.SWC_AXON, etc.)

    • resetRestrictions

      public void resetRestrictions()
      Removes any filtering restrictions that may have been set. Once called, subsequent analysis will use all paths initially parsed by the constructor. Does nothing if no paths are currently being excluded from the analysis.

    • getParsedTree

      public Tree getParsedTree()
      Returns the set of parsed Paths.
      Returns:
      the set of paths currently being considered for analysis.
      See Also:

    • summarize

      public void summarize(boolean groupByType)
      Outputs a summary of the current analysis to the measurements table using the default Tree label.
      Parameters:
      groupByType - if true measurements are grouped by SWC-type flag
      See Also:

    • summarize

      public void summarize(String rowHeader, boolean groupByType)
      Outputs a summary of the current analysis to the measurements table.
      Parameters:
      rowHeader - the String to be used as label for the summary
      groupByType - if true measurements are grouped by SWC-type flag
      See Also:

    • getNextRow

      protected int getNextRow(String rowHeader)

    • getSWCTypesAsString

      protected String getSWCTypesAsString()

    • measure

      public void measure(Collection<String> metrics, boolean groupByType)
      Measures this Tree, outputting the result to the measurements table using default row labels. If a Context has been specified, the table is updated. Otherwise, table contents are printed to Console.
      Parameters:
      metrics - the list of metrics to be computed. When null or an empty collection is specified, getMetrics() is used.
      groupByType - if false, metrics are computed to all branches in the Tree. If true, measurements will be split by SWC type annotations (axon, dendrite, etc.)
      See Also:

    • measure

      public void measure(String rowHeader, Collection<String> metrics, boolean groupByType)
      Measures this Tree, outputting the result to the measurements table. If a Context has been specified, the table is updated. Otherwise, table contents are printed to Console.
      Parameters:
      rowHeader - the row header label
      metrics - the list of metrics to be computed. When null or an empty collection is specified, getMetrics() is used.
      groupByType - if false, metrics are computed to all branches in the Tree. If true, measurements will be split by SWC type annotations (axon, dendrite, etc.)
      See Also:

    • getSummaryStats

      public org.apache.commons.math3.stat.descriptive.SummaryStatistics getSummaryStats(String metric)
      Computes the SummaryStatistics for the specified measurement.
      Parameters:
      metric - the measurement (N_NODES, NODE_RADIUS, etc.)
      Returns:
      the SummaryStatistics object.

    • getDescriptiveStats

      public org.apache.commons.math3.stat.descriptive.DescriptiveStatistics getDescriptiveStats(String metric)
      Computes the DescriptiveStatistics for the specified measurement.
      Parameters:
      metric - the measurement (N_NODES, NODE_RADIUS, etc.)
      Returns:
      the DescriptiveStatistics object.

    • setTable

      public void setTable(org.scijava.table.GenericTable table, String title)
      Sets the measurements table.
      Parameters:
      table - the table to be used by this TreeStatistics instance
      title - the title of the table display window

    • getTable

      public org.scijava.table.DefaultGenericTable getTable()
      Gets the table currently being used by this TreeStatistics instance
      Returns:
      the table

    • setTable

      public void setTable(org.scijava.table.GenericTable table)
      Sets the table for this TreeStatistics instance.
      Parameters:
      table - the table to be used by this TreeStatistics instance
      See Also:

    • getAnnotatedLength

      public Map<BrainAnnotation,Double> getAnnotatedLength(int level)
      Retrieves the amount of cable length present on each brain compartment innervated by the analyzed neuron.
      Parameters:
      level - the ontological depth of the compartments to be considered
      Returns:
      the map containing the brain compartments as keys, and cable lengths as values.
      See Also:

    • getAnnotatedLength

      public Map<BrainAnnotation,Double> getAnnotatedLength(int level, String hemisphere)
      Retrieves the amount of cable length present on each brain compartment innervated by the analyzed neuron.
      Parameters:
      level - the ontological depth of the compartments to be considered
      hemisphere - typically 'left' or 'right'. The hemisphere flag ( BrainAnnotation.LEFT_HEMISPHERE or BrainAnnotation.RIGHT_HEMISPHERE) is extracted from the first character of the string (case-insensitive). Ignored if not a recognized option
      Returns:
      the map containing the brain compartments as keys, and cable lengths as values.
      See Also:

    • getAnnotatedLength

      public Map<BrainAnnotation,Double> getAnnotatedLength(int level, String hemisphere, boolean norm)
      Retrieves the amount of cable length present on each brain compartment innervated by the analyzed neuron.
      Parameters:
      level - the ontological depth of the compartments to be considered
      hemisphere - typically 'left' or 'right'. The hemisphere flag ( BrainAnnotation.LEFT_HEMISPHERE or BrainAnnotation.RIGHT_HEMISPHERE) is extracted from the first character of the string (case-insensitive). Ignored if not a recognized option
      norm - whether length should be normalized to the cells' cable length
      Returns:
      the map containing the brain compartments as keys, and cable lengths as values.
      See Also:

    • getAnnotatedLengthsByHemisphere

      public Map<BrainAnnotation,double[]> getAnnotatedLengthsByHemisphere(int level)
      Retrieves the amount of cable length present on each brain compartment innervated by the analyzed neuron in the two brain hemispheres. Lengths are absolute and not normalized to the cells' cable length.
      Parameters:
      level - the ontological depth of the compartments to be considered
      Returns:
      the map containing the brain compartments as keys, and cable lengths per hemisphere as values.
      See Also:

    • getAnnotatedLengthHistogram

      public SNTChart getAnnotatedLengthHistogram()
      Retrieves the of cable length frequencies across brain areas.
      Returns:
      the histogram of cable length frequencies.

    • getAnnotatedLengthHistogram

      public SNTChart getAnnotatedLengthHistogram(int depth)
      Retrieves the histogram of cable length frequencies across brain areas of the specified ontology level.
      Parameters:
      depth - the ontological depth of the compartments to be considered
      Returns:
      the annotated length histogram
      See Also:

    • getAnnotatedLengthHistogram

      public SNTChart getAnnotatedLengthHistogram(int depth, String hemisphere)
      Retrieves the histogram of cable length frequencies across brain areas of the specified ontology level across the specified hemisphere.
      Parameters:
      depth - the ontological depth of the compartments to be considered
      hemisphere - 'left', 'right' or 'ratio' (case-insensitive). Ignored if not a recognized option
      Returns:
      the annotated length histogram
      See Also:

    • getAnnotatedLengthsByHemisphereHistogram

      protected SNTChart getAnnotatedLengthsByHemisphereHistogram(int depth)

    • getAnnotatedLengthHistogram

      protected SNTChart getAnnotatedLengthHistogram(Map<BrainAnnotation,Double> map, int depth, String secondaryLabel)

    • getHistogram

      public SNTChart getHistogram(String metric)
      Retrieves the histogram of relative frequencies histogram for a univariate measurement. The number of bins is determined using the Freedman-Diaconis rule.
      Parameters:
      metric - the measurement (N_NODES, NODE_RADIUS, etc.)
      Returns:
      the frame holding the histogram

    • getPolarHistogram

      public SNTChart getPolarHistogram(String metric)
      Assembles a polar histogram for the specified metric (assumed to be an angular measurements (e.g., branch angles, path orientations).
      Parameters:
      metric - the metric to be plotted (e.g., BRANCH_EXTENSION_ANGLE_XY, PATH_EXT_ANGLE_XY, etc.)
      Returns:
      the polar histogram chart
      Throws:
      UnknownMetricException - if the metric is not recognized
      See Also:

    • getFlowPlot

      public SNTChart getFlowPlot(String feature, Collection<BrainAnnotation> annotations, boolean normalize)
      Assembles a Flow plot (aka Sankey diagram) for the specified feature using "mean" as integration statistic, and no cutoff value.
      See Also:

    • getFlowPlot

      public SNTChart getFlowPlot(String feature, int depth)
      Assembles a Flow plot (aka Sankey diagram) for the specified feature using "mean" as integration statistic, no cutoff value, and all of the brain regions of the specified ontology depth.
      Parameters:
      feature - the feature ("Cable length", "No. of branch points", "No. of tips", etc.).
      depth - the ontological depth of the compartments to be considered
      Returns:
      the flow plot
      See Also:

    • getFlowPlot

      public SNTChart getFlowPlot(String feature, int depth, double cutoff, boolean normalize)
      Assembles a Flow plot (aka Sankey diagram) for the specified feature using "mean" as integration statistic, no cutoff value, and all of the brain regions of the specified ontology depth. *
      Parameters:
      feature - the feature ("Cable length", "No. of branch points", "No. of tips", etc.)
      depth - the ontological depth of the compartments to be considered
      cutoff - a filtering option. If the computed feature for an annotation is below this value, that annotation is excluded from the plot * @param normalize If true, values are retrieved as ratios. E.g., If feature is "Cable length", and cutoff 0.1, BrainAnnotations in annotations associated with less than 10% of cable length are ignored.
      Returns:
      the flow plot

    • getFlowPlot

      public SNTChart getFlowPlot(String feature, Collection<BrainAnnotation> annotations)
      Assembles a Flow plot (aka Sankey diagram) for the specified feature using "mean" as integration statistic, and no cutoff value.
      See Also:

    • getFlowPlot

      public SNTChart getFlowPlot(String feature, Collection<BrainAnnotation> annotations, String statistic, double cutoff, boolean normalize)
      Assembles a Flow plot (aka Sankey diagram) for the specified feature.
      Parameters:
      feature - the feature ("Cable length", "No. of branch points", "No. of tips", etc.). Note that the majority of getAllMetrics() metrics are currently not supported.
      annotations - the BrainAnnotations to be queried. Null not allowed.
      statistic - the integration statistic (lower case). Either "mean", "sum", "min" or "max". Null not allowed.
      cutoff - a filtering option. If the computed feature for an annotation is below this value, that annotation is excluded from the plot
      normalize - If true, values are retrieved as ratios. E.g., If feature is "Cable length", and cutoff 0.1, BrainAnnotations in annotations associated with less than 10% of cable length are ignored.
      Returns:
      the SNTChart holding the flow plot

    • getHistogram

      protected SNTChart getHistogram(String normMeasurement, sc.fiji.snt.analysis.AnalysisUtils.HistogramDatasetPlus datasetPlus)

    • assembleStats

      protected void assembleStats(sc.fiji.snt.analysis.TreeStatistics.StatisticsInstance stat, String measurement)

    • lastDstatsCanBeRecycled

      protected boolean lastDstatsCanBeRecycled(String normMeasurement)

    • run

      public void run()
      Generates detailed summaries in which measurements are grouped by SWC-type flags
      See Also:

    • getShollMetric

      protected Number getShollMetric(String metric)

    • getNodeStatistics

      public NodeStatistics<SWCPoint> getNodeStatistics()
      Convenience method to initialize a NodeStatistics from all the nodes of the Tree being analyzed.
      Returns:
      the NodeStatistics instance

    • getNodeStatistics

      public NodeStatistics<SWCPoint> getNodeStatistics(String type)
      Convenience method to initialize a NodeStatistics from a subset of the nodes of the Tree being analyzed.
      Parameters:
      type - the vertex type (e.g., "tips"/"end-points", "junctions"/"branch points", "all")
      Returns:
      the NodeStatistics instance
      See Also:

    • getConvexHullMetric

      public double getConvexHullMetric(String metric)
      Convenience method to obtain a single-value metric from ConvexHullAnalyzer
      Parameters:
      metric - the metric to be retrieved, one of ConvexHullAnalyzer.supportedMetrics()
      Returns:
      the convex hull metric
      See Also:

    • getConvexAnalyzer

      public ConvexHullAnalyzer getConvexAnalyzer()
      Gets the ConvexHullAnalyzer instance associated with this TreeStatistics instance.
      Returns:
      the ConvexHullAnalyzer instance

    • getRootAngleMetric

      public double getRootAngleMetric(String metric)
      Convenience method to obtain a single-value metric from RootAngleAnalyzer.
      Parameters:
      metric - the metric to be retrieved, one of RootAngleAnalyzer.supportedMetrics()
      Returns:
      the root angle metric
      See Also:

    • getRootAngleAnalyzer

      public RootAngleAnalyzer getRootAngleAnalyzer() throws IllegalArgumentException
      Gets the RootAngleAnalyzer instance associated with this TreeStatistics instance.
      Returns:
      the RootAngleAnalyzer instance
      Throws:
      IllegalArgumentException

    • getAnnotations

      public Set<BrainAnnotation> getAnnotations()
      Retrieves the brain compartments (neuropil labels) associated with the Tree being measured innervated by the analyzed neuron.
      Returns:
      the set of brain compartments (BrainAnnotations)
      See Also:

    • getAnnotations

      public Set<BrainAnnotation> getAnnotations(int depth)
      Retrieves the brain compartments (neuropil labels) associated with the Tree being measured innervated by the analyzed neuron.
      Parameters:
      depth - the max. ontological depth of the compartments to be retrieved
      Returns:
      the set of brain compartments (BrainAnnotations)
      See Also:

    • getPrimaryLength

      public double getPrimaryLength()
      Gets the cable length of primary branches.
      Returns:
      the length sum of all primary branches
      See Also:

    • getInnerLength

      public double getInnerLength()
      Gets the cable length of inner branches
      Returns:
      the length sum of all inner branches
      See Also:

    • getTerminalLength

      public double getTerminalLength()
      Gets the cable length of terminal branches
      Returns:
      the length sum of all terminal branches
      See Also:

    • getHighestPathOrder

      public int getHighestPathOrder()
      Gets the highest path order of the analyzed tree
      Returns:
      the highest Path order, or -1 if Paths in the Tree have no defined order
      See Also:

    • isValid

      public boolean isValid()
      Checks whether this tree is topologically valid, i.e., contains only one root and no loops.
      Returns:
      true, if Tree is valid, false otherwise

    • getStrahlerNumber

      public int getStrahlerNumber() throws IllegalArgumentException
      Gets the highest Strahler number of the analyzed tree.
      Returns:
      the highest Strahler (root) number order
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getStrahlerAnalyzer

      public StrahlerAnalyzer getStrahlerAnalyzer() throws IllegalArgumentException
      Gets the StrahlerAnalyzer instance associated with this TreeStatistics instance
      Returns:
      the StrahlerAnalyzer instance associated with this TreeStatistics instance
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getShollAnalyzer

      public ShollAnalyzer getShollAnalyzer()
      Gets the ShollAnalyzer instance associated with this TreeStatistics instance. Note that changes to ShollAnalyzer must be performed before retrieving Sholl related metrics, i.e., before calling measure(Collection, boolean), etc.
      Returns:
      the ShollAnalyzer instance associated with this TreeStatistics instance

    • getStrahlerBifurcationRatio

      public double getStrahlerBifurcationRatio() throws IllegalArgumentException
      Gets the average Strahler bifurcation ratio of analyzed tree.
      Returns:
      the average bifurcation ratio
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getNBranches

      public int getNBranches() throws IllegalArgumentException
      Gets the number of branches in the analyzed tree.
      Returns:
      the number of branches
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getNNodes

      public long getNNodes()
      Gets the number of nodes in the analyzed tree.
      Returns:
      the number of nodes

    • getBranches

      public List<Path> getBranches() throws IllegalArgumentException
      Gets all the branches in the analyzed tree. A branch is defined as the Path composed of all the nodes between two branching points or between one branching point and a termination point.
      Returns:
      the list of branches as Path objects.
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops
      See Also:

    • getAvgContraction

      public double getAvgContraction() throws IllegalArgumentException
      Gets average contraction for all the branches of the analyzed tree.
      Returns:
      the average branch contraction
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getAvgFragmentation

      public double getAvgFragmentation()
      Gets the average no. of nodes (fragmentation) for all the branches of the analyzed tree.
      Returns:
      the average no. of branch nodes (average branch fragmentation)
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getAvgBranchLength

      public double getAvgBranchLength() throws IllegalArgumentException
      Gets average length for all the branches of the analyzed tree.
      Returns:
      the average branch length
      Throws:
      IllegalArgumentException - if tree contains multiple roots or loops

    • getRemoteBifAngles

      public List<Double> getRemoteBifAngles() throws IllegalArgumentException
      Gets the angle between each bifurcation point and its children in the simplified graph, which comprise either branch points or terminal nodes. Note that branch points with more than 2 children are ignored.
      Returns:
      the list of remote bifurcation angles
      Throws:
      IllegalArgumentException - if the tree contains multiple roots or loops

    • getAvgRemoteBifAngle

      public double getAvgRemoteBifAngle() throws IllegalArgumentException
      Gets the average remote bifurcation angle of the analyzed tree. Note that branch points with more than 2 children are ignored during the computation.
      Returns:
      the average remote bifurcation angle
      Throws:
      IllegalArgumentException - if the tree contains multiple roots or loops

    • getPartitionAsymmetry

      public List<Double> getPartitionAsymmetry() throws IllegalArgumentException
      Gets the partition asymmetry at each bifurcation point in the analyzed tree. Note that branch points with more than 2 children are ignored.
      Returns:
      a list containing the partition asymmetry at each bifurcation point
      Throws:
      IllegalArgumentException - if the tree contains multiple roots or loops

    • getAvgPartitionAsymmetry

      public double getAvgPartitionAsymmetry() throws IllegalArgumentException
      Gets the average partition asymmetry of the analyzed tree. Note that branch points with more than 2 children are ignored during the computation.
      Returns:
      the average partition asymmetry
      Throws:
      IllegalArgumentException - if the tree contains multiple roots or loops

    • getFractalDimension

      public List<Double> getFractalDimension() throws IllegalArgumentException
      Gets the fractal dimension of each branch in the analyzed tree. Note that branches with less than 5 points are ignored.
      Returns:
      a list containing the fractal dimension of each branch
      Throws:
      IllegalArgumentException - if the tree contains multiple roots or loops
      See Also:

    • getAvgFractalDimension

      public double getAvgFractalDimension() throws IllegalArgumentException
      Gets the average fractal dimension of the analyzed tree. Note that branches with less than 5 points are ignored during the computation.
      Returns:
      the average fractal dimension
      Throws:
      IllegalArgumentException - if the tree contains multiple roots or loops

    • getNoSpinesOrVaricosities

      public int getNoSpinesOrVaricosities()
      Gets the number of spines/varicosities that have been (manually) assigned to tree being analyzed.
      Returns:
      the number of spines/varicosities

    • getSpineOrVaricosityDensity

      public double getSpineOrVaricosityDensity()
      Gets the overall density of spines/varicosities associated with this tree
      Returns:
      the spine/varicosity density (same as getNoSpinesOrVaricosities()/getCableLength())

    • updateAndDisplayTable

      public void updateAndDisplayTable()
      Updates and displays the measurements table. If Context has not been set (running headless!?), table is printed to Console.

    • getUnit

      public String getUnit(String metric)
      Returns the physical unit associated with the specified metric. E.g.: returns µm³ if metric is "volume" and coordinates of tree being measured are defined in µm.
      Parameters:
      metric - the metric to be queried (case-insensitive)
      Returns:
      physical unit

    • getSpatialUnit

      protected String getSpatialUnit()

    • getCol

      protected int getCol(String header)

    • getNPaths

      public int getNPaths()
      Gets the no. of parsed paths.
      Returns:
      the number of paths

    • getNFittedPaths

      protected int getNFittedPaths()

    • getWidth

      public double getWidth()
      Returns the width of the BoundingBox box of the tree being measured
      Returns:
      the bounding box width

    • getHeight

      public double getHeight()
      Returns the height of the BoundingBox box of the tree being measured
      Returns:
      the bounding box height

    • getDepth

      public double getDepth()
      Returns the depth of the BoundingBox box of the tree being measured
      Returns:
      the bounding box depth

    • getPrimaryPaths

      public List<Path> getPrimaryPaths()
      Retrieves all the Paths in the analyzed Tree tagged as primary.
      Returns:
      the list of primary paths.
      See Also:

    • getInnerBranches

      public List<Path> getInnerBranches()
      Retrieves the branches of highest Strahler order in the Tree. This typically correspond to the most 'internal' branches of the Tree in direct sequence from the root.
      Returns:
      the list containing the "inner" branches. Note that these branches (Path segments) will not carry any connectivity information.
      See Also:

    • getPrimaryBranches

      public List<Path> getPrimaryBranches()
      Retrieves the primary branches of the analyzed Tree. Primary branches (or root-associated) have origin in the Tree's root, extending to the closest branch/end-point. Note that a primary branch can also be terminal.
      Returns:
      the primary branches. Note that these branches (Path segments) will not carry any connectivity information.
      See Also:

    • getTerminalBranches

      public List<Path> getTerminalBranches()
      Retrieves the terminal branches of the analyzed Tree. A terminal branch corresponds to the section of a terminal Path between its last branch-point and its terminal point (tip). A terminal branch can also be primary.
      Returns:
      the terminal branches. Note that as per Path.getSection(int, int), these branches will not carry any connectivity information.
      See Also:

    • getTips

      public Set<PointInImage> getTips()
      Gets the position of all the tips in the analyzed tree.
      Returns:
      the set of terminal points

    • getTips

      public Set<PointInImage> getTips(BrainAnnotation annot)
      Gets the position of all the tips in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried (all of its children will be considered). Null not allowed.
      Returns:
      the branch points positions, or an empty set if no tips were retrieved.

    • getTips

      public Set<PointInImage> getTips(BrainAnnotation annot, boolean includeChildren)
      Gets the position of all the tips in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried. Null not allowed.
      includeChildren - whether children of annot should be included.
      Returns:
      the branch points positions, or an empty set if no tips were retrieved.

    • getNTips

      public int getNTips(BrainAnnotation annot)
      Gets the number of end points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried. All of its children will be considered
      Returns:
      the number of end points

    • getNTips

      public int getNTips(BrainAnnotation annot, boolean includeChildren)
      Gets the number of end points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried.
      includeChildren - whether children of annot should be included.
      Returns:
      the number of end points

    • getNTipsNorm

      public double getNTipsNorm(BrainAnnotation annot)
      Gets the number of end points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried. All of its children will be considered
      Returns:
      the number of end points

    • getTips

      public Set<PointInImage> getTips(double minDistance)
      Gets the position of all tips in the analyzed tree that are further distant than the specified distance from the root.
      Parameters:
      minDistance - the minimum distance from root (inclusive, in the same units as tree coordinates)
      Returns:
      the set of terminal points distant from root by at least minDistance, or an empty set if no tips are found or if the tree has no root

    • getTips

      public Set<PointInImage> getTips(double minDistance, double maxDistance)
      Gets the position of all tips in the analyzed tree that are within the specified distance range from the root. This method is useful for analyzing tree morphology within specific distance bands from the soma.
      Parameters:
      minDistance - the minimum distance from root (inclusive, in the same units as tree coordinates)
      maxDistance - the maximum distance from root (inclusive, in the same units as tree coordinates)
      Returns:
      the set of terminal points within the specified distance range from root, or an empty set if no tips are found within the range or if the tree has no root

    • getNTipsNorm

      public double getNTipsNorm(BrainAnnotation annot, boolean includeChildren)
      Gets the percentage of end points in the analyzed tree associated with the specified annotation
      Parameters:
      annot - the BrainAnnotation to be queried.
      includeChildren - whether children of annot should be included
      Returns:
      the ratio between the no. of branch points associated with annot and the total number of end points in the tree.

    • getBranchPoints

      public Set<PointInImage> getBranchPoints()
      Gets the position of all the branch points in the analyzed tree.
      Returns:
      the branch points positions

    • getBranchPoints

      public Set<PointInImage> getBranchPoints(BrainAnnotation annot)
      Gets the position of all the branch points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried. All of its children are considered.
      Returns:
      the branch points positions, or an empty set if no branch points were retrieved

    • getBranchPoints

      public Set<PointInImage> getBranchPoints(BrainAnnotation annot, boolean includeChildren)
      Gets the position of all the branch points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried.
      includeChildren - whether children of annot should be included
      Returns:
      the branch points positions, or an empty set if no branch points were retrieved

    • getNBranchPoints

      public int getNBranchPoints(BrainAnnotation annot)
      Gets the number of branch points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried. All of its children are considered.
      Returns:
      the number of branch points

    • getNBranchPoints

      public int getNBranchPoints(BrainAnnotation annot, boolean includeChildren)
      Gets the number of branch points in the analyzed tree associated with the specified annotation.
      Parameters:
      annot - the BrainAnnotation to be queried.
      includeChildren - whether children of annot should be included
      Returns:
      the number of branch points

    • getNBranchPointsNorm

      public double getNBranchPointsNorm(BrainAnnotation annot)
      Gets the percentage of branch points in the analyzed tree associated with the specified annotation
      Parameters:
      annot - the BrainAnnotation to be queried. All of its children are considered.
      Returns:
      the ratio between the no. of branch points associated with annot and the total number of branch points in the tree.

    • getNBranchPointsNorm

      public double getNBranchPointsNorm(BrainAnnotation annot, boolean includeChildren)
      Gets the percentage of branch points in the analyzed tree associated with the specified annotation
      Parameters:
      annot - the BrainAnnotation to be queried.
      includeChildren - whether children of annot should be included
      Returns:
      the ratio between the no. of branch points associated with annot and the total number of branch points in the tree.

    • getCableLength

      public double getCableLength()
      Gets the cable length.
      Returns:
      the cable length of the tree

    • getCableLength

      public double getCableLength(BrainAnnotation compartment)
      Gets the cable length associated with the specified compartment (neuropil label).
      Parameters:
      compartment - the query compartment (null not allowed). All of its children will be considered
      Returns:
      the filtered cable length

    • getCableLengthNorm

      public double getCableLengthNorm(BrainAnnotation compartment)
      Gets the cable length associated with the specified compartment (neuropil label) as a ratio of total length.
      Parameters:
      compartment - the query compartment (null not allowed). All of its children will be considered
      Returns:
      the filtered cable length normalized to total cable length

    • getCableLengthNorm

      public double getCableLengthNorm(BrainAnnotation compartment, boolean includeChildren)
      Gets the cable length associated with the specified compartment (neuropil label) as a ratio of total length.
      Parameters:
      compartment - the query compartment (null not allowed)
      includeChildren - whether children of compartment should be included
      Returns:
      the filtered cable length normalized to total cable length

    • getCableLength

      public double getCableLength(BrainAnnotation compartment, boolean includeChildren)
      Gets the cable length associated with the specified compartment (neuropil label).
      Parameters:
      compartment - the query compartment (null not allowed)
      includeChildren - whether children of compartment should be included
      Returns:
      the filtered cable length

    • contains

      protected boolean contains(BrainAnnotation annot, BrainAnnotation annotToBeTested, boolean includeChildren)

    • dispose

      public void dispose()
      Clears internal caches and mappings to free memory.

    • main

      public static void main(String[] args)