morph_stats: morphometric statistics extraction

The neurom stats application extracts morphometrics from a set of neuron morphology files and produces a summary in JSON or CSV format. It may obtain any of the morphometrics available in the neurom.get() function, and is highly configurable, allowing the user to get raw or summary statistics from a large set of neurite and neuron features.

An example usage:

neurom stats path/to/morph/file_or_dir --config path/to/config --output path/to/output/file

The functionality can be best explained by looking at a sample configuration file that is supposed to go under --config option:

neurite:
    section_lengths:
        - max
        - total
    section_volumes:
        - total
    section_branch_orders:
        - max

neurite_type:
    - AXON
    - APICAL_DENDRITE
    - BASAL_DENDRITE
    - ALL

neuron:
    soma_radii:
        - mean

Here, there are two feature categories,

  1. neurite: these are morphometrics obtained from neurites, e.g. branch orders, section lengths, bifurcation angles, path lengths.

  2. neuron: these are morphometrics that can be applied to a whole neuron, e.g. the soma radius, the trunk radii, etc.

Each category sub-item (section_lengths, soma_radii, etc) corresponds to a neurom.get() feature, and each one of its sub-items corresponds to a statistic, e.g.

  • raw: array of raw values

  • max, min, mean, median, std: self-explanatory.

  • total: sum of the raw values

An additional field neurite_type specifies the neurite types into which the morphometrics are to be split. This is a sample output using the above configuration:

{
  "some/path/morph.swc":{
    "mean_soma_radius":0.17071067811865476,
    "axon":{
      "total_section_length":207.87975220908129,
      "max_section_length":11.018460736176685,
      "max_section_branch_order":10,
      "total_section_volume":276.73857657289523
    },
    "all":{
      "total_section_length":840.68521442251949,
      "max_section_length":11.758281556059444,
      "max_section_branch_order":10,
      "total_section_volume":1104.9077419665782
    },
    "apical_dendrite":{
      "total_section_length":214.37304577550353,
      "max_section_length":11.758281556059444,
      "max_section_branch_order":10,
      "total_section_volume":271.9412385728449
    },
    "basal_dendrite":{
      "total_section_length":418.43241643793476,
      "max_section_length":11.652508126101711,
      "max_section_branch_order":10,
      "total_section_volume":556.22792682083821
    }
  }
}

For more information on the application and available options, invoke it with the --help or -h option.

neurom stats --help
neurom --help  # to see all logging options

Features

To see all available features for --config:

$ neurom features

Neurite features (neurite, neuron, neuron population):
    - diameter_power_relations:
        Calculate the diameter power relation at a bifurcation point.
        
            Diameter power relation is defined in https://www.ncbi.nlm.nih.gov/pubmed/18568015
        
            This quantity gives an indication of how far the branching is from
            the Rall ratio (when =1).
    - local_bifurcation_angles:
        Get a list of local bifurcation angles in a collection of neurites.
    - max_radial_distance:
        Get the maximum radial distances of the termination sections for a collection of neurites.
    - max_radial_distances:
        Get the maximum radial distances of the termination sections for a collection of neurites.
    - n_bifurcation_points:
        Number of bifurcation points in a collection of neurites.
    - n_forking_points:
        Number of forking points in a collection of neurites.
    - n_leaves:
        Number of leaves points in a collection of neurites.
    - n_neurites:
        Number of neurites in a collection of neurites.
    - n_sections:
        Number of sections in a collection of neurites.
    - n_segments:
        Number of segments in a collection of neurites.
    - neurite_lengths:
        Get the path length per neurite in a collection.
    - neurite_volume_density:
        Get the volume density per neurite.
        
            The volume density is defined as the ratio of the neurite volume and
            the volume of the neurite's enclosing convex hull
        
            TODO: the convex hull fails on some morphologies, it may be good to instead use
                bounding_box to compute the neurite enclosing volume
        
            .. note:: Returns `np.nan` if the convex hull computation fails.
    - neurite_volumes:
        Get the volume per neurite in a collection.
    - number_of_bifurcations:
        Number of bifurcation points in a collection of neurites.
    - number_of_forking_points:
        Number of forking points in a collection of neurites.
    - number_of_neurites:
        Number of neurites in a collection of neurites.
    - number_of_sections:
        Number of sections in a collection of neurites.
    - number_of_sections_per_neurite:
        Get the number of sections per neurite in a collection of neurites.
    - number_of_segments:
        Number of sections in a collection of neurites.
    - number_of_terminations:
        Number of leaves points in a collection of neurites.
    - partition:
        Partition at bifurcation points of a collection of neurites.
    - partition_asymmetry:
        Partition asymmetry at bifurcation points of a collection of neurites.
        
            Variant: length is a different definition, as the absolute difference in
            downstream path lenghts, relative to the total neurite path length
    - partition_asymmetry_length:
        Partition asymmetry at bifurcation points of a collection of neurites.
        
            Variant: length is a different definition, as the absolute difference in
            downstream path lenghts, relative to the total neurite path length
    - partition_pairs:
        Partition pairs at bifurcation points of a collection of neurites.
        
            Partition pair is defined as the number of bifurcations at the two
            daughters of the bifurcating section
    - principal_direction_extents:
        Principal direction extent of neurites in neurons.
    - remote_bifurcation_angles:
        Get a list of remote bifurcation angles in a collection of neurites.
    - section_areas:
        Section areas in a collection of neurites.
    - section_bif_branch_orders:
        Bifurcation section branch orders in a collection of neurites.
    - section_bif_lengths:
        Bifurcation section lengths in a collection of neurites.
    - section_bif_radial_distances:
        Get the radial distances of the bifurcation sections for a collection of neurites.
    - section_branch_orders:
        Section branch orders in a collection of neurites.
    - section_end_distances:
        Section end to end distances in a collection of neurites.
    - section_lengths:
        Section lengths in a collection of neurites.
    - section_path_distances:
        Path lengths of a collection of neurites.
    - section_radial_distances:
        Section radial distances in a collection of neurites.
        
            The iterator_type can be used to select only terminal sections (ileaf)
            or only bifurcations (ibifurcation_point).
    - section_strahler_orders:
        Inter-segment opening angles in a section.
    - section_taper_rates:
        Diameter taper rates of the sections in a collection of neurites from root to tip.
        
            Taper rate is defined here as the linear fit along a section.
            It is expected to be negative for neurons.
    - section_term_branch_orders:
        Termination section branch orders in a collection of neurites.
    - section_term_lengths:
        Termination section lengths in a collection of neurites.
    - section_term_radial_distances:
        Get the radial distances of the termination sections for a collection of neurites.
    - section_tortuosity:
        Section tortuosities in a collection of neurites.
    - section_volumes:
        Section volumes in a collection of neurites.
    - segment_areas:
        Areas of the segments in a collection of neurites.
    - segment_lengths:
        Lengths of the segments in a collection of neurites.
    - segment_meander_angles:
        Inter-segment opening angles in a section.
    - segment_midpoints:
        Return a list of segment mid-points in a collection of neurites.
    - segment_path_lengths:
        Returns pathlengths between all non-root points and their root point.
    - segment_radial_distances:
        Returns the list of distances between all segment mid points and origin.
    - segment_radii:
        Arithmetic mean of the radii of the points in segments in a collection of neurites.
    - segment_taper_rates:
        Diameters taper rates of the segments in a collection of neurites.
        
            The taper rate is defined as the absolute radii differences divided by length of the section
    - segment_volumes:
        Volumes of the segments in a collection of neurites.
    - sibling_ratios:
        Sibling ratios at bifurcation points of a collection of neurites.
        
            The sibling ratio is the ratio between the diameters of the
            smallest and the largest child. It is a real number between
            0 and 1. Method argument allows one to consider mean diameters
            along the child section instead of diameter of the first point.
    - terminal_path_lengths_per_neurite:
        Get the path lengths to each terminal point per neurite in a collection.
    - total_area_per_neurite:
        Surface area in a collection of neurites.
        
            The area is defined as the sum of the area of the sections.
    - total_length:
        Get the total length of all sections in the group of neurons or neurites.
    - total_length_per_neurite:
        Get the path length per neurite in a collection.

