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:

• data (Union[VizDataInput, List[VizDataInput], Tuple[VizDataInput, ...]]) –

  a data object of any supported type.

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.