neuron_morphology.features.layer.layer_histogram

Module Contents

Classes

LayerHistogram	The results of calculating a within-layer depth histogram of points
EarthMoversDistanceInterpretation	Describes how to understand an earth mover’s distance result. This is
EarthMoversDistanceResult	The result of comparing two histograms using earth mover’s distance

Functions

ensure_tuple(inputs: Any, item_type: Type, if_none: Union[str, Tuple] = ‘raise’) → Tuple	Try to smartly coerce inputs to a tuple.
ensure_node_types(node_types)	Make sure the argued node types are a tuple
ensure_layers(layers)	Make sure the argued layer array is a tuple
earth_movers_distance(data: Data, node_types: Sequence[int], node_types_to_compare: Sequence[int], bin_size: float = 5) → Dict[str, EarthMoversDistanceResult]	Calculate the earth mover’s distance between normalized histograms of
histogram_earth_movers_distance(from_hist: np.ndarray, to_hist: np.ndarray) → EarthMoversDistanceResult	Calculate the earth mover’s distance between to histograms, normalizing
normalized_depth_histogram(data: Data, node_types: Optional[Sequence[int]] = None, bin_size=5.0) → Dict[str, LayerHistogram]	Calculates for each cortical layer a histogram of node depths within
normalized_depth_histograms_across_layers(data: Data, point_types: Optional[Tuple[int]] = None, only_layers: Optional[Tuple[str]] = None, bin_size=5.0) → Dict[str, LayerHistogram]	A helper function for running cortical depth histograms across multiple
normalized_depth_histogram_within_layer(point_depths: np.ndarray, local_layer_pia_side_depths: np.ndarray, local_layer_wm_side_depths: np.ndarray, reference_layer_depths: ReferenceLayerDepths, bin_size: float) → np.ndarray	Calculates a histogram of node depths within a single (cortical) layer.

neuron_morphology.features.layer.layer_histogram.ensure_tuple(inputs: Any, item_type: Type, if_none: Union[str, Tuple] = 'raise') → Tuple

Try to smartly coerce inputs to a tuple.

Parameters:

inputs : the data to be coerced

item_type : which type do/should the elements of the tuple have?

if_none : if the inputs are none, return this value. If the value is

“raise”, instead raise an exception

Returns:

the coerced inputs

neuron_morphology.features.layer.layer_histogram.ensure_node_types(node_types)

Make sure the argued node types are a tuple

neuron_morphology.features.layer.layer_histogram.ensure_layers(layers)

Make sure the argued layer array is a tuple

class neuron_morphology.features.layer.layer_histogram.LayerHistogram

Bases: typing.NamedTuple

The results of calculating a within-layer depth histogram of points within some cortical layer.

counts :np.ndarray

bin_edges :np.ndarray

class neuron_morphology.features.layer.layer_histogram.EarthMoversDistanceInterpretation

Bases: enum.Enum

Describes how to understand an earth mover’s distance result. This is useful in the case that one or both histograms are all 0.

BothPresent = 0

OneEmpty = 1

BothEmpty = 2

class neuron_morphology.features.layer.layer_histogram.EarthMoversDistanceResult

Bases: typing.NamedTuple

The result of comparing two histograms using earth mover’s distance

result :float

interpretation :EarthMoversDistanceInterpretation

to_dict_human_readable(self)

neuron_morphology.features.layer.layer_histogram.earth_movers_distance(data: Data, node_types: Sequence[int], node_types_to_compare: Sequence[int], bin_size: float = 5) → Dict[str, EarthMoversDistanceResult]

Calculate the earth mover’s distance between normalized histograms of node depths within cortical layers. Calculates one distance for each layer.

Parameters:

data : Must be endowed with layered_point_depths and reference_layer_depths.

The morphology is not actually used directly.

node_types : Defines one set of points whose histograms to compare.

node_types_to_compare : Defines the other set of points

bin_size : the size of each depth bin. Default is appropriate if the units

are microns.

Returns:

A mapping from layers to distances between histograms within those layers.

neuron_morphology.features.layer.layer_histogram.histogram_earth_movers_distance(from_hist: np.ndarray, to_hist: np.ndarray) → EarthMoversDistanceResult

Calculate the earth mover’s distance between to histograms, normalizing each. If one histogram is empty, return the sum of the other and a flag. If both are empty, return 0 a and a flag.

Parameters:

from_hist : distance is calculated between (the normalized form of) this

histogram and to_hist. The result is symmetric.

to_hist : distance is calculated between (the normalized form of) this

histogram and from_hist

Returns:

The distance between input histograms, along with an enum indicating

whether one or both of the histograms was all 0.

neuron_morphology.features.layer.layer_histogram.normalized_depth_histogram(data: Data, node_types: Optional[Sequence[int]] = None, bin_size=5.0) → Dict[str, LayerHistogram]

Calculates for each cortical layer a histogram of node depths within that layer.

Parameters:

data : Must have the following attributes:

reference_layer_depths : A dictionary mapping layer names (str) to

ReferenceLayerDepths objects describing the average pia and white- matter side depths of this each layer.

layered_point_depths : A LayeredPointDepths defining for each point a

depth from pia. See LayeredPointDepths for more information.

node_types : for which to calculate the histograms

bin_size : the size of each depth bin. Default is appropriate if the units

are microns.

neuron_morphology.features.layer.layer_histogram.normalized_depth_histograms_across_layers(data: Data, point_types: Optional[Tuple[int]] = None, only_layers: Optional[Tuple[str]] = None, bin_size=5.0) → Dict[str, LayerHistogram]

A helper function for running cortical depth histograms across multiple layers.

Parameters:

data : must have reference_layer_depths and layered_point_depths

point_types : calculate histograms for points labeled with these types

only_layers : exclude other layers from this calculation

bin_size : the size of each depth bin. Default is appropriate if the units

are microns.

neuron_morphology.features.layer.layer_histogram.normalized_depth_histogram_within_layer(point_depths: np.ndarray, local_layer_pia_side_depths: np.ndarray, local_layer_wm_side_depths: np.ndarray, reference_layer_depths: ReferenceLayerDepths, bin_size: float) → np.ndarray

Calculates a histogram of node depths within a single (cortical) layer. Uses reference information about layer boundaries to normalize these depths for cross-reconstruction comparison.

Parameters:

depths : Each item corresponds to a point of interest (such as a node

in a morphological reconstruction). Values are the depths of these points of interest from the pia surface.

local_layer_pia_side_depths : Each item corresponds to a point of interest.

Values are the depth of the intersection point between a path of steepest descent from the pia surface to the point of interest and the upper surface of the layer.

local_layer_wm_side_depths : Each item corresponds to a point of interest.

Values are the depth of the intersection point between the layer’s lower boundary and the path described above.

reference_layer_depths : Used to provide normalized depths suitable

for comparison across reconstructions. Should provide a generic equivalent of local layer depths for a population or reference space.

bin_size : The width of each bin, in terms of depths from pia in the

reference space. Provide only one of bin_edges or bin_size.

Returns:

A numpy array listing for each depth bin the number of nodes falling within

that bin.

Notes

This function relies on the notion of a steepest descent path through cortex, but is agnostic to the method used to obtain such a path and to features of the path (e.g. whether it is allowed to curve). Rather the caller must ensure that all depths have been calculated according to a consistent scheme.