Skip to content

viz

lonboard.viz 

viz(
    data: VizDataInput | list[VizDataInput] | tuple[VizDataInput, ...],
    *,
    scatterplot_kwargs: ScatterplotLayerKwargs | None = None,
    path_kwargs: PathLayerKwargs | None = None,
    polygon_kwargs: PolygonLayerKwargs | None = None,
    map_kwargs: MapKwargs | None = None,
    con: DuckDBPyConnection | None = None
) -> Map

Plot your data easily.

The goal of this function is to make it simple to get something showing on a map. For more control over rendering, construct Map and Layer objects directly.

This function accepts a variety of geospatial inputs:

  • GeoPandas GeoDataFrame.
  • GeoPandas GeoSeries.
  • numpy array of Shapely objects.
  • Single Shapely object.

  • A DuckDB query with a spatial column from DuckDB Spatial.

    Warning

    The DuckDB query must be run with duckdb.sql() or duckdb.DuckDBPyConnection.sql() and not with duckdb.execute() or duckdb.DuckDBPyConnection.execute().

    For example

    import duckdb
from lonboard import viz

sql = "SELECT * FROM spatial_table;"
query = duckdb.sql(sql)
viz(query)

    You can also render an entire table by using the table() method:

    import duckdb
from lonboard import viz

con = duckdb.connect()
con.execute("CREATE TABLE spatial_table AS ...;")
viz(con.table("spatial_table"))

    Warning

    DuckDB Spatial does not currently expose coordinate reference system information, so the user must ensure that data has been reprojected to EPSG:4326.

  • Any Python class with a __geo_interface__ property conforming to the Geo Interface protocol.

  • dict holding GeoJSON-like data.
  • pyarrow Table with a geometry column marked with a GeoArrow extension type.
  • pyarrow Array or ChunkedArray marked with a GeoArrow extension type defined by geoarrow-pyarrow.

  • Arrow-compatible Array, ChunkedArray, Table, or RecordBatch objects that have associated GeoArrow metadata. An object is "Arrow-compatible" if it implements the Arrow PyCapsule Interface and has either an __arrow_c_array__ or __arrow_c_stream__ method. The provided Arrow data must be or have a geometry column marked with a GeoArrow extension type.

    Some examples of these sources include pyogrio's open_arrow, DuckDB Spatial, GeoArrow-Rust's Python bindings, GeoDataFusion database connections, and, soon, GeoPolars DataFrames.

Alternatively, you can pass a list or tuple of any of the above inputs.

If you want to easily add more data, to an existing map, you can pass the output of viz into Map.add_layer.

Parameters:

Other Parameters:

  • scatterplot_kwargs (ScatterplotLayerKwargs | None) –

    a dict of parameters to pass down to all generated ScatterplotLayers.

  • path_kwargs (PathLayerKwargs | None) –

    a dict of parameters to pass down to all generated PathLayers.

  • polygon_kwargs (PolygonLayerKwargs | None) –

    a dict of parameters to pass down to all generated PolygonLayers.

  • map_kwargs (MapKwargs | None) –

    a dict of parameters to pass down to the generated Map.

  • con (DuckDBPyConnection | None) –

    Deprecated: the active DuckDB connection. This argument has no effect and might be removed in the future.

For more control over rendering, construct Map and Layer objects directly.

Returns:

  • Map –

    widget visualizing the provided data.

VizDataInput module-attribute 

VizDataInput: TypeAlias = (
    GeoDataFrame
    | GeoSeries
    | Table
    | NDArray[object_]
    | BaseGeometry
    | ArrowArrayExportable
    | ArrowStreamExportable
    | GeoInterfaceProtocol
    | dict[str, Any]
    | DuckDBPyRelation
)

A type definition for allowed data inputs to the viz function.