GeoDataFrame

polars_st.GeoDataFrame

GeoDataFrame(
    data: FrameInitTypes | None = None,
    schema: SchemaDefinition | None = None,
    *,
    geometry_name: str = "geometry",
    geometry_format: (
        Literal[
            "wkb",
            "wkt",
            "ewkt",
            "geojson",
            "shapely",
            "coords",
            "point",
            "multipoint",
            "linestring",
            "circularstring",
            "multilinestring",
            "polygon",
        ]
        | None
    ) = None,
    schema_overrides: SchemaDict | None = None,
    strict: bool = True,
    orient: Orientation | None = None,
    infer_schema_length: int | None = N_INFER_DEFAULT,
    nan_to_null: bool = False
)

Bases: DataFrame

Create a new GeoDataFrame.

GeoDataFrame is used as an alias for pl.DataFrame with type annotations added for the st namespace, and an overriden constructor which will parse the column identified by geometry_name (default "geometry") into a GeoSeries.

See pl.DataFrame for parameters documentation.

Note

Because Polars doesn't support subclassing of their types, calling this constructor will NOT create an instance of GeoDataFrame, but an instance of pl.DataFrame.

As a result, instance checks are not permitted on this class to prevent misuse:

>>> gdf = st.GeoDataFrame(["POINT(0 0)"])
>>> type(gdf)
<class 'polars.dataframe.frame.DataFrame'>
>>> isinstance(gdf, st.GeoDataFrame)
Traceback (most recent call last):
...
TypeError: instance check on abstract class GeoDataFrame is not allowed

Examples:

>>> gdf = st.GeoDataFrame({
...     "geometry": [
...         "POINT(0 0)",
...         "POINT(1 2)",
...     ]
... })
>>> gdf.schema
Schema({'geometry': Binary})

>>> gdf = st.GeoDataFrame(
...     {
...         "geom": [
...             '{"type": "Point", "coordinates": [0, 0]}',
...             '{"type": "Point", "coordinates": [1, 2]}',
...         ]
...     },
...     geometry_name="geom",
...     geometry_format="geojson",
... )
>>> gdf.schema
Schema({'geom': Binary})

st property

st: GeoDataFrameNameSpace

polars_st.GeoDataFrameNameSpace

polars_st.GeoDataFrameNameSpace.__geo_interface__ property

__geo_interface__: dict

Return a GeoJSON FeatureCollection dict representation of the DataFrame.

Examples:

>>> gdf = st.GeoDataFrame({
...     "geometry": ["POINT(0 0)", "POINT(1 2)"],
...     "name": ["Alice", "Bob"]
... })
>>> interface = gdf.st.__geo_interface__
>>> pprint.pp(interface)
{'type': 'FeatureCollection',
 'features': [{'type': 'Feature',
               'geometry': {'type': 'Point', 'coordinates': [0.0, 0.0]},
               'properties': {'name': 'Alice'}},
              {'type': 'Feature',
               'geometry': {'type': 'Point', 'coordinates': [1.0, 2.0]},
               'properties': {'name': 'Bob'}}]}

polars_st.GeoDataFrameNameSpace.sjoin

sjoin(
    other: DataFrame,
    on: str | Expr = "geometry",
    how: JoinStrategy = "inner",
    predicate: Literal[
        "intersects_bbox",
        "intersects",
        "within",
        "contains",
        "overlaps",
        "crosses",
        "touches",
        "covers",
        "covered_by",
        "contains_properly",
    ] = "intersects",
    *,
    left_on: str | Expr | None = None,
    right_on: str | Expr | None = None,
    suffix: str = "_right",
    validate: JoinValidation = "m:m",
    coalesce: bool | None = None
) -> GeoDataFrame

Perform a spatial join operation with another DataFrame.

polars_st.GeoDataFrameNameSpace.to_wkt

to_wkt(
    *geometry_columns: str,
    rounding_precision: int | None = 6,
    trim: bool = True,
    output_dimension: Literal[2, 3, 4] = 3,
    old_3d: bool = False
) -> DataFrame

Serialize the DataFrame geometry column as WKT.

See GeoExprNameSpace.to_wkt.

polars_st.GeoDataFrameNameSpace.to_ewkt

