cartoframes.contrib.vector module¶
This module allows users to create interactive vector maps using CARTO VL.
The API for vector maps is broadly similar to CartoContext.map
, with the exception that all styling
expressions are expected to be straight CARTO VL expressions. See examples in
the CARTO VL styling guide
-
class
cartoframes.contrib.vector.
Layer
(table_name, color=None, size=None, time=None, strokeColor=None, strokeWidth=None, interactivity=None)¶ Bases:
cartoframes.contrib.vector.QueryLayer
Layer from a table name. See
QueryLayer
for docs on the style attributesExample
Vizualize data from a table. Here we’re using the example CartoContext. To use this with your account, replace the example_context with your
CartoContext
and a table in the account you authenticate against.from cartoframes.examples import example_context from cartoframes.contrib import vector vector.vmap( [vector.Layer( 'nat', color='ramp(globalEqIntervals($hr90, 7), sunset)', strokeWidth=0), ], example_context)
-
class
cartoframes.contrib.vector.
LocalLayer
(dataframe, color=None, size=None, time=None, strokeColor=None, strokeWidth=None, interactivity=None)¶ Bases:
cartoframes.contrib.vector.QueryLayer
Create a layer from a GeoDataFrame
TODO: add support for filepath to a geojson file, json/dict, or string
See
QueryLayer
for the full styling documentation.Example
In this example, we grab data from the cartoframes example account using read_mcdonals_nyc to get McDonald’s locations within New York City. Using the decode_geom=True argument, we decode the geometries into a form that works with GeoPandas. Finally, we pass the GeoDataFrame into
LocalLayer
to visualize.import geopandas as gpd from cartoframes.examples import read_mcdonalds_nyc, example_context from cartoframes.contrib import vector gdf = gpd.GeoDataFrame(read_mcdonalds_nyc(decode_geom=True)) vector.vmap([vector.LocalLayer(gdf), ], context=example_context)
-
class
cartoframes.contrib.vector.
QueryLayer
(query, color=None, size=None, time=None, strokeColor=None, strokeWidth=None, interactivity=None)¶ Bases:
object
CARTO VL layer based on an arbitrary query against user database
Parameters: - query (str) – Query against user database. This query must have the the following columns included to successfully have a map rendered: the_geom, the_geom_webmercator, and cartodb_id. If columns are used in styling, they must be included in this query as well.
- color (str, optional) – CARTO VL color styling for this layer. Valid inputs are simple web color names and hex values. For more advanced styling, see the CARTO VL guide on styling for more information: https://carto.com/developers/carto-vl/guides/styling-points/
- size (float or str, optional) – CARTO VL width styling for this layer if
points or lines (which are not yet implemented). Valid inputs are
positive numbers or text expressions involving variables. To remain
cosistent with cartoframes’ raster-based
Layer
API, size is used here in place of width, which is the CARTO VL variable name for controlling the width of a point or line. Default size is 7 pixels wide. - time (str, optional) – Time expression to animate data. This is an alias for the CARTO VL filter style attribute. Default is no animation.
- strokeColor (str, optional) – Defines the stroke color of polygons. Default is white.
- strokeWidth (float or str, optional) – Defines the width of the stroke in pixels. Default is 1.
- interactivity (str, list, or dict, optional) –
This option add interactivity (click or hover) to a layer. Defaults to click if one of the followring inputs are specified:
- dict: If a
dict
, this must have the key cols with its value a list of columns. Optionally add event to choosehover
orclick
. Specifying a header key/value pair adds a header to the popup that will be rendered in HTML. - list: A list of valid column names in the data used for this layer
- str: A column name in the data used in this layer
- dict: If a
Example
from cartoframes.examples import example_context from cartoframes.contrib import vector # create geometries from lng/lat columns q = ''' SELECT *, ST_Transform(the_geom, 3857) as the_geom_webmercator FROM ( SELECT CDB_LatLng(pickup_latitude, pickup_longitude) as the_geom, fare_amount, cartodb_id FROM taxi_50k ) as _w ''' vector.vmap( [vector.QueryLayer(q), ], example_context )
-
cartoframes.contrib.vector.
vmap
(layers, context, size=(800, 400))¶ CARTO VL-powered interactive map
Parameters: - layers (list of Layer-types) – List of layers. One or more of
Layer
,QueryLayer
, orLocalLayer
. - context (
CartoContext
) – ACartoContext
instance
Example
from cartoframes.contrib import vector from cartoframes import CartoContext cc = CartoContext( base_url='https://your_user_name.carto.com', api_key='your api key' ) vector.vmap([vector.Layer('table in your account'), ], cc)
- layers (list of Layer-types) – List of layers. One or more of