nhood_counts

cellseg_gsontools.neighbors.nhood_counts(nhood, values, bins, **kwargs)

Get the counts of objects that belong to bins/classes in the neighborhood.

Note

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

Parameters:

Name	Type	Description	Default
nhood	Sequence[int]	A list or array of neighboring node uids.	required
values	Series	A value column-vector of shape (N, ).	required
bins	Sequence	The bins of any value vector. Shape (n_bins, ).	required
return_vals	bool	If True, also, the values the values are. Defaults to False.	required
**kwargs	Dict[str, Any]	Additional keyword arguments. Not used.	{}

Returns:

Type	Description
ndarray	np.ndarray: The counts vector of the given values vector. Shape (n_classes, )

Examples:

Use gdf_apply to compute the neighborhood counts for each areal bin

>>> import mapclassify
>>> 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_vals, nhood_counts
>>> 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"])
>>> # get the area values of the neighbors
>>> func = partial(nhood_vals, values=gc.area.round(2))
>>> gc["neighbor_areas"] = gdf_apply(
...     gc,
...     func=func,
...     parallel=True,
...     columns=["nhood"],
... )
>>> bins = mapclassify.Quantiles(gc.area, k=5)
>>> func = partial(nhood_counts, values=gc.area, bins=bins.bins)
>>> gc["area_bins"] = gdf_apply(
...     gc,
...     func,
...     columns=["nhood"],
... )
>>> gc["area_bins"].head(5)
uid
0    [0, 2, 0, 3, 1]
1    [0, 2, 1, 2, 1]
2    [0, 0, 0, 3, 3]
3    [0, 1, 0, 3, 3]
4    [0, 1, 0, 3, 3]
Name: area_bins, dtype: object

Source code in cellseg_gsontools/neighbors.py

def nhood_counts(
    nhood: Sequence[int], values: pd.Series, bins: Sequence, **kwargs
) -> np.ndarray:
    """Get the counts of objects that belong to bins/classes in the neighborhood.

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

    Parameters:
        nhood (Sequence[int]):
            A list or array of neighboring node uids.
        values (pd.Series):
            A value column-vector of shape (N, ).
        bins (Sequence):
            The bins of any value vector. Shape (n_bins, ).
        return_vals (bool, optional):
            If True, also, the values the values are. Defaults to False.
        **kwargs (Dict[str, Any]):
            Additional keyword arguments. Not used.

    Returns:
        np.ndarray:
            The counts vector of the given values vector. Shape (n_classes, )

    Examples:
        Use `gdf_apply` to compute the neighborhood counts for each areal bin
        >>> import mapclassify
        >>> 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_vals, nhood_counts
        >>> 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"])
        >>> # get the area values of the neighbors
        >>> func = partial(nhood_vals, values=gc.area.round(2))
        >>> gc["neighbor_areas"] = gdf_apply(
        ...     gc,
        ...     func=func,
        ...     parallel=True,
        ...     columns=["nhood"],
        ... )
        >>> bins = mapclassify.Quantiles(gc.area, k=5)
        >>> func = partial(nhood_counts, values=gc.area, bins=bins.bins)
        >>> gc["area_bins"] = gdf_apply(
        ...     gc,
        ...     func,
        ...     columns=["nhood"],
        ... )
        >>> gc["area_bins"].head(5)
        uid
        0    [0, 2, 0, 3, 1]
        1    [0, 2, 1, 2, 1]
        2    [0, 0, 0, 3, 3]
        3    [0, 1, 0, 3, 3]
        4    [0, 1, 0, 3, 3]
        Name: area_bins, dtype: object
    """
    if isinstance(nhood, pd.Series):
        nhood = nhood.iloc[0]  # assume that the series is a row

    counts = np.array([0])
    if nhood not in (None, np.nan) and isinstance(nhood, (Sequence, np.ndarray)):
        nhood_vals = values.loc[nhood]

        if is_categorical(nhood_vals):
            counts = nhood_vals.value_counts().values
        else:
            sample_bins = mapclassify.UserDefined(nhood_vals, bins)
            counts = sample_bins.counts

    return counts