navis.in_volume¶

navis.in_volume(x, volume, mode='IN', backend=('ncollpyde', 'pyoctree'), n_rays=None, prevent_fragments=False, validate=False, inplace=False)[source]¶

Test if points/neurons are within a given volume.

Notes

This function requires ncollpyde (recommended and installed with navis) or pyoctree as backends for raycasting. If neither is installed, we can fall back to using scipy’s ConvexHull instead. This is, however, slower and will give wrong positives for concave meshes!

Parameters:

x ((N, 3) array-like | pandas.DataFrame | Neuron/List) –
- neuron(s)
- array-like is treated as list of x/y/z oordinates. Has to be of shape (N, 3), i.e. [[x1, y1, z1], [x2, y2, z2], ..]
- pandas.DataFrame needs to have x, y, z columns
volume (Volume | mesh-like | dict or list thereof) – Multiple volumes can be given as list ([volume1, volume2, ...]) or dict ({'label1': volume1, ...}).
mode ('IN' | 'OUT', optional) – If ‘IN’, parts of the neuron that are within the volume are kept.
backend ('ncollpyde' | 'pyoctree' | 'scipy' | iterable thereof) – Which backend so be used (see Notes). If multiple backends are given, will use the first backend that is available.
n_rays (int | None, optional) – Number of rays used to determine if a point is inside a volume. More rays give more reliable results but are slower (especially with pyoctree backend). If None will use default number of rays (3 for ncollpyde, 1 for pyoctree).
prevent_fragments (bool, optional) – Only relevant if input is TreeNeuron(s). If True, will attempt to keep neuron from fragmenting.
validate (bool, optional) – If True, validate volume and try to fix issues using trimesh. Will raise ValueError if issue could not be fixed.
inplace (bool, optional) – Only relevant if input is Neuron/List. Ignored if multiple volumes are provided.

Return type:

Union[Union[NeuronList, TreeNeuron, BaseNeuron, MeshNeuron], Sequence[bool], Dict[str, Union[Sequence[bool], Union[NeuronList, TreeNeuron, BaseNeuron, MeshNeuron]]], None]

Returns:

Neuron – If input is a single neuron or NeuronList, will return subset of the neuron(s) (nodes and connectors) that are within given volume.
list of bools – If input is (N, 3) array of coordinates, returns a (N, ) boolean array: True if in volume, False if not in order.
dict – If multiple volumes are provided, results will be returned in dictionary with volumes as keys:
```
{'volume1': in_volume(x, volume1),
 'volume2': in_volume(x, volume2),
 ... }
```

Examples

Prune neuron to volume

>>> import navis
>>> n = navis.example_neurons(1)
>>> lh = navis.example_volume('LH')
>>> n_lh = navis.in_volume(n, lh, inplace=False)
>>> n_lh                                                    
type            navis.TreeNeuron
name                  1734350788
id                    1734350788
n_nodes                      344
n_connectors                None
n_branches                    49
n_leafs                       50
cable_length             32313.5
soma                        None
units                8 nanometer
dtype: object