:mod:`neuron_morphology.features.layer.layer_histogram` ======================================================= .. py:module:: neuron_morphology.features.layer.layer_histogram Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: neuron_morphology.features.layer.layer_histogram.LayerHistogram neuron_morphology.features.layer.layer_histogram.EarthMoversDistanceInterpretation neuron_morphology.features.layer.layer_histogram.EarthMoversDistanceResult Functions ~~~~~~~~~ .. autoapisummary:: neuron_morphology.features.layer.layer_histogram.ensure_tuple neuron_morphology.features.layer.layer_histogram.ensure_node_types neuron_morphology.features.layer.layer_histogram.ensure_layers neuron_morphology.features.layer.layer_histogram.earth_movers_distance neuron_morphology.features.layer.layer_histogram.histogram_earth_movers_distance neuron_morphology.features.layer.layer_histogram.normalized_depth_histogram neuron_morphology.features.layer.layer_histogram.normalized_depth_histograms_across_layers neuron_morphology.features.layer.layer_histogram.normalized_depth_histogram_within_layer .. function:: 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 .. .. !! processed by numpydoc !! .. function:: ensure_node_types(node_types) Make sure the argued node types are a tuple .. !! processed by numpydoc !! .. function:: ensure_layers(layers) Make sure the argued layer array is a tuple .. !! processed by numpydoc !! .. py:class:: LayerHistogram Bases: :class:`typing.NamedTuple` The results of calculating a within-layer depth histogram of points within some cortical layer. .. !! processed by numpydoc !! .. attribute:: counts :annotation: :np.ndarray .. attribute:: bin_edges :annotation: :np.ndarray .. py:class:: EarthMoversDistanceInterpretation Bases: :class:`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. .. !! processed by numpydoc !! .. attribute:: BothPresent :annotation: = 0 .. attribute:: OneEmpty :annotation: = 1 .. attribute:: BothEmpty :annotation: = 2 .. py:class:: EarthMoversDistanceResult Bases: :class:`typing.NamedTuple` The result of comparing two histograms using earth mover's distance .. !! processed by numpydoc !! .. attribute:: result :annotation: :float .. attribute:: interpretation :annotation: :EarthMoversDistanceInterpretation .. method:: to_dict_human_readable(self) .. function:: 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. .. .. !! processed by numpydoc !! .. function:: 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. .. .. !! processed by numpydoc !! .. function:: 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. .. !! processed by numpydoc !! .. function:: 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. .. !! processed by numpydoc !! .. function:: 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. .. rubric:: 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. .. !! processed by numpydoc !!