Skip to content

get_objs

Query objects in relation to the given area GeoDataFrame (tissue segmentations).

Parameters:

Name Type Description Default
area GeoDataFrame

Area of interest. The objects that intersect with this area will be returned.

 required
objects GeoDataFrame

Objects to check for intersection with the area.

 required
predicate str

Predicate for the spatial query. One of contains", "contains_properly", "covered_by", "covers", "crosses", "intersects", "overlaps", "touches", "within", "dwithin"

 'intersects'
**kwargs Any

Additional keyword arguments to pass to the spatial query.

 {}

Returns:

Type Description
Union[GeoDataFrame, None]

Union[gpd.GeoDataFrame, None]: Objects that intersect with the given area.

Examples:

>>> from histolytics.data import cervix_nuclei, cervix_tissue
>>> from histolytics.spatial_ops import get_objs
>>> # load the data
>>> nuc = cervix_nuclei()
>>> tis = cervix_tissue()
>>> # select the CIN tissue
>>> cin_tissue = tis[tis["class_name"] == "cin"]
>>>
>>> # select all the nuclei contained within CIN tissue
>>> nuc_within_cin = get_objs(cin_tissue, nuc, predicate="contains")
>>> print(nuc_within_cin.head(3))
                                            geometry         class_name
1  POLYGON ((906.01 5350.02, 906.01 5361, 908.01 ...         connective
2  POLYGON ((866 5137.02, 862.77 5137.94, 860 513...   squamous_epithel
3  POLYGON ((932 4777.02, 928 4778.02, 922.81 478...  glandular_epithel
>>> ax = tis.plot(column="class_name", figsize=(5, 5), aspect=1, alpha=0.5)
>>> nuc_within_cin.plot(ax=ax, color="blue")
>>> ax.set_axis_off()

out

Source code in src/histolytics/spatial_ops/ops.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def get_objs(
    area: gpd.GeoDataFrame,
    objects: gpd.GeoDataFrame,
    predicate: str = "intersects",
    **kwargs,
) -> Union[gpd.GeoDataFrame, None]:
    """Query objects in relation to the given `area` GeoDataFrame (tissue segmentations).

    Parameters:
        area (gpd.GeoDataFrame):
            Area of interest. The objects that intersect with this area will be returned.
        objects (gpd.GeoDataFrame):
            Objects to check for intersection with the area.
        predicate (str):
            Predicate for the spatial query. One of contains", "contains_properly",
            "covered_by", "covers", "crosses", "intersects", "overlaps", "touches",
            "within", "dwithin"
        **kwargs (Any):
            Additional keyword arguments to pass to the spatial query.

    Returns:
        Union[gpd.GeoDataFrame, None]:
            Objects that intersect with the given area.

    Examples:
        >>> from histolytics.data import cervix_nuclei, cervix_tissue
        >>> from histolytics.spatial_ops import get_objs
        >>> # load the data
        >>> nuc = cervix_nuclei()
        >>> tis = cervix_tissue()
        >>> # select the CIN tissue
        >>> cin_tissue = tis[tis["class_name"] == "cin"]
        >>>
        >>> # select all the nuclei contained within CIN tissue
        >>> nuc_within_cin = get_objs(cin_tissue, nuc, predicate="contains")
        >>> print(nuc_within_cin.head(3))
                                                    geometry         class_name
        1  POLYGON ((906.01 5350.02, 906.01 5361, 908.01 ...         connective
        2  POLYGON ((866 5137.02, 862.77 5137.94, 860 513...   squamous_epithel
        3  POLYGON ((932 4777.02, 928 4778.02, 922.81 478...  glandular_epithel
        >>> ax = tis.plot(column="class_name", figsize=(5, 5), aspect=1, alpha=0.5)
        >>> nuc_within_cin.plot(ax=ax, color="blue")
        >>> ax.set_axis_off()
    ![out](../../img/get_objs.png)
    """
    # NOTE, gdfs need to have same crs, otherwise warning flood.
    inds = objects.geometry.sindex.query(area.geometry, predicate=predicate, **kwargs)
    objs: gpd.GeoDataFrame = objects.iloc[np.unique(inds)[1:]]

    return objs.drop_duplicates("geometry")