# `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 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. 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 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. 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.