bigframes.bigquery.st_difference#

bigframes.bigquery.st_difference(series: Series | GeoSeries, other: Series | GeoSeries | BaseGeometry) → Series[source]#

Returns a GEOGRAPHY that represents the point set difference of geography_1 and geography_2. Therefore, the result consists of the part of geography_1 that doesnt intersect with geography_2.

If geometry_1 is completely contained in geometry_2, then ST_DIFFERENCE returns an empty GEOGRAPHY.

Note

BigQuerys Geography functions, like st_difference, interpret the geometry data type as a point set on the Earths surface. A point set is a set of points, lines, and polygons on the WGS84 reference spheroid, with geodesic edges. See: https://cloud.google.com/bigquery/docs/geospatial-data

Examples:

>>> import bigframes as bpd
>>> import bigframes.bigquery as bbq
>>> import bigframes.geopandas
>>> from shapely.geometry import Polygon, LineString, Point

We can check two GeoSeries against each other, row by row:

>>> s1 = bigframes.geopandas.GeoSeries(
...    [
...        Polygon([(0, 0), (2, 2), (0, 2)]),
...        Polygon([(0, 0), (2, 2), (0, 2)]),
...        LineString([(0, 0), (2, 2)]),
...        LineString([(2, 0), (0, 2)]),
...        Point(0, 1),
...    ],
... )
>>> s2 = bigframes.geopandas.GeoSeries(
...    [
...        Polygon([(0, 0), (1, 1), (0, 1)]),
...        LineString([(1, 0), (1, 3)]),
...        LineString([(2, 0), (0, 2)]),
...        Point(1, 1),
...        Point(0, 1),
...    ],
...    index=range(1, 6),
... )

>>> s1
0    POLYGON ((0 0, 2 2, 0 2, 0 0))
1    POLYGON ((0 0, 2 2, 0 2, 0 0))
2             LINESTRING (0 0, 2 2)
3             LINESTRING (2 0, 0 2)
4                       POINT (0 1)
dtype: geometry

>>> s2
1    POLYGON ((0 0, 1 1, 0 1, 0 0))
2             LINESTRING (1 0, 1 3)
3             LINESTRING (2 0, 0 2)
4                       POINT (1 1)
5                       POINT (0 1)
dtype: geometry

>>> bbq.st_difference(s1, s2)
0                                               None
1    POLYGON ((0.99954 1, 2 2, 0 2, 0 1, 0.99954 1))
2                   LINESTRING (0 0, 1 1.00046, 2 2)
3                           GEOMETRYCOLLECTION EMPTY
4                                        POINT (0 1)
5                                               None
dtype: geometry

Additionally, we can check difference of a GeoSeries against a single shapely geometry:

>>> polygon = Polygon([(0, 0), (10, 0), (10, 10), (0, 0)])
>>> bbq.st_difference(s1, polygon)
0    POLYGON ((1.97082 2.00002, 0 2, 0 0, 1.97082 2...
1    POLYGON ((1.97082 2.00002, 0 2, 0 0, 1.97082 2...
2                             GEOMETRYCOLLECTION EMPTY
3                    LINESTRING (0.99265 1.00781, 0 2)
4                                          POINT (0 1)
dtype: geometry

Parameters:

• series (bigframes.pandas.Series | bigframes.geopandas.GeoSeries) A series containing geography objects.

• other (bigframes.pandas.Series | bigframes.geopandas.GeoSeries | shapely.Geometry) The series or geometric object to subtract from the geography objects in series.

Returns:

A GeoSeries of the points in each aligned geometry that are not in other.

Return type:

bigframes.series.Series