navis

class BaseNeuron(UnitObject):
    """Base class for all neurons."""

    name: Optional[str]
    id: Union[int, str, uuid.UUID]

    #: Unit space for this neuron. Some functions, like soma detection are
    #: sensitive to units (if provided)
    #: Default = micrometers
    units: Union[pint.Unit, pint.Quantity]

    volume: Union[int, float]

    connectors: Optional[pd.DataFrame]

    #: Attributes used for neuron summary
    SUMMARY_PROPS = ["type", "name", "units"]

    #: Attributes to be used when comparing two neurons.
    EQ_ATTRIBUTES = ["name"]

    #: Temporary attributes that need clearing when neuron data changes
    TEMP_ATTR = ["_memory_usage"]

    #: Core data table(s) used to calculate hash
    CORE_DATA = []

    def __init__(self, **kwargs):
        # Set a random ID -> may be replaced later
        self.id = uuid.uuid4()

        # Make a copy of summary and temp props so that if we register
        # additional properties we don't change this for every single neuron
        self.SUMMARY_PROPS = self.SUMMARY_PROPS.copy()
        self.TEMP_ATTR = self.TEMP_ATTR.copy()

        self._lock = 0
        for k, v in kwargs.items():
            self._register_attr(name=k, value=v)

        # Base neurons has no data
        self._current_md5 = None

    def __getattr__(self, key):
        """Get attribute."""
        if key.startswith("has_"):
            key = key[key.index("_") + 1 :]
            if hasattr(self, key):
                data = getattr(self, key)
                if isinstance(data, pd.DataFrame):
                    if not data.empty:
                        return True
                    else:
                        return False
                # This is necessary because np.any does not like strings
                elif isinstance(data, str):
                    if data == "NA" or not data:
                        return False
                    return True
                elif utils.is_iterable(data) and len(data) > 0:
                    return True
                elif data:
                    return True
            return False
        elif key.startswith("n_"):
            key = key[key.index("_") + 1 :]
            if hasattr(self, key):
                data = getattr(self, key, None)
                if isinstance(data, pd.DataFrame):
                    return data.shape[0]
                elif utils.is_iterable(data):
                    return len(data)
                elif isinstance(data, str) and data == "NA":
                    return "NA"
            return None

        raise AttributeError(f'Attribute "{key}" not found')

    def __str__(self):
        return self.__repr__()

    def __repr__(self):
        return str(self.summary())

    def __copy__(self):
        return self.copy(deepcopy=False)

    def __deepcopy__(self, memo):
        result = self.copy(deepcopy=True)
        memo[id(self)] = result
        return result

    def __eq__(self, other):
        """Implement neuron comparison."""
        if isinstance(other, BaseNeuron):
            # We will do this sequentially and stop as soon as we find a
            # discrepancy -> this saves tons of time!
            for at in self.EQ_ATTRIBUTES:
                comp = getattr(self, at, None) == getattr(other, at, None)
                if isinstance(comp, np.ndarray) and not all(comp):
                    return False
                elif comp is False:
                    return False
            # If all comparisons have passed, return True
            return True
        else:
            return NotImplemented

    def __hash__(self):
        """Generate a hashable value."""
        # We will simply use the neuron's memory address
        return id(self)

    def __add__(self, other):
        """Implement addition."""
        if isinstance(other, BaseNeuron):
            return core.NeuronList([self, other])
        return NotImplemented

    def __imul__(self, other):
        """Multiplication with assignment (*=)."""
        return self.__mul__(other, copy=False)

    def __itruediv__(self, other):
        """Division with assignment (/=)."""
        return self.__truediv__(other, copy=False)

    def __iadd__(self, other):
        """Addition with assignment (+=)."""
        return self.__add__(other, copy=False)

    def __isub__(self, other):
        """Subtraction with assignment (-=)."""
        return self.__sub__(other, copy=False)

    def _repr_html_(self):
        frame = self.summary().to_frame()
        frame.columns = [""]
        # return self._gen_svg_thumbnail() + frame._repr_html_()
        return frame._repr_html_()

    def _gen_svg_thumbnail(self):
        """Generate 2D plot for thumbnail."""
        import matplotlib.pyplot as plt

        # Store some previous states
        prev_level = logger.getEffectiveLevel()
        prev_pbar = config.pbar_hide
        prev_int = plt.isinteractive()

        plt.ioff()  # turn off interactive mode
        logger.setLevel("WARNING")
        config.pbar_hide = True
        fig = plt.figure(figsize=(2, 2))
        ax = fig.add_subplot(111)
        fig, ax = self.plot2d(connectors=False, ax=ax)
        output = StringIO()
        fig.savefig(output, format="svg")

        if prev_int:
            plt.ion()  # turn on interactive mode
        logger.setLevel(prev_level)
        config.pbar_hide = prev_pbar
        _ = plt.clf()
        return output.getvalue()

    def _clear_temp_attr(self, exclude: list = []) -> None:
        """Clear temporary attributes."""
        if self.is_locked:
            logger.debug(f"Neuron {self.id} at {hex(id(self))} locked.")
            return

        # Must set checksum before recalculating e.g. node types
        # -> otherwise we run into a recursive loop
        self._current_md5 = self.core_md5
        self._stale = False

        for a in [at for at in self.TEMP_ATTR if at not in exclude]:
            try:
                delattr(self, a)
                logger.debug(f"Neuron {self.id} {hex(id(self))}: attribute {a} cleared")
            except AttributeError:
                logger.debug(
                    f'Neuron {self.id} at {hex(id(self))}: Unable to clear temporary attribute "{a}"'
                )
            except BaseException:
                raise

    def _register_attr(self, name, value, summary=True, temporary=False):
        """Set and register attribute.

        Use this if you want an attribute to be used for the summary or cleared
        when temporary attributes are cleared.
        """
        setattr(self, name, value)

        # If this is an easy to summarize attribute, add to summary
        if summary and name not in self.SUMMARY_PROPS:
            if isinstance(value, (numbers.Number, str, bool, np.bool_, type(None))):
                self.SUMMARY_PROPS.append(name)
            else:
                logger.error(
                    f'Attribute "{name}" of type "{type(value)}" '
                    "can not be added to summary"
                )

        if temporary:
            self.TEMP_ATTR.append(name)

    def _unregister_attr(self, name):
        """Remove and unregister attribute."""
        if name in self.SUMMARY_PROPS:
            self.SUMMARY_PROPS.remove(name)

        if name in self.TEMP_ATTR:
            self.TEMP_ATTR.remove(name)

        delattr(self, name)

    @property
    def core_md5(self) -> str:
        """MD5 checksum of core data.

        Generated from `.CORE_DATA` properties.

        Returns
        -------
        md5 :   string
                MD5 checksum of core data. `None` if no core data.

        """
        hash = ""
        for prop in self.CORE_DATA:
            cols = None
            # See if we need to parse props into property and columns
            # e.g. "nodes:node_id,parent_id,x,y,z"
            if ":" in prop:
                prop, cols = prop.split(":")
                cols = cols.split(",")

            if hasattr(self, prop):
                data = getattr(self, prop)
                if isinstance(data, pd.DataFrame):
                    if cols:
                        data = data[cols]
                    data = data.values

                data = np.ascontiguousarray(data)

                if xxhash:
                    hash += xxhash.xxh128(data).hexdigest()
                else:
                    hash += hashlib.md5(data).hexdigest()

        return hash if hash else None

    @property
    def datatables(self) -> List[str]:
        """Names of all DataFrames attached to this neuron."""
        return [k for k, v in self.__dict__.items() if isinstance(v, pd.DataFrame)]

    @property
    def extents(self) -> np.ndarray:
        """Extents of neuron in x/y/z direction (includes connectors)."""
        if not hasattr(self, "bbox"):
            raise ValueError(
                "Neuron must implement `.bbox` (bounding box) "
                "property to calculate extents."
            )
        bbox = self.bbox
        return bbox[:, 1] - bbox[:, 0]

    @property
    def id(self) -> Any:
        """ID of the neuron.

        Must be hashable. If not set, will assign a random unique identifier.
        Can be indexed by using the `NeuronList.idx[]` locator.
        """
        return getattr(self, "_id", None)

    @id.setter
    def id(self, value):
        try:
            hash(value)
        except BaseException:
            raise ValueError("id must be hashable")
        self._id = value

    @property
    def label(self) -> str:
        """Label (e.g. for legends)."""
        # If explicitly set return that label
        if getattr(self, "_label", None):
            return self._label

        # If no label set, produce one from name + id (optional)
        name = getattr(self, "name", None)
        id = getattr(self, "id", None)

        # If no name, use type
        if not name:
            name = self.type

        label = name

        # Use ID only if not a UUID
        if not isinstance(id, uuid.UUID):
            # And if it can be turned into a string
            try:
                id = str(id)
            except BaseException:
                id = ""

            # Only use ID if it is not the same as name
            if id and name != id:
                label += f" ({id})"

        return label

    @label.setter
    def label(self, value: str):
        if not isinstance(value, str):
            raise TypeError(f'label must be string, got "{type(value)}"')
        self._label = value

    @property
    def name(self) -> str:
        """Neuron name."""
        return getattr(self, "_name", None)

    @name.setter
    def name(self, value: str):
        self._name = value

    @property
    def connectors(self) -> pd.DataFrame:
        """Connector table. If none, will return `None`."""
        return getattr(self, "_connectors", None)

    @connectors.setter
    def connectors(self, v):
        if isinstance(v, type(None)):
            self._connectors = None
        else:
            self._connectors = utils.validate_table(
                v, required=["x", "y", "z"], rename=True, restrict=False
            )

    @property
    def presynapses(self):
        """Table with presynapses (filtered from connectors table).

        Requires a "type" column in connector table. Will look for type labels
        that include "pre" or that equal 0 or "0".
        """
        if not isinstance(getattr(self, "connectors", None), pd.DataFrame):
            raise ValueError("No connector table found.")
        # Make an educated guess what presynapses are
        types = self.connectors["type"].unique()
        pre = [t for t in types if "pre" in str(t).lower() or t in [0, "0"]]

        if len(pre) == 0:
            logger.debug(f"Unable to find presynapses in types: {types}")
            return self.connectors.iloc[0:0]  # return empty DataFrame
        elif len(pre) > 1:
            raise ValueError(f"Found ambigous presynapse labels: {pre}")

        return self.connectors[self.connectors["type"] == pre[0]]

    @property
    def postsynapses(self):
        """Table with postsynapses (filtered from connectors table).

        Requires a "type" column in connector table. Will look for type labels
        that include "post" or that equal 1 or "1".
        """
        if not isinstance(getattr(self, "connectors", None), pd.DataFrame):
            raise ValueError("No connector table found.")
        # Make an educated guess what presynapses are
        types = self.connectors["type"].unique()
        post = [t for t in types if "post" in str(t).lower() or t in [1, "1"]]

        if len(post) == 0:
            logger.debug(f"Unable to find postsynapses in types: {types}")
            return self.connectors.iloc[0:0]  # return empty DataFrame
        elif len(post) > 1:
            raise ValueError(f"Found ambigous postsynapse labels: {post}")

        return self.connectors[self.connectors["type"] == post[0]]

    @property
    def is_stale(self) -> bool:
        """Test if temporary attributes might be outdated."""
        # If we know we are stale, just return True
        if getattr(self, "_stale", False):
            return True
        else:
            # Only check if we believe we are not stale
            self._stale = self._current_md5 != self.core_md5
        return self._stale

    @property
    def is_locked(self):
        """Test if neuron is locked."""
        return getattr(self, "_lock", 0) > 0

    @property
    def type(self) -> str:
        """Neuron type."""
        return "navis.BaseNeuron"

    @property
    def soma(self):
        """The soma of the neuron (if any)."""
        raise NotImplementedError(f"`soma` property not implemented for {type(self)}.")

    @property
    def bbox(self) -> np.ndarray:
        """Bounding box of neuron."""
        raise NotImplementedError(f"Bounding box not implemented for {type(self)}.")

    def convert_units(
        self, to: Union[pint.Unit, str], inplace: bool = False
    ) -> Optional["BaseNeuron"]:
        """Convert coordinates to different unit.

        Only works if neuron's `.units` is not dimensionless.

        Parameters
        ----------
        to :        pint.Unit | str
                    Units to convert to. If string, must be parsable by pint.
                    See examples.
        inplace :   bool, optional
                    If True will convert in place. If not will return a
                    copy.

        Examples
        --------
        >>> import navis
        >>> n = navis.example_neurons(1)
        >>> n.units
        <Quantity(8, 'nanometer')>
        >>> n.cable_length
        266476.8
        >>> n2 = n.convert_units('um')
        >>> n2.units
        <Quantity(1.0, 'micrometer')>
        >>> n2.cable_length
        2131.8

        """
        if not isinstance(self.units, (pint.Unit, pint.Quantity)):
            raise ValueError("Unable to convert: neuron has no units set.")

        n = self.copy() if not inplace else self

        # Catch pint's UnitStrippedWarning
        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            # Get factor by which we have to multiply to get to target units
            conv = n.units.to(to).magnitude
            # Multiply by conversion factor
            n *= conv

        n._clear_temp_attr(exclude=["classify_nodes"])

        return n

    def copy(self, deepcopy=False) -> "BaseNeuron":
        """Return a copy of the neuron."""
        copy_fn = copy.deepcopy if deepcopy else copy.copy
        # Attributes not to copy
        no_copy = ["_lock"]
        # Generate new empty neuron
        x = self.__class__()
        # Override with this neuron's data
        x.__dict__.update(
            {k: copy_fn(v) for k, v in self.__dict__.items() if k not in no_copy}
        )

        return x

    def summary(self, add_props=None) -> pd.Series:
        """Get a summary of this neuron."""
        # Do not remove the list -> otherwise we might change the original!
        props = list(self.SUMMARY_PROPS)

        # Make sure ID is always in second place
        if "id" in props and props.index("id") != 2:
            props.remove("id")
            props.insert(2, "id")
        # Add .id to summary if not a generic UUID
        elif not isinstance(self.id, uuid.UUID) and "id" not in props:
            props.insert(2, "id")

        if add_props:
            props, ix = np.unique(np.append(props, add_props), return_inverse=True)
            props = props[ix]

        # This is to catch an annoying "UnitStrippedWarning" with pint
        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            s = pd.Series([getattr(self, at, "NA") for at in props], index=props)

        return s

    def plot2d(self, **kwargs):
        """Plot neuron using [`navis.plot2d`][].

        Parameters
        ----------
        **kwargs
                Will be passed to [`navis.plot2d`][].
                See `help(navis.plot2d)` for a list of keywords.

        See Also
        --------
        [`navis.plot2d`][]
                    Function called to generate 2d plot.

        """
        from ..plotting import plot2d

        return plot2d(self, **kwargs)

    def plot3d(self, **kwargs):
        """Plot neuron using [`navis.plot3d`][].

        Parameters
        ----------
        **kwargs
                Keyword arguments. Will be passed to [`navis.plot3d`][].
                See `help(navis.plot3d)` for a list of keywords.

        See Also
        --------
        [`navis.plot3d`][]
                    Function called to generate 3d plot.

        Examples
        --------
        >>> import navis
        >>> nl = navis.example_neurons()
        >>> #Plot with connectors
        >>> viewer = nl.plot3d(connectors=True)

        """
        from ..plotting import plot3d

        return plot3d(core.NeuronList(self, make_copy=False), **kwargs)

    def map_units(
        self,
        units: Union[pint.Unit, str],
        on_error: Union[Literal["raise"], Literal["ignore"]] = "raise",
    ) -> Union[int, float]:
        """Convert units to match neuron space.

        Only works if neuron's `.units` is isometric and not dimensionless.

        Parameters
        ----------
        units :     number | str | pint.Quantity | pint.Units
                    The units to convert to neuron units. Simple numbers are just
                    passed through.
        on_error :  "raise" | "ignore"
                    What to do if an error occurs (e.g. because `neuron` does not
                    have units specified). If "ignore" will simply return `units`
                    unchanged.

        See Also
        --------
        [`navis.core.to_neuron_space`][]
                    The base function for this method.

        Examples
        --------
        >>> import navis
        >>> # Example neurons are in 8x8x8nm voxel space
        >>> n = navis.example_neurons(1)
        >>> n.map_units('1 nanometer')
        0.125
        >>> # Numbers are passed-through
        >>> n.map_units(1)
        1
        >>> # For neuronlists
        >>> nl = navis.example_neurons(3)
        >>> nl.map_units('1 nanometer')
        [0.125, 0.125, 0.125]

        """
        return core.core_utils.to_neuron_space(units, neuron=self, on_error=on_error)

    def memory_usage(self, deep=False, estimate=False):
        """Return estimated memory usage of this neuron.

        Works by going over attached data (numpy arrays and pandas DataFrames
        such as vertices, nodes, etc) and summing up their size in memory.

        Parameters
        ----------
        deep :      bool
                    Passed to pandas DataFrames. If True will also inspect
                    memory footprint of `object` dtypes.
        estimate :  bool
                    If True, we will only estimate the size. This is
                    considerably faster but will slightly underestimate the
                    memory usage.

        Returns
        -------
        int
                    Memory usage in bytes.

        """
        # We will use a very simply caching here
        # We don't check whether neuron is stale because that causes
        # additional overhead and we want this function to be as fast
        # as possible
        if hasattr(self, "_memory_usage"):
            mu = self._memory_usage
            if mu["deep"] == deep and mu["estimate"] == estimate:
                return mu["size"]

        size = 0
        if not estimate:
            for k, v in self.__dict__.items():
                if isinstance(v, np.ndarray):
                    size += v.nbytes
                elif isinstance(v, pd.DataFrame):
                    size += v.memory_usage(deep=deep).sum()
                elif isinstance(v, pd.Series):
                    size += v.memory_usage(deep=deep)
        else:
            for k, v in self.__dict__.items():
                if isinstance(v, np.ndarray):
                    size += v.dtype.itemsize * v.size
                elif isinstance(v, pd.DataFrame):
                    for dt in v.dtypes.values:
                        if isinstance(dt, pd.CategoricalDtype):
                            size += len(dt.categories) * dt.itemsize
                        else:
                            size += dt.itemsize * v.shape[0]
                elif isinstance(v, pd.Series):
                    if isinstance(v.dtype, pd.CategoricalDtype):
                        size += len(dt.categories) * dt.itemsize
                    else:
                        size += v.dtype.itemsize * v.shape[0]

        self._memory_usage = {"deep": deep, "estimate": estimate, "size": size}

        return size

