Skip to content

morpho

Calculate cable length.

PARAMETER DESCRIPTION
x
        Neuron(s) for which to calculate cable length.

TYPE: TreeNeuron | MeshNeuron | NeuronList

mask
        If provided, will only consider nodes where
        `mask` is True. Callable must accept a DataFrame of nodes
        and return a boolean array of the same length.

TYPE: None | boolean array | callable DEFAULT: None

RETURNS DESCRIPTION
cable_length

Cable length of the neuron(s).

TYPE: float | array of float

Source code in navis/morpho/mmetrics.py
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
@utils.map_neuronlist(desc="Cable length", allow_parallel=True)
@utils.meshneuron_skeleton(method="pass_through")
def cable_length(x, mask=None) -> Union[int, float]:
    """Calculate cable length.

    Parameters
    ----------
    x :             TreeNeuron | MeshNeuron | NeuronList
                    Neuron(s) for which to calculate cable length.
    mask :          None | boolean array | callable
                    If provided, will only consider nodes where
                    `mask` is True. Callable must accept a DataFrame of nodes
                    and return a boolean array of the same length.

    Returns
    -------
    cable_length :  float | array of float
                    Cable length of the neuron(s).

    """
    utils.eval_param(x, name="x", allowed_types=(core.TreeNeuron,))

    nodes = x.nodes
    if mask is not None:
        if callable(mask):
            mask = mask(x.nodes)

        if isinstance(mask, np.ndarray):
            if len(mask) != len(x.nodes):
                raise ValueError(
                    f"Length of mask ({len(mask)}) must match number of nodes "
                    f"({len(x.nodes)})."
                )
        else:
            raise ValueError(
                f"Mask must be callable or boolean array, got {type(mask)}"
            )

        nodes = x.nodes.loc[mask, ['node_id','parent_id', 'x', 'y', 'z']].copy()

        # Set the parent IDs to -1 for nodes that are not in the mask
        nodes.loc[~nodes.parent_id.isin(nodes.node_id), "parent_id"] = -1

    if not len(nodes):
        return 0

    # See if we can use fastcore
    if not utils.fastcore:
        # The by far fastest way to get the cable length is to work on the node table
        # Using the igraph representation is about the same speed... if it is already calculated!
        # However, one problem with the graph representation is that with large neuronlists
        # it adds a lot to the memory footprint.
        not_root = (nodes.parent_id >= 0).values
        xyz = nodes[["x", "y", "z"]].values[not_root]
        xyz_parent = (
            x.nodes.set_index("node_id")
            .loc[nodes.parent_id.values[not_root], ["x", "y", "z"]]
            .values
        )
        cable_length = np.sum(np.linalg.norm(xyz - xyz_parent, axis=1))
    else:
        cable_length = utils.fastcore.dag.parent_dist(
            nodes.node_id.values,
            nodes.parent_id.values,
            nodes[["x", "y", "z"]].values,
            root_dist=0,
        ).sum()

    return cable_length