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 attributes

Example

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 choose hover or click. 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

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:

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)