nhood_dists

cellseg_gsontools.neighbors.nhood_dists(nhood, centroids, ids=None, invert=False)

Compute the neighborhood distances between the center node.

Note

This function is designed to be used with the gdf_apply function. See the example.

Note

It is assumed that the center node is the first index in the nhood array. Use include_self=True in neighborhood to include the center.

Parameters:

Name	Type	Description	Default
nhood	Sequence[int]	An array containing neighbor indices. The first index is assumed to be the center node.	required
centroids	Series	A pd.Series array containing the centroid Points of the full gdf.	required
ids	Series	A pd.Series array containing the ids of the full gdf.	None
invert	bool	Flag, whether to invert the distances. E.g. 1/dists. Defaults to False.	False

Returns:

Type	Description
ndarray	np.ndarray: An array containing the distances between the center node and its neighborhood.

Examples:

Use gdf_apply to extract the neighboring node distances for each node/cell

>>> from functools import partial
>>> from cellseg_gsontools.data import gland_cells
>>> from cellseg_gsontools.graphs import fit_graph
>>> from cellseg_gsontools.utils import set_uid
>>> from cellseg_gsontools.apply import gdf_apply
>>> from cellseg_gsontools.neighbors import neighborhood, nhood_dists
>>> gc = gland_cells()
>>> # To fit the delaunay graph, we need to set a unique id for each cell first
>>> gc = set_uid(gc, id_col="uid")
>>> w = fit_graph(gc, type="delaunay", thresh=100, id_col="uid")
>>> # Get the neihgboring nodes of the graph
>>> func = partial(neighborhood, spatial_weights=w)
>>> gc["nhood"] = gdf_apply(gc, func, columns=["uid"])
>>> func = partial(nhood_dists, centroids=gc.centroid)
>>> gc["nhood_dists"] = gdf_apply(
...     gc,
...     func,
...     columns=["nhood"],
... )
>>> gc["nhood_dists"].head(5)
uid
0        [0.0, 26.675, 24.786, 30.068, 30.228, 41.284]
1        [0.0, 26.675, 23.428, 42.962, 39.039, 23.949]
2        [0.0, 25.577, 39.348, 46.097, 34.309, 29.478]
3    [0.0, 24.786, 25.577, 39.574, 37.829, 47.16, 3...
4    [0.0, 30.068, 23.428, 39.574, 29.225, 36.337, ...
Name: nhood_dists, dtype: object

Source code in cellseg_gsontools/neighbors.py

def nhood_dists(
    nhood: Sequence[int],
    centroids: pd.Series,
    ids: pd.Series = None,
    invert: bool = False,
) -> np.ndarray:
    """Compute the neighborhood distances between the center node.

    Note:
        This function is designed to be used with the `gdf_apply` function.
        See the example.

    Note:
        It is assumed that the center node is the first index in the `nhood`
        array. Use `include_self=True` in `neighborhood` to include the center.

    Parameters:
        nhood (Sequence[int]):
            An array containing neighbor indices. The first index is assumed to be
            the center node.
        centroids (pd.Series):
            A pd.Series array containing the centroid Points of the full gdf.
        ids (pd.Series):
            A pd.Series array containing the ids of the full gdf.
        invert (bool):
            Flag, whether to invert the distances. E.g. 1/dists. Defaults to False.

    Returns:
        np.ndarray:
            An array containing the distances between the center node and its
            neighborhood.

    Examples:
        Use `gdf_apply` to extract the neighboring node distances for each node/cell
        >>> from functools import partial
        >>> from cellseg_gsontools.data import gland_cells
        >>> from cellseg_gsontools.graphs import fit_graph
        >>> from cellseg_gsontools.utils import set_uid
        >>> from cellseg_gsontools.apply import gdf_apply
        >>> from cellseg_gsontools.neighbors import neighborhood, nhood_dists
        >>> gc = gland_cells()
        >>> # To fit the delaunay graph, we need to set a unique id for each cell first
        >>> gc = set_uid(gc, id_col="uid")
        >>> w = fit_graph(gc, type="delaunay", thresh=100, id_col="uid")
        >>> # Get the neihgboring nodes of the graph
        >>> func = partial(neighborhood, spatial_weights=w)
        >>> gc["nhood"] = gdf_apply(gc, func, columns=["uid"])
        >>> func = partial(nhood_dists, centroids=gc.centroid)
        >>> gc["nhood_dists"] = gdf_apply(
        ...     gc,
        ...     func,
        ...     columns=["nhood"],
        ... )
        >>> gc["nhood_dists"].head(5)
        uid
        0        [0.0, 26.675, 24.786, 30.068, 30.228, 41.284]
        1        [0.0, 26.675, 23.428, 42.962, 39.039, 23.949]
        2        [0.0, 25.577, 39.348, 46.097, 34.309, 29.478]
        3    [0.0, 24.786, 25.577, 39.574, 37.829, 47.16, 3...
        4    [0.0, 30.068, 23.428, 39.574, 29.225, 36.337, ...
        Name: nhood_dists, dtype: object
    """
    if isinstance(nhood, pd.Series):
        nhood = nhood.iloc[0]  # assume that the series is a row

    nhood_dists = np.array([0])
    if nhood not in (None, np.nan) and isinstance(nhood, (Sequence, np.ndarray)):
        if ids is not None:
            nhood = ids[ids.isin(nhood)].index

        node = nhood[0]
        center_node = centroids.loc[node]
        nhood_nodes = centroids.loc[nhood].to_numpy()
        nhood_dists = np.array(
            [np.round(_dist(center_node, c), 3) for c in nhood_nodes]
        )
        if invert:
            nhood_dists = np.round(np.reciprocal(nhood_dists, where=nhood_dists > 0), 3)

    return nhood_dists