to_ewkt(
    *geometry_columns: str,
    rounding_precision: int | None = 6,
    trim: bool = True,
    output_dimension: Literal[2, 3, 4] = 3,
    old_3d: bool = False
) -> DataFrame

Serialize the DataFrame geometry column as EWKT.

See GeoExprNameSpace.to_ewkt.

polars_st.GeoDataFrameNameSpace.to_wkb

to_wkb(
    *geometry_columns: str,
    output_dimension: Literal[2, 3, 4] = 3,
    byte_order: Literal[0, 1] | None = None,
    include_srid: bool = False
) -> DataFrame

Serialize the DataFrame geometry column as WKB.

See GeoExprNameSpace.to_wkb.

polars_st.GeoDataFrameNameSpace.to_geojson

to_geojson(*geometry_columns: str, indent: int | None = None) -> DataFrame

Serialize the DataFrame geometry column as GeoJSON.

See GeoExprNameSpace.to_geojson.

polars_st.GeoDataFrameNameSpace.to_shapely

to_shapely(*geometry_columns: str) -> DataFrame

Convert the DataFrame geometry column to a shapely representation.

See GeoExprNameSpace.to_shapely.

polars_st.GeoDataFrameNameSpace.to_dict

to_dict(*geometry_columns: str) -> DataFrame

Convert the DataFrame geometry column to a GeoJSON-like Python dict representation.

See GeoExprNameSpace.to_dict.

polars_st.GeoDataFrameNameSpace.to_dicts

to_dicts(geometry_name: str = 'geometry') -> list[dict[str, Any]]

Convert every row to a Python dict representation of a GeoJSON Feature.

Examples:

>>> gdf = st.GeoDataFrame({
...     "name": ["Alice", "Bob"],
...     "location": ["POINT(0 0)", "POINT(1 2)"],
... }, geometry_name="location")
>>> dicts = gdf.st.to_dicts("location")
>>> dicts[0]
{'type': 'Feature', 'geometry': {'type': 'Point', 'coordinates': [0.0, 0.0]}, 'properties': {'name': 'Alice'}}

polars_st.GeoDataFrameNameSpace.to_geopandas

to_geopandas(
    *,
    geometry_name: str = "geometry",
    use_pyarrow_extension_array: bool = False,
    **kwargs: Any
) -> GeoDataFrame

Convert this DataFrame to a geopandas GeoDataFrame.

polars_st.GeoDataFrameNameSpace.write_file

write_file(
    path: str | BytesIO,
    layer: str | None = None,
    driver: str | None = None,
    geometry_name: str = "geometry",
    encoding: str | None = None,
    append: bool = False,
    dataset_metadata: dict | None = None,
    layer_metadata: dict | None = None,
    metadata: dict | None = None,
    dataset_options: dict | None = None,
    layer_options: dict | None = None,
    **kwargs: dict[str, Any]
) -> None

Write the GeoDataFrame to an OGR supported file format.

Parameters:

• path (str | BytesIO) –

  path to output file on writeable file system or an io.BytesIO object to allow writing to memory NOTE: support for writing to memory is limited to specific drivers.

• layer (str | None, default: None ) –

  layer name to create. If writing to memory and layer name is not provided, it layer name will be set to a UUID4 value.

• driver (str | None, default: None ) –

  The OGR format driver used to write the vector file. By default attempts to infer driver from path. Must be provided to write to memory. The available drivers can be listed by calling:

  >>> import pyogrio
  >>> pyogrio.list_drivers() # doctest: +SKIP
  {..., 'GeoJSON': 'rw', 'GeoJSONSeq': 'rw',...}
  

• geometry_name (str, default: 'geometry' ) –

  The name of the column in the input data that will be written as the geometry field.

• encoding (str | None, default: None ) –

  Only used for the .dbf file of ESRI Shapefiles. If not specified, uses the default locale.

• append (bool, default: False ) –

  If True, the data source specified by path already exists, and the driver supports appending to an existing data source, will cause the data to be appended to the existing records in the data source. Not supported for writing to in-memory files. NOTE: append support is limited to specific drivers and GDAL versions.

• dataset_metadata (dict | None, default: None ) –

  Metadata to be stored at the dataset level in the output file; limited to drivers that support writing metadata, such as GPKG, and silently ignored otherwise. Keys and values must be strings.