class Dotprops(BaseNeuron):
    """Neuron represented as points + local vectors.

    Dotprops consist of points with x/y/z coordinates, a tangent vector and an
    alpha value describing the immediate neighbourhood (see also references).

    Typically constructed using [`navis.make_dotprops`][].

    References
    ----------
    Masse N.Y., Cachero S., Ostrovsky A., and Jefferis G.S.X.E. (2012). A mutual
    information approach to automate identification of neuronal clusters in
    Drosophila brain images. Frontiers in Neuroinformatics 6 (00021).
    doi: 10.3389/fninf.2012.00021

    Parameters
    ----------
    points :        numpy array
                    (N, 3) array of x/y/z coordinates.
    k :             int, optional
                    Number of nearest neighbors for tangent vector calculation.
                    This can be `None` or `0` but then vectors must be
                    provided on initialization and can subsequently not be
                    re-calculated. Typical values here are `k=20` for dense
                    (e.g. from light level data) and `k=5` for sparse
                    (e.g. from skeletons) point clouds.
    vect :          numpy array, optional
                    (N, 3) array of vectors. If not provided will
                    recalculate both `vect` and `alpha` using `k`.
    alpha :         numpy array, optional
                    (N, ) array of alpha values. If not provided will
                    recalculate both `alpha` and `vect` using `k`.
    units :         str | pint.Units | pint.Quantity
                    Units for coordinates. Defaults to `None` (dimensionless).
                    Strings must be parsable by pint: e.g. "nm", "um",
                    "micrometer" or "8 nanometers".
    **metadata
                    Any additional data to attach to neuron.

    """

    connectors: Optional[pd.DataFrame]

    points: np.ndarray
    alpha: np.ndarray
    vect:  np.ndarray
    k: Optional[int]

    soma: Optional[Union[list, np.ndarray]]

    #: Attributes used for neuron summary
    SUMMARY_PROPS = ['type', 'name', 'k', 'units', 'n_points']

    #: Attributes to be used when comparing two neurons.
    EQ_ATTRIBUTES = ['name', 'n_points', 'k']

    #: Temporary attributes that need clearing when neuron data changes
    TEMP_ATTR = ['_memory_usage']

    #: Core data table(s) used to calculate hash
    _CORE_DATA = ['points', 'vect']

    def __init__(self,
                 points: np.ndarray,
                 k: int,
                 vect: Optional[np.ndarray] = None,
                 alpha: Optional[np.ndarray] = None,
                 units: Union[pint.Unit, str] = None,
                 **metadata
                 ):
        """Initialize Dotprops Neuron."""
        super().__init__()

        self.k = k
        self.points = points
        self.alpha = alpha
        self.vect = vect

        self.soma = None

        for k, v in metadata.items():
            try:
                setattr(self, k, v)
            except AttributeError:
                raise AttributeError(f"Unable to set neuron's `{k}` attribute.")

        self.units = units

    def __truediv__(self, other, copy=True):
        """Implement division for coordinates."""
        if isinstance(other, numbers.Number) or utils.is_iterable(other):
            # If a number, consider this an offset for coordinates
            n = self.copy() if copy else self
            _ = np.divide(n.points, other, out=n.points, casting='unsafe')
            if n.has_connectors:
                n.connectors.loc[:, ['x', 'y', 'z']] /= other

            # Force recomputing of KDTree
            if hasattr(n, '_tree'):
                delattr(n, '_tree')

            # Convert units
            # Note: .to_compact() throws a RuntimeWarning and returns unchanged
            # values  when `units` is a iterable
            with warnings.catch_warnings():
                warnings.simplefilter("ignore")
                n.units = (n.units * other).to_compact()

            return n
        return NotImplemented

    def __mul__(self, other, copy=True):
        """Implement multiplication for coordinates."""
        if isinstance(other, numbers.Number) or utils.is_iterable(other):
            # If a number, consider this an offset for coordinates
            n = self.copy() if copy else self
            _ = np.multiply(n.points, other, out=n.points, casting='unsafe')
            if n.has_connectors:
                n.connectors.loc[:, ['x', 'y', 'z']] *= other

            # Force recomputing of KDTree
            if hasattr(n, '_tree'):
                delattr(n, '_tree')

            # Convert units
            # Note: .to_compact() throws a RuntimeWarning and returns unchanged
            # values  when `units` is a iterable
            with warnings.catch_warnings():
                warnings.simplefilter("ignore")
                n.units = (n.units / other).to_compact()

            return n
        return NotImplemented

    def __add__(self, other, copy=True):
        """Implement addition for coordinates."""
        if isinstance(other, numbers.Number) or utils.is_iterable(other):
            # If a number, consider this an offset for coordinates
            n = self.copy() if copy else self
            _ = np.add(n.points, other, out=n.points, casting='unsafe')
            if n.has_connectors:
                n.connectors.loc[:, ['x', 'y', 'z']] += other

            # Force recomputing of KDTree
            if hasattr(n, '_tree'):
                delattr(n, '_tree')

            return n
        # If another neuron, return a list of neurons
        elif isinstance(other, BaseNeuron):
            return core.NeuronList([self, other])
        return NotImplemented

    def __sub__(self, other, copy=True):
        """Implement subtraction for coordinates."""
        if isinstance(other, numbers.Number) or utils.is_iterable(other):
            # If a number, consider this an offset for coordinates
            n = self.copy() if copy else self
            _ = np.subtract(n.points, other, out=n.points, casting='unsafe')
            if n.has_connectors:
                n.connectors.loc[:, ['x', 'y', 'z']] -= other

            # Force recomputing of KDTree
            if hasattr(n, '_tree'):
                delattr(n, '_tree')

            return n
        return NotImplemented

    def __getstate__(self):
        """Get state (used e.g. for pickling)."""
        state = {k: v for k, v in self.__dict__.items() if not callable(v)}

        # The KDTree from pykdtree does not like being pickled
        # We will have to remove it which will force it to be regenerated
        # after unpickling
        if '_tree' in state:
            if 'pykdtree' in str(type(state['_tree'])):
                _ = state.pop('_tree')

        return state

    def __len__(self):
        return len(self.points)

    @property
    def alpha(self):
        """Alpha value for tangent vectors (optional)."""
        if isinstance(self._alpha, type(None)):
            if isinstance(self.k, type(None)) or (self.k <= 0):
                raise ValueError('Unable to calculate `alpha` for Dotprops not '
                                 'generated using k-nearest-neighbors.')

            self.recalculate_tangents(self.k, inplace=True)
        return self._alpha

    @alpha.setter
    def alpha(self, value):
        if not isinstance(value, type(None)):
            value = np.asarray(value)
            if value.ndim != 1:
                raise ValueError(f'alpha must be (N, ) array, got {value.shape}')
        self._alpha = value

    @property
    def bbox(self) -> np.ndarray:
        """Bounding box (includes connectors)."""
        mn = np.min(self.points, axis=0)
        mx = np.max(self.points, axis=0)

        if self.has_connectors:
            cn_mn = np.min(self.connectors[['x', 'y', 'z']].values, axis=0)
            cn_mx = np.max(self.connectors[['x', 'y', 'z']].values, axis=0)

            mn = np.min(np.vstack((mn, cn_mn)), axis=0)
            mx = np.max(np.vstack((mx, cn_mx)), axis=0)

        return np.vstack((mn, mx)).T

    @property
    def datatables(self) -> List[str]:
        """Names of all DataFrames attached to this neuron."""
        return [k for k, v in self.__dict__.items() if isinstance(v, pd.DataFrame, np.ndarray)]

    @property
    def kdtree(self):
        """KDTree for points."""
        if not getattr(self, '_tree', None):
            self._tree = KDTree(self.points)
        return self._tree

    @property
    def points(self):
        """Center of tangent vectors."""
        return self._points

    @points.setter
    def points(self, value):
        if isinstance(value, type(None)):
            value = np.zeros((0, 3))
        value = np.asarray(value)
        if value.ndim != 2 or value.shape[1] != 3:
            raise ValueError(f'points must be (N, 3) array, got {value.shape}')
        self._points = value
        # Also reset KDtree
        self._tree = None

    @property
    def vect(self):
        """Tangent vectors."""
        if isinstance(self._vect, type(None)):
            self.recalculate_tangents(self.k, inplace=True)
        return self._vect

    @vect.setter
    def vect(self, value):
        if not isinstance(value, type(None)):
            value = np.asarray(value)
            if value.ndim != 2 or value.shape[1] != 3:
                raise ValueError(f'vectors must be (N, 3) array, got {value.shape}')
        self._vect = value

    @property
    def sampling_resolution(self):
        """Mean distance between points."""
        dist, _ = self.kdtree.query(self.points, k=2)
        return np.mean(dist[:, 1])

    @property
    def soma(self) -> Optional[int]:
        """Index of soma point.

        `None` if no soma. You can assign either a function that accepts a
        Dotprops as input or a fix value. Default is None.
        """
        if callable(self._soma):
            soma = self._soma.__call__()  # type: ignore  # say int not callable
        else:
            soma = self._soma

        # Sanity check to make sure that the soma node actually exists
        if isinstance(soma, type(None)):
            # Return immmediately without expensive checks
            return soma
        elif utils.is_iterable(soma):
            if not any(soma):
                soma = None
            elif any(np.array(soma) < 0) or any(np.array(soma) > self.points.shape[0]):
                logger.warning(f'Soma(s) {soma} not found in points.')
                soma = None
        else:
            if 0 < soma < self.points.shape[0]:
                logger.warning(f'Soma {soma} not found in node table.')
                soma = None

        return soma

    @soma.setter
    def soma(self, value: Union[Callable, int, None]) -> None:
        """Set soma."""
        if hasattr(value, '__call__'):
            self._soma = types.MethodType(value, self)
        elif isinstance(value, type(None)):
            self._soma = None
        elif isinstance(value, bool) and not value:
            self._soma = None
        else:
            if 0 < value < self.points.shape[0]:
                self._soma = value
            else:
                raise ValueError('Soma must be function, None or a valid node index.')

    @property
    def type(self) -> str:
        """Neuron type."""
        return 'navis.Dotprops'

    def dist_dots(self,
                  other: 'Dotprops',
                  alpha: bool = False,
                  distance_upper_bound: Optional[float] = None,
                  **kwargs) -> Union[
                      Tuple[np.ndarray, np.ndarray], Tuple[np.ndarray, np.ndarray, np.ndarray]
                    ]:
        """Query this Dotprops against another.

        This function is mainly for `navis.nblast`.

        Parameters
        ----------
        other :                 Dotprops
        alpha :                 bool
                                If True, will also return the product of the
                                product of the alpha values of matched points.
        distance_upper_bound :  non-negative float, optional
                                If provided, we will stop the nearest neighbor
                                search at this distance which can vastly speed
                                up the query. For points with no hit within this
                                distance, `dist` will be set to
                                `distance_upper_bound`, and `dotprods` and
                                `alpha_prod` will be set to 0.
        kwargs
                                Keyword arguments are passed to the KDTree's
                                `query()` method. Note that we are using
                                `pykdtree.kdtree.KDTree` if available and fall
                                back to `scipy.spatial.cKDTree` if pykdtree is
                                not installed.

        Returns
        -------
        dist :          np.ndarray
                        For each point in `self`, the distance to the closest
                        point in `other`.
        dotprods :      np.ndarray
                        Dotproduct of each pair of closest points between
                        `self` and `other`.
        alpha_prod :    np.ndarray
                        Dotproduct of each pair of closest points between
                        `self` and `other`. Only returned if `alpha=True`.

        """
        if not isinstance(other, Dotprops):
            raise TypeError(f'Expected Dotprops, got "{type(other)}"')

        # If we are using pykdtree we need to make sure that self.points is
        # of the same dtype as other.points - not a problem with scipy but
        # the overhead is typically only a few micro seconds anyway
        points = self.points.astype(other.points.dtype, copy=False)

        # Scipy's KDTree does not like the distance to be None
        diub = distance_upper_bound if distance_upper_bound else np.inf
        fast_dists, fast_idxs = other.kdtree.query(points,
                                                   distance_upper_bound=diub,
                                                   **kwargs)

        # If upper distance we have to worry about infinite distances
        if distance_upper_bound:
            no_nn = fast_dists == np.inf
            fast_dists[no_nn] = distance_upper_bound

            # Temporarily give those nodes a match
            fast_idxs[no_nn] = 0

        fast_dotprods = np.abs((self.vect * other.vect[fast_idxs]).sum(axis=1))

        if distance_upper_bound:
            fast_dotprods[no_nn] = 0

        if not alpha:
            return fast_dists, fast_dotprods

        fast_alpha = self.alpha * other.alpha[fast_idxs]

        if distance_upper_bound:
            fast_alpha[no_nn] = 0

        return fast_dists, fast_dotprods, fast_alpha

    def downsample(self, factor=5, inplace=False, **kwargs):
        """Downsample the neuron by given factor.

        Parameters
        ----------
        factor :                int, optional
                                Factor by which to downsample the neurons.
                                Default = 5.
        inplace :               bool, optional
                                If True, operation will be performed on
                                itself. If False, operation is performed on
                                copy which is then returned.
        **kwargs
                                Additional arguments passed to
                                [`navis.downsample_neuron`][].

        See Also
        --------
        [`navis.downsample_neuron`][]
            Base function. See for details and examples.

        """
        if inplace:
            x = self
        else:
            x = self.copy()

        sampling.downsample_neuron(x, factor, inplace=True, **kwargs)

        if not inplace:
            return x
        return None

    def copy(self) -> 'Dotprops':
        """Return a copy of the dotprops.

        Returns
        -------
        Dotprops

        """
        # Don't copy the KDtree - when using pykdtree, copy.copy throws an
        # error and the construction is super fast anyway
        no_copy = ['_lock', '_tree']
        # Generate new empty neuron - note we pass vect and alpha to
        # prevent calculation on initialization
        x = self.__class__(points=np.zeros((0, 3)), k=1,
                           vect=np.zeros((0, 3)), alpha=np.zeros(0))
        # Populate with this neuron's data
        x.__dict__.update({k: copy.copy(v) for k, v in self.__dict__.items() if k not in no_copy})

        return x

    def drop_fluff(self, epsilon, keep_size: int = None, n_largest: int = None, inplace=False):
        """Remove fluff from neuron.

        By default, this function will remove all but the largest connected
        component from the neuron. You can change that behavior using the
        `keep_size` and `n_largest` parameters.

        Parameters
        ----------
        epsilon :   float
                    Distance at which to consider two points to be connected.
                    If `None`, will use the default value of 5 times the average
                    node distance (`self.sampling_resolution`).
        keep_size : float, optional
                    Use this to set a size (in number of points) for small
                    bits to keep. If `keep_size` < 1 it will be intepreted as
                    fraction of total nodes/vertices/points.
        n_largest : int, optional
                    If set, will keep the `n_largest` connected components. Note:
                    if provided, `keep_size` will be applied first!
        inplace :   bool, optional
                    If False, will return a copy and leave the original data
                    unmodified.

        Returns
        -------
        Dotprops
                    Only if `inplace=False`.

        See Also
        --------
        [`navis.drop_fluff`][]
            Base function. See for details and examples.

        """
        x = morpho.drop_fluff(self, epsilon=epsilon, keep_size=keep_size, n_largest=n_largest, inplace=inplace)

        if not inplace:
            return x

    def recalculate_tangents(self, k: int, inplace=False):
        """Recalculate tangent vectors and alpha with a new `k`.

        Parameters
        ----------
        k :         int
                    Number of nearest neighbours to use for tangent vector
                    calculation.
        inplace :   bool
                    If False, will return a copy and leave the original data
                    unmodified.

        Returns
        -------
        Dotprops
                    Only if `inplace=False`.

        """
        if not inplace:
            x = self.copy()
        else:
            x = self

        if isinstance(k, type(None)) or k < 1:
            raise ValueError(f'`k` must be integer >= 1, got "{k}"')

        # Checks and balances
        n_points = x.points.shape[0]
        if n_points < k:
            raise ValueError(f"Too few points ({n_points}) to calculate {k} "
                             "nearest-neighbors")

        # Create the KDTree and get the k-nearest neighbors for each point
        dist, ix = self.kdtree.query(x.points, k=k)

        # Get points: array of (N, k, 3)
        pt = x.points[ix]

        # Generate centers for each cloud of k nearest neighbors
        centers = np.mean(pt, axis=1)

        # Generate vector from center
        cpt = pt - centers.reshape((pt.shape[0], 1, 3))

        # Get inertia (N, 3, 3)
        inertia = cpt.transpose((0, 2, 1)) @ cpt

        # Extract vector and alpha
        u, s, vh = np.linalg.svd(inertia)
        x.vect = vh[:, 0, :]
        x.alpha = (s[:, 0] - s[:, 1]) / np.sum(s, axis=1)

        # Keep track of k
        x.k = k

        if not inplace:
            return x

    def snap(self, locs, to='points'):
        """Snap xyz location(s) to closest point or synapse.

        Parameters
        ----------
        locs :      (N, 3) array | (3, ) array
                    Either single or multiple XYZ locations.
        to :        "points" | "connectors"
                    Whether to snap to points or connectors.

        Returns
        -------
        ix :        int | list of int
                    Index/Indices of the closest point/connector.
        dist :      float | list of float
                    Distance(s) to the closest point/connector.

        Examples
        --------
        >>> import navis
        >>> n = navis.example_neurons(1)
        >>> dp = navis.make_dotprops(n, k=5)
        >>> ix, dist = dp.snap([0, 0, 0])
        >>> ix
        1123

        """
        locs = np.asarray(locs).astype(np.float64)

        is_single = (locs.ndim == 1 and len(locs) == 3)
        is_multi = (locs.ndim == 2 and locs.shape[1] == 3)
        if not is_single and not is_multi:
            raise ValueError('Expected a single (x, y, z) location or a '
                             '(N, 3) array of multiple locations')

        if to not in ['points', 'connectors']:
            raise ValueError('`to` must be "points" or "connectors", '
                             f'got {to}')

        # Generate tree
        tree = graph.neuron2KDTree(self, data=to)

        # Find the closest node
        dist, ix = tree.query(locs)

        return ix, dist

    def to_skeleton(self,
                    scale_vec: Union[float, Literal['auto']] = 'auto'
                    ) -> core.TreeNeuron:
        """Turn Dotprop into a TreeNeuron.

        This does *not* skeletonize the neuron but rather generates a line
        segment for each point based on the tangent vector. This is mainly
        used under the hood for plotting. Also note that only minimal meta
        data is carried over.

        For proper skeletonization see [`navis.skeletonize`][].

        Parameters
        ----------
        scale_vec :     "auto" | float
                        Factor by which to scale each tangent vector when
                        generating the line segments. If "auto" (default for
                        plotting) will use the sampling resolution (median
                        distance between points) to determine a suitable
                        values.

        Returns
        -------
        TreeNeuron

        """
        if not isinstance(scale_vec, numbers.Number) and scale_vec != 'auto':
            raise ValueError('`scale_vect` must be "auto" or a number, '
                             f'got {scale_vec}')

        if scale_vec == 'auto':
            scale_vec = self.sampling_resolution * .8

        # Prepare segments - this is based on nat:::plot3d.dotprops
        halfvect = self.vect / 2 * scale_vec
        starts = self.points - halfvect
        ends = self.points + halfvect

        # Interweave starts and ends
        segs = np.zeros((starts.shape[0] * 2, 3))
        segs[::2] = starts
        segs[1::2] = ends

        # Generate node table
        nodes = pd.DataFrame(segs, columns=['x', 'y', 'z'])
        nodes['node_id'] = nodes.index
        nodes['parent_id'] = -1
        nodes.loc[1::2, 'parent_id'] = nodes.index.values[::2]

        # Produce a minimal TreeNeuron
        tn = core.TreeNeuron(nodes, units=self.units, id=self.id)

        # Carry over the label
        if getattr(self, '_label', None):
            tn._label = self._label

        # Add some other relevant attributes directly
        if self.has_connectors:
            tn._connectors = self._connectors
        tn._soma = self._soma

        return tn