contrib¶

contrib is an experimental library of modules in the contrib directory. These modules allow us to release new features with the expectation that they will change quickly, but give users quicker access to the bleeding edge. Most features in contrib will eventually be merged into the cartoframes core.

vector maps¶

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

Here is an example using the example CartoContext from the Examples class.

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.BaseMaps¶

Supported CARTO vector basemaps. Read more about the styles in the CARTO Basemaps repository.

darkmatter¶

CARTO’s “Dark Matter” style basemap

Type:	str

positron¶

CARTO’s “Positron” style basemap

Type:	str

voyager¶

CARTO’s “Voyager” style basemap

Type:	str

Example

Create an embedded map using CARTO’s Positron style with no data layers

from cartoframes.contrib import vector
from cartoframes import CartoContext
cc = CartoContext()
vector.vmap([], context=cc, basemap=vector.BaseMaps.positron)

class cartoframes.contrib.vector.Layer(table_name, color=None, size=None, time=None, strokeColor=None, strokeWidth=None, interactivity=None, legend=None)¶

Layer from a table name. See vector.QueryLayer for docs on the style attributes.

Example

Visualize 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, legend=None)¶

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, legend=None)¶

CARTO VL layer based on an arbitrary query against user database

Parameters:

query (str) – Query against user database. This query must have 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 consistent 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 adds interactivity (click or hover) to a layer. Defaults to click if one of the following 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,
    interactivity={
        'cols': ['fare_amount', ],
        'event': 'hover'
    }
)

cartoframes.contrib.vector.vmap(*args, **kwargs)¶

CARTO VL-powered interactive map

Parameters:

layers (list of Layer-types) – List of layers. One or more of Layer, QueryLayer, or LocalLayer.
context (CartoContext) – A CartoContext instance
basemap (str) –
- if a str, name of a CARTO vector basemap. One of positron, voyager, or darkmatter from the BaseMaps class
- if a dict, Mapbox or other style as the value of the style key. If a Mapbox style, the access token is the value of the token key.

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)

CARTO basemap style.

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'), ],
    context=cc,
    basemap=vector.BaseMaps.darkmatter
)

Custom basemap style. Here we use the Mapbox streets style, which requires an access token.

from cartoframes.contrib import vector
from cartoframes import CartoContext
cc = CartoContext(
    base_url='https://<username>.carto.com',
    api_key='your api key'
)
vector.vmap(
    [vector.Layer('table in your account'), ],
    context=cc,
    basemap={
        'style': 'mapbox://styles/mapbox/streets-v9',
        'token: '<your mapbox token>'
    }
)