Skip to content

Starting From a Polars Dataframe

Spatial polars has a few ways to create a dataframe with a geometry column in the appropriate format for spatial polars functionality to operate that do not involve reading directly from a spatial source. If you have an existing dataframe with coordinates of points, or WKB/WKT, you're in luck!

setup
import polars as pl
import shapely
from spatial_polars import SpatialFrame

From Point Coords

Spatial polars provides a way to take an existing polars dataframe with columns of X/Y (and optionally Z) coordinates, and convert them to work with the spatial polars functionality. We can use SpatialFrame.from_point_coords to take the dataframe and convert the coordinates into a spatial polars geometry struct column.

In the example below we'll create a polars DataFrame with a 'Place' column, for the name of the place, along with x/y/z coordinates.

from point coords
df = pl.DataFrame(  # (1)!
    {
        "Place": ["Gateway Arch", "Monks Mound"],
        "x": [-90.18497, -90.06211],
        "y": [38.62456, 38.66072],
        "z": [0, 0],
    }
)
print("Before SpatialFrame.from_point_coords:")
print(df)
s_df1 = SpatialFrame.from_point_coords(df, x_col="x", y_col="y", z_col="z")  # (2)!
print("After SpatialFrame.from_point_coords:")
print(s_df1)
  1. Creating a polars dataframe with x/y/z coordinates

  2. SpatialFrame.from_point_coords takes the x/y/z coordinates and converts them to a struct column with the geometry as WKB and a CRS

    Note

    Because we are not specifying a crs WGS84:4326 is defaulted.

Before SpatialFrame.from_point_coords:
shape: (2, 4)
┌──────────────┬───────────┬──────────┬─────┐
│ Place        ┆ x         ┆ y        ┆ z   │
│ ---          ┆ ---       ┆ ---      ┆ --- │
│ str          ┆ f64       ┆ f64      ┆ i64 │
╞══════════════╪═══════════╪══════════╪═════╡
│ Gateway Arch ┆ -90.18497 ┆ 38.62456 ┆ 0   │
│ Monks Mound  ┆ -90.06211 ┆ 38.66072 ┆ 0   │
└──────────────┴───────────┴──────────┴─────┘
After SpatialFrame.from_point_coords:
shape: (2, 2)
┌──────────────┬─────────────────────────────────┐
│ Place        ┆ geometry                        │
│ ---          ┆ ---                             │
│ str          ┆ struct[2]                       │
╞══════════════╪═════════════════════════════════╡
│ Gateway Arch ┆ {b"\x01\x01\x00\x00\x80o/i\x8c… │
│ Monks Mound  ┆ {b"\x01\x01\x00\x00\x80K\xb08\… │
└──────────────┴─────────────────────────────────┘

From WKB

Spatial polars provides a way to take an existing polars dataframe with a column of WKB, and convert it to work with the spatial polars functionality. We can use SpatialFrame.from_WKB to take the dataframe and convert the WKB into a spatial polars geometry struct column.

In the cell below we'll create a polars DataFrame with a 'Place' column, for the name of the place, along with a column containting WKB.

from wkb
arch_wkb = shapely.Point(-90.18497, 38.62456).wkb
monks_mound_wkb = shapely.Point(-90.06211, 38.66072).wkb
df = pl.DataFrame(  # (1)!
    {
        "Place": ["Gateway Arch", "Monks Mound"],
        "wkb": [arch_wkb, monks_mound_wkb],
    }
)
print("Before SpatialFrame.from_WKB:")
print(df)
s_df2 = SpatialFrame.from_WKB(df, "wkb")  # (2)!
print("After SpatialFrame.from_WKB:")
print(s_df2)
  1. Creating a polars dataframe with column of WKB

  2. SpatialFrame.from_WKB takes the wkb column and adds it to a struct column with the CRS

    Note

    Because we are not specifying a crs WGS84:4326 is defaulted.

Before SpatialFrame.from_WKB:
shape: (2, 2)
┌──────────────┬─────────────────────────────────┐
│ Place        ┆ wkb                             │
│ ---          ┆ ---                             │
│ str          ┆ binary                          │
╞══════════════╪═════════════════════════════════╡
│ Gateway Arch ┆ b"\x01\x01\x00\x00\x00o/i\x8c\… │
│ Monks Mound  ┆ b"\x01\x01\x00\x00\x00K\xb08\x… │
└──────────────┴─────────────────────────────────┘
After SpatialFrame.from_WKB:
shape: (2, 2)
┌──────────────┬─────────────────────────────────┐
│ Place        ┆ geometry                        │
│ ---          ┆ ---                             │
│ str          ┆ struct[2]                       │
╞══════════════╪═════════════════════════════════╡
│ Gateway Arch ┆ {b"\x01\x01\x00\x00\x00o/i\x8c… │
│ Monks Mound  ┆ {b"\x01\x01\x00\x00\x00K\xb08\… │
└──────────────┴─────────────────────────────────┘

From WKT

Spatial polars provides a way to take an existing polars dataframe with a column of WKT, and convert it to work with the spatial polars functionality. We can use SpatialFrame.from_WKT to take the dataframe and convert the WKT into a spatial polars geometry struct column.

In the cell below we'll create a polars DataFrame with a 'Place' column, for the name of the place, along with a column containting WKT.

from wkt
arch_wkt = shapely.Point(-90.18497, 38.62456).wkt
monks_mound_wkt = shapely.Point(-90.06211, 38.66072).wkt
df = pl.DataFrame(  # (1)!
    {
        "Place": ["Gateway Arch", "Monks Mound"],
        "wkt": [arch_wkt, monks_mound_wkt],
    }
)
print("Before SpatialFrame.from_WKT:")
print(df)
s_df3 = SpatialFrame.from_WKT(df, "wkt")  # (2)!
print("After SpatialFrame.from_WKT:")
print(s_df3)
  1. Creating a polars dataframe with column of WKT

  2. SpatialFrame.from_WKT takes the wkt column, converts it to WKB and adds it to a struct column with the CRS

    Note

    Because we are not specifying a crs WGS84:4326 is defaulted.

Before SpatialFrame.from_WKT:
shape: (2, 2)
┌──────────────┬────────────────────────────┐
│ Place        ┆ wkt                        │
│ ---          ┆ ---                        │
│ str          ┆ str                        │
╞══════════════╪════════════════════════════╡
│ Gateway Arch ┆ POINT (-90.18497 38.62456) │
│ Monks Mound  ┆ POINT (-90.06211 38.66072) │
└──────────────┴────────────────────────────┘
After SpatialFrame.from_WKT:
shape: (2, 2)
┌──────────────┬─────────────────────────────────┐
│ Place        ┆ geometry                        │
│ ---          ┆ ---                             │
│ str          ┆ struct[2]                       │
╞══════════════╪═════════════════════════════════╡
│ Gateway Arch ┆ {b"\x01\x01\x00\x00\x00o/i\x8c… │
│ Monks Mound  ┆ {b"\x01\x01\x00\x00\x00K\xb08\… │
└──────────────┴─────────────────────────────────┘