Skip to content

viz

lonboard.viz

viz(
    data: Union[VizDataInput, List[VizDataInput], Tuple[VizDataInput, ...]],
    *,
    scatterplot_kwargs: Optional[ScatterplotLayerKwargs] = None,
    path_kwargs: Optional[PathLayerKwargs] = None,
    polygon_kwargs: Optional[PolygonLayerKwargs] = None,
    map_kwargs: Optional[MapKwargs] = None,
    con: Optional[DuckDBPyConnection] = None
) -> Map

A high-level function to 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)
    

    If you're using a custom connection, ensure you pass in the con parameter:

    import duckdb
    from lonboard import viz
    
    con = duckdb.connect()
    sql = "SELECT * FROM spatial_table;"
    query = con.sql(sql)
    viz(query, con=con)
    

    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(), con=con)
    

    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 marked with a GeoArrow extension type defined by geoarrow-pyarrow.

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 (Optional[ScatterplotLayerKwargs]) –

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

  • path_kwargs (Optional[PathLayerKwargs]) –

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

  • polygon_kwargs (Optional[PolygonLayerKwargs]) –

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

  • map_kwargs (Optional[MapKwargs]) –

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

  • con (Optional[DuckDBPyConnection]) –

    the active DuckDB connection. This is necessary in some cases when passing in a DuckDB query. In particular, if you're using a non-global DuckDB connection and if your SQL query outputs the default GEOMETRY type.

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

Returns:

  • Map

    widget visualizing the provided data.

VizDataInput module-attribute

VizDataInput = Union[
    GeoDataFrame,
    GeoSeries,
    Table,
    NDArray[object_],
    BaseGeometry,
    ArrowArrayExportable,
    ArrowStreamExportable,
    GeoInterfaceProtocol,
    Dict[str, Any],
    DuckDBPyRelation,
]

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