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
) -> 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.

    Info

    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"))

    Info

    With DuckDB >= 1.5, the CRS of a GEOMETRY column is read automatically from the column type. For WKB_BLOB or 2D columns, DuckDB older than 1.5, or a GEOMETRY column without a CRS encoded, 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 has either an __arrow_c_array__ or __arrow_c_stream__ method, that is, it implements the Arrow PyCapsule Interface. 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, Sedona DB sessions, 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.

viz returns a regular Map, whose layers are in Map.layers. So you can change how the data looks after calling viz by setting attributes on the map or on its layers. A map that is already displayed updates in place.

import geodatasets
import geopandas as gpd
from lonboard import viz

# New York City boroughs
gdf = gpd.read_file(geodatasets.get_path("nybb"))
m = viz(gdf)
m

Then, in a later cell:

# `viz` created one `PolygonLayer` for this data
layer = m.layers[0]
layer.get_fill_color = [255, 0, 0]
layer.get_line_color = [255, 255, 255]

viz creates one layer per geometry type in each input, so check the type of each layer in m.layers when you pass mixed geometries or more than one input.

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.

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.