Skip to content

GeoDataFrame

polars_st.GeoDataFrame #

GeoDataFrame(
    data: FrameInitTypes | None = None,
    schema: SchemaDefinition | 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.

A GeoDataFrame is a regular polars.DataFrame with type annotations added for the st namespace.

If a GeoDataFrame is created with a column matching the Configuration default geometry column name, that column will be parsed into a GeoSeries.

Examples:

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

>>> gdf = st.GeoDataFrame([
...     "POINT(0 0)",
...     "POINT(1 2)",
... ])
>>> gdf.schema
Schema([('geometry', 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__
>>> 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 | None = None,
    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(
    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(
    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(
    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(indent: int | None = None) -> DataFrame

Serialize the DataFrame geometry column as GeoJSON.

See GeoExprNameSpace.to_geojson.

polars_st.GeoDataFrameNameSpace.to_shapely #

to_shapely() -> DataFrame

Convert the DataFrame geometry column to a shapely representation.

See GeoExprNameSpace.to_shapely.

polars_st.GeoDataFrameNameSpace.to_dict #

to_dict() -> DataFrame

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

See GeoExprNameSpace.to_dict.

polars_st.GeoDataFrameNameSpace.to_dicts #

to_dicts() -> list[dict[str, Any]]

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

polars_st.GeoDataFrameNameSpace.to_geopandas #

to_geopandas(
    *, 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_type: (
        Literal[
            "Unknown",
            "Point",
            "LineString",
            "Polygon",
            "MultiPoint",
            "MultiLineString",
            "MultiPolygon",
            "GeometryCollection",
        ]
        | None
    ) = None,
    crs: str | None = None,
    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.

  • geometry_type (Literal['Unknown', 'Point', 'LineString', 'Polygon', 'MultiPoint', 'MultiLineString', 'MultiPolygon', 'GeometryCollection'] | None, default: None ) –

    The geometry type of the written layer. Currently, this needs to be specified explicitly when creating a new layer with geometries.

    This parameter does not modify the geometry, but it will try to force the layer type of the output file to this value. Use this parameter with caution because using a wrong layer geometry type may result in errors when writing the file, may be ignored by the driver, or may result in invalid files.

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

    WKT-encoded CRS of the geometries to be written.

  • 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: 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_geojsonseq #

write_geojsonseq(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"]
... })
>>> geojsonseq = gdf.st.write_geojsonseq()
>>> print(geojsonseq)
{"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(**kwargs: Unpack[EncodeKwds]) -> 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(df).mark_geoshape().encode(**kwargs).interactive(). Please read Altair GeoShape documentation for available options.