Neuron features (neuron, neuron population):
    - sholl_frequency:
        Perform Sholl frequency calculations on a population of neurites.
        
            Args:
                nrn(morph): nrn or population
                neurite_type(NeuriteType): which neurites to operate on
                step_size(float): step size between Sholl radii
        
            Note:
                Given a neuron, the soma center is used for the concentric circles,
                which range from the soma radii, and the maximum radial distance
                in steps of `step_size`.  When a population is given, the concentric
                circles range from the smallest soma radius to the largest radial neurite
                distance.  Finally, each segment of the neuron is tested, so a neurite that
                bends back on itself, and crosses the same Sholl radius will get counted as
                having crossed multiple times.
    - soma_radii:
        Get the radii of the somata of a population of neurons.
        
            Note:
                If a single neuron is passed, a single element list with the
                radius of its soma member is returned.
    - soma_surface_area:
        Get the surface area of a neuron's soma.
        
            Note:
                The surface area is calculated by assuming the soma is spherical.
    - soma_surface_areas:
        Get the surface areas of the somata in a population of neurons.
        
            Note:
                The surface area is calculated by assuming the soma is spherical.
        
            Note:
                If a single neuron is passed, a single element list with the surface
                area of its soma member is returned.
    - soma_volume:
        Get the volume of a neuron's soma.
    - soma_volumes:
        Get the volume of the somata in a population of neurons.
        
            Note:
                If a single neuron is passed, a single element list with the volume
                of its soma member is returned.
    - trunk_angles:
        Calculates the angles between all the trunks of the neuron.
        
            The angles are defined on the x-y plane and the trees
            are sorted from the y axis and anticlock-wise.
    - trunk_origin_azimuths:
        Get a list of all the trunk origin azimuths of a neuron or population.
        
            The azimuth is defined as Angle between x-axis and the vector
            defined by (initial tree point - soma center) on the x-z plane.
        
            The range of the azimuth angle [-pi, pi] radians
    - trunk_origin_elevations:
        Get a list of all the trunk origin elevations of a neuron or population.
        
            The elevation is defined as the angle between x-axis and the
            vector defined by (initial tree point - soma center)
            on the x-y half-plane.
        
            The range of the elevation angle [-pi/2, pi/2] radians
    - trunk_origin_radii:
        Radii of the trunk sections of neurites in a neuron.
    - trunk_section_lengths:
        List of lengths of trunk sections of neurites in a neuron.
    - trunk_vectors:
        Calculates the vectors between all the trunks of the neuron and the soma center.