• layer_metadata (dict | None, default: None ) –

  Metadata to be stored at the layer level in the output file; limited to drivers that support writing metadata, such as GPKG, and silently ignored otherwise. Keys and values must be strings.

• metadata (dict | None, default: None ) –

  alias of layer_metadata

• dataset_options (dict | None, default: None ) –

  Dataset creation options (format specific) passed to OGR. Specify as a key-value dictionary.

• layer_options (dict | None, default: None ) –

  Layer creation options (format specific) passed to OGR. Specify as a key-value dictionary.

• **kwargs (dict[str, Any], default: {} ) –

  Additional driver-specific dataset or layer creation options passed to OGR. pyogrio will attempt to automatically pass those keywords either as dataset or as layer creation option based on the known options for the specific driver. Alternatively, you can use the explicit dataset_options or layer_options keywords to manually do this (for example if an option exists as both dataset and layer option).

polars_st.GeoDataFrameNameSpace.write_geojson

write_geojson(file: None = None) -> str

write_geojson(file: IOBase | str | Path) -> None

write_geojson(file: IOBase | str | Path | None = None) -> str | None

Serialize to GeoJSON FeatureCollection representation.

The result will be invalid if the geometry column contains different geometry types.

Examples:

>>> gdf = st.GeoDataFrame({
...     "geometry": ["POINT(0 0)", "POINT(1 2)"],
...     "name": ["Alice", "Bob"]
... })
>>> geojson = gdf.st.write_geojson()
>>> print(geojson)
{"type":"FeatureCollection","features":[{"properties":{"name":"Alice"},"geometry":{"type":"Point","coordinates":[0.0,0.0]}},{"properties":{"name":"Bob"},"geometry":{"type":"Point","coordinates":[1.0,2.0]}}]}

polars_st.GeoDataFrameNameSpace.write_ndgeojson

write_ndgeojson(file: None = None) -> str

write_ndgeojson(file: IOBase | str | Path) -> None

write_ndgeojson(file: IOBase | str | Path | None = None) -> str | None

Serialize to newline-delimited GeoJSON representation.

The result will be invalid if the geometry column contains different geometry types.

Examples:

>>> gdf = st.GeoDataFrame({
...     "geometry": ["POINT(0 0)", "POINT(1 2)"],
...     "name": ["Alice", "Bob"]
... })
>>> ndgeojson = gdf.st.write_ndgeojson()
>>> print(ndgeojson)
{"properties":{"name":"Alice"},"geometry":{"type":"Point","coordinates":[0.0,0.0]}}
{"properties":{"name":"Bob"},"geometry":{"type":"Point","coordinates":[1.0,2.0]}}

polars_st.GeoDataFrameNameSpace.plot

plot(
    geometry_name: str = "geometry", **kwargs: Unpack[MarkConfigKwds]
) -> Chart

Draw map plot.

Polars does not implement plotting logic itself but instead defers to Altair.

df.st.plot(**kwargs) is shorthand for alt.Chart({"values": df.st.to_dicts()}).mark_geoshape(**kwargs).interactive(). Please read Altair GeoShape documentation for available options.

Please note that the dataframe will be converted to a GeoJSON FeatureCollection, so columns will need to be prefixed with properties. for access in Altair functions.

Examples:

>>> url = "https://naciscdn.org/naturalearth/110m/cultural/ne_110m_admin_0_countries.zip"
>>> plot = (
...     st.read_file(url)
...     .with_columns(st.simplify(tolerance=1))
...     .st.plot()
...     .encode(color="properties.CONTINENT:N")
...     .configure_legend(title=None)
...     .properties(height=150)
... )

>>> import altair as alt
>>> df = st.GeoDataFrame({
... "color": ["red","yellow", "blue"],
... "geometry": [
...     "POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))",
...     "POLYGON((0 0, 1 2, 2 0, 0 0))",
...     "POINT(2 1)"
... ]})
>>> plot = (
...     df.st.plot(blend="difference")
...     .encode(fill=alt.Color("properties.color:N", scale=None))
...     .project("identity", reflectY=True, pointRadius=100)
...     .properties(height=200)
... )