Map Workflows

With CARTOframes you can create maps based on vector data using the CARTO VL library. All maps can be exported as files or displayed interactively in a Jupyter notebook.

Interactive CARTO VL Maps

Interactive CARTO VL maps are the recommended way to create maps in cartoframes. These maps have a powerful API which exposes many features of the CARTO VL mapping library, including automatic legend generation. With the use of the helper functions, maps are created with great cartographic defaults out-of-the-box and include legends and popups automatically.

class cartoframes.viz.Map(layers=None, basemap='Positron', bounds=None, size=None, viewport=None, default_legend=False, show_info=None, theme=None, title=None, description=None, is_static=None, **kwargs)
Parameters:
  • layers (list of Layer) – List of layers. Zero or more of Layer.
  • basemap (str, optional) –
    • if a str, name of a CARTO vector basemap. One of positron, voyager, or darkmatter from the BaseMaps class, or a hex value, rgb string, or other color expression from CARTO VL.
    • 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.
  • bounds (dict or list, optional) – a dict with west, south, east, north keys, or an array of floats in the following structure: [[west, south], [east, north]]. If not provided the bounds will be automatically calculated to fit all features.
  • size (tuple, optional) – a (width, height) pair for the size of the map. Default is (1024, 632).
  • viewport (dict, optional) – Properties for display of the map viewport. Keys can be bearing or pitch.
  • default_legend (bool, optional) – Default False. If True, it displays the map title. Therefore, it needs the title value to be defined.
  • show_info (bool, optional) – Whether to display center and zoom information in the map or not. It is False by default.
  • is_static (bool, optional) – Default False. If True, instead of showing and interactive map, a png image will be displayed.
  • theme (string, optional) – Use a different UI theme
  • title (string, optional) – Title to label the map
  • description (string, optional) – Text that describes the map and will be displayed in the default legend after the title.

Examples

Basic usage.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

Map(Layer('table in your account'))

Display more than one layer on a map.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

Map(layers=[
    Layer('table1'),
    Layer('table2')
])

Change the CARTO basemap style.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer, basemaps

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

Map(
    Layer('table in your account'),
    basemaps.darkmatter
)

Choose a custom basemap style. Here we use the Mapbox streets style, which requires an access token.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your CARTO API key'
)

basemap = {
    'style': 'mapbox://styles/mapbox/streets-v9',
    'token': 'your Mapbox token'
}

Map(
    Layer('table in your account'),
    basemap
)

Remove basemap and show a custom color.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

Map(
    Layer('table in your account'),
    basemap='yellow'  # None, False, 'white', 'rgb(255, 255, 0)'
)

Set custom bounds.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

bounds = {
    'west': -10,
    'east': 10,
    'north': -10,
    'south': 10
}

# or bounds = [[-10, 10], [10, -10]]

Map(
    Layer('table in your account'),
    bounds=bounds
)

Show the map center and zoom value on the map (lower left-hand corner).

from cartoframes.auth import Credentials, set_default_credentials
from cartoframes.viz import Map, Layer

credentials = Credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)
set_default_credentials(credentials)

Map(Layer('table in your account'), show_info=True)
publish(name, maps_api_key='default_public', credentials=None, password=None)

Publish the map visualization as a CARTO custom visualization (aka Kuviz).

Parameters:
  • name (str) – The Kuviz name on CARTO
  • maps_api_key (str, optional) – A Regular API key with permissions to Maps API and datasets used by the map
  • credentials (Credentials, optional) – A Credentials instance. If not provided, the credentials will be automatically obtained from the default credentials if available.
  • password (str, optional) – setting it your Kuviz will be protected by password. When someone will try to show the Kuviz, the password will be requested

Example

Publishing the map visualization

from cartoframes.viz import Map, Layer

tmap = Map(Layer('tablename'))
tmap.publish('Custom Map Title')
sync_data(table_name, credentials=None)

Synchronize datasets used by the map with CARTO.

Parameters:
  • table_name (str) – Desired table name for the dataset on CARTO. If name does not conform to SQL naming conventions, it will be ‘normalized’ (e.g., all lower case, adding _ in place of spaces and other special characters.
  • credentials (Credentials, optional) – A Credentials instance. If not provided, the credentials will be automatically obtained from the default credentials if available.
delete_publication()

Delete the published map Kuviz.

update_publication(name, password, maps_api_key='default_public')

Update the published map Kuviz.

Parameters:
  • name (str) – The Kuviz name on CARTO
  • password (str) – setting it your Kuviz will be protected by password and using None the Kuviz will be public
  • maps_api_key (str, optional) – A Regular API key with permissions to Maps API and datasets used by the map
static all_publications(credentials=None)

Get all map Kuviz published by the current user.

Parameters:credentials (Credentials, optional) – A Credentials instance. If not provided, the credentials will be automatically obtained from the default credentials if available.

Helper Functions

Map helper functions bootstrap the process of creating common types of maps. These functions save time by giving great out-of-the-box cartography, legends, and popups. The layer can be further customized using optional overrides.

cartoframes.viz.helpers.color_bins_layer(source, value, title='', method='quantiles', bins=5, breaks=None, palette=None, size=None, opacity=None, stroke_color=None, stroke_width=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a classed color map.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of legend.
  • method (str, optional) – Classification method of data: “quantiles”, “equal”, “stdev”. Default is “quantiles”.
  • bins (int, optional) – Number of size classes (bins) for map. Default is 5.
  • breaks (int[], optional) – Assign manual class break values.
  • palette (str, optional) – Palette that can be a named cartocolor palette or other valid CARTO VL palette expression. Default is purpor.
  • size (int, optional) – Size of point or line features.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data: “True” or “False”. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.color_category_layer(source, value, title='', top=11, cat=None, palette=None, size=None, opacity=None, stroke_color=None, stroke_width=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a category color map.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of legend.
  • top (int, optional) – Number of category for map. Default is 11. Values can range from 1 to 16.
  • cat (str, optional) – Category list. Must be a valid CARTO VL category list.
  • palette (str, optional) – Palette that can be a named CARTOColor palette or other valid CARTO VL palette expression. Default is bold.
  • size (int, optional) – Size of point or line features.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.color_continuous_layer(source, value, title='', palette=None, size=None, opacity=None, stroke_color=None, stroke_width=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a continuous color map.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of legend
  • palette (str, optional) – Palette that can be a named cartocolor palette or other valid CARTO VL palette expression. Default is bluyl.
  • size (int, optional) – Size of point or line features.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.size_bins_layer(source, value, title='', method='quantiles', bins=5, breaks=None, size=None, color=None, opacity=None, stroke_width=None, stroke_color=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a size symbol map with classification method/buckets.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of legend.
  • method (str, optional) – Classification method of data: “quantiles”, “equal”, “stdev”. Default is “quantiles”.
  • bins (int, optional) – Number of size classes (bins) for map. Default is 5.
  • breaks (int[], optional) – Assign manual class break values.
  • size (int, optiona) – Min/max size array in CARTO VL syntax. Default is ‘[2, 14]’ for point geometries and ‘[1, 10]’ for lines.
  • color (str, optional) – Hex value, rgb expression, or other valid CARTO VL color. Default is ‘#EE5D5A’ for point geometries and ‘#4CC8A3’ for lines.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.size_category_layer(source, value, title='', top=5, cat=None, size=None, color=None, opacity=None, stroke_width=None, stroke_color=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a size category layer.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of legend.
  • top (int, optional) – Number of size categories for layer. Default is 5. Valid values range from 1 to 16.
  • cat (str, optional) – Category list. Must be a valid CARTO VL category list.
  • size (str, optiona) – Min/max size array in CARTO VL syntax. Default is ‘[2, 20]’ for point geometries and ‘[1, 10]’ for lines.
  • color (str, optional) – Hex value, rgb expression, or other valid CARTO VL color. Default is ‘#F46D43’ for point geometries and ‘#4CC8A3’ for lines.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.size_continuous_layer(source, value, title='', size=None, color=None, opacity=None, stroke_width=None, stroke_color=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a size symbol map with continuous size scaled by value.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of legend.
  • size (str, optiona) – Min/max size array in CARTO VL syntax. Default is ‘[2, 40]’ for point geometries and ‘[1, 10]’ for lines.
  • color (str, optional) – Hex value, rgb expression, or other valid CARTO VL color. Defaults is ‘#FFB927’ for point geometries and ‘#4CC8A3’ for lines.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.cluster_size_layer(source, value=None, operation='count', resolution=32, title='', color=None, opacity=None, stroke_width=None, stroke_color=None, description='', footer='', legend=True, popup=True, widget=False, animate=None)

Helper function for quickly creating a cluster map with continuously sized points.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Numeric column to aggregate.
  • operation (str) – Cluster operation, defaults to ‘count’. Other options available are ‘avg’, ‘min’, ‘max’, and ‘sum’.
  • resolution (int) – Resolution of aggregation grid cell. Set to 32 by default.
  • title (str, optional) – Title of legend and hover.
  • color (str, optional) – Hex value, rgb expression, or other valid CARTO VL color. Defaults is ‘#FFB927’ for point geometries.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • description (str, optional) – Description text legend placed under legend title.
  • footer (str, optional) – Footer text placed under legend items.
  • legend (bool, optional) – Display map legend: “True” or “False”. Set to “True” by default.
  • popup (bool, optional) – Display popups on hover and click: “True” or “False”. Set to “True” by default.
  • widget (bool, optional) – Display a widget for mapped data. Set to “False” by default.
  • animate (str, optional) – Animate features by date/time or other numeric field.
Returns:

Layer styled by value. Includes a legend, popup and widget on value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.animation_layer(source, value, title='', duration=None, fade=None, size=None, color=None, opacity=None, stroke_color=None, stroke_width=None, widget_type='time-series', description='')

Helper function for quickly creating an animated map.

Parameters:
  • source (Dataset or str) – Dataset or text representing a table or query associated with user account.
  • value (str) – Column to symbolize by.
  • title (str, optional) – Title of widget.
  • color (str, optional) – Hex value, rgb expression, or other valid CARTO VL color. Default is ‘#EE5D5A’ for point geometries, ‘#4CC8A3’ for lines and #826DBA for polygons.
  • size (int, optional) – Size of point or line features.
  • opacity (int, optional) – Opacity value for point color and line features. Default is ‘0.8’.
  • stroke_width (int, optional) – Size of the stroke on point features.
  • stroke_color (str, optional) – Color of the stroke on point features. Default is ‘#222’.
  • widget_type (str, optional) – Type of animation widget: “animation” or “time-series”. The default is “time-series”.
  • description (str, optional) – Description text placed under the widget title.
  • fade (string, optional) – Animation fade with the format: “(fade in, fade out)”. Default is (1, 1).
Returns:

Layer styled by value. Includes Widget value.

Return type:

cartoframes.viz.Layer

Widget Functions

Widget helpers to generate widgets faster.

class cartoframes.viz.widgets.Widget(f_arg, **kwargs)
Parameters:
  • type – The widget type. It can be ‘default’, ‘formula’, time-series’, ‘animation’, ‘category’, ‘histogram’.
  • value – A constant value or a CARTO VL expression.
  • title (optional) – Widget title.
  • description (optional) – Description shown below the title.
  • footer (optional) – Footer of widget. This is often used to attribute data sources.

Example:

from cartoframes.viz import Widget

Widget('formula', value='viewportSum($amount)', title='Widget Title',
       'description': '[description]', 'footer': '[footer]')
class cartoframes.viz.widgets.WidgetList(widgets=None)
Parameters:widgets (dict, list, Widget) – The list of widgets for a layer.

Example

cartoframes.viz.widgets.animation_widget(**kwargs)

Helper function for quickly creating an animated widget.

The animation widget includes an animation status bar as well as controls to play or pause animated data. The filter property of your map’s style, applied to either a date or numeric field, drives both the animation and the widget. Only one animation can be controlled per layer. To learn more about creating animations visit:

Parameters:
  • title (str, optional) – Title of widget.
  • description (str, optional) – Description text widget placed under widget title.
  • footer (str, optional) – Footer text placed on the widget bottom
Returns:

Widget with type=’animation’

Return type:

cartoframes.viz.Widget

Example

from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import animation_widget

Map(
    Layer(
        'seattle_collisions',
        'filter: animation($incdate, 20, fade(0.5,0.5))',
        widgets=[
            animation_widget(
                title='Collision Date',
                description= 'Play, pause, or select the range of the animation'
            )]
    )
)
cartoframes.viz.widgets.category_widget(value, **kwargs)

Helper function for quickly creating a category widget.

Parameters:
  • value (str) – Column name of the category value
  • title (str, optional) – Title of widget.
  • description (str, optional) – Description text widget placed under widget title.
  • footer (str, optional) – Footer text placed on the widget bottom
  • read_only (boolean, optional) – Interactively filter a category by selecting it in the widget. Set to “False” by default.
Returns:

Widget with type=’category’

Return type:

cartoframes.viz.Widget

Example

from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import category_widget

Map(
    Layer(
        'seattle_collisions',
        widgets=[
            category_widget(
                'collisiontype',
                title='Type of Collision',
                description='Select a category to filter',
            )
        ]
    )
)
cartoframes.viz.widgets.default_widget(**kwargs)

Helper function for quickly creating a default widget.

The default widget is a general purpose widget that can be used to provide additional information about your map.

Parameters:
  • title (str, optional) – Title of widget.
  • description (str, optional) – Description text widget placed under widget title.
  • footer (str, optional) – Footer text placed on the widget bottom
Returns:

Widget with type=’default’

Return type:

cartoframes.viz.Widget

Example

from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import default_widget

Map(
    Layer(
        'seattle_collisions',
        widgets=[
            default_widget(
                title='Road Collisions in 2018',
                description='An analysis of collisions in Seattle, WA',
                footer='Data source: City of Seattle'
            )]
    )
)
cartoframes.viz.widgets.formula_widget(value, operation=None, **kwargs)

Helper function for quickly creating a formula widget.

Formula widgets calculate aggregated values (‘Avg’, ‘Max’, ‘Min’, ‘Sum’) from numeric columns or counts of features (‘Count’) in a dataset.

A formula widget’s aggregations can be calculated on ‘global’ or ‘viewport’ based values. If you want the values in a formula widget to update on zoom and/or pan, use viewport based aggregations.

Parameters:
  • value (str) – Column name of the numeric value
  • operation (str) – attribute for widget’s aggregated value (‘count’, ‘avg’, ‘max’, ‘min’, ‘sum’)
  • title (str, optional) – Title of widget.
  • description (str, optional) – Description text widget placed under widget title.
  • footer (str, optional) – Footer text placed on the widget bottom
  • is_global (boolean, optional) – Account for calculations based on the entire dataset (‘global’) vs. the default of ‘viewport’ features.
Returns:

Widget with type=’formula’

Return type:

cartoframes.viz.Widget

Example

from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import formula_widget

Map(
    Layer(
        'seattle_collisions',
        widgets=[
            formula_widget(
                'count',
                title='Number of Collisions',
                description='Zoom and/or pan the map to update count',
                footer='collisions in this view'
            )
        ]
    )
)
from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import formula_widget

Map(
    Layer(
        'seattle_collisions',
        widgets=[
            formula_widget(
                'pedcount',
                'sum',
                is_global=True,
                title='Total Number of Pedestrians',
                description='involved over all collisions',
                footer='pedestrians'
            )
        ]
    )
)
cartoframes.viz.widgets.histogram_widget(value, **kwargs)

Helper function for quickly creating a histogram widget.

Histogram widgets display the distribution of a numeric attribute, in buckets, to group ranges of values in your data. By default, you can hover over each bar to see each bucket’s values and count, and also filter your map’s data within a given range

Parameters:
  • value (str) – Column name of the numeric or date value
  • title (str, optional) – Title of widget.
  • description (str, optional) – Description text widget placed under widget title.
  • footer (str, optional) – Footer text placed on the widget bottom
  • buckets (number, optional) – Number of histogram buckets. Set to 20 by default.
  • read_only (boolean, optional) – Interactively filter a range of numeric values by selecting them in the widget. Set to “False” by default.
Returns:

Widget with type=’histogram’

Return type:

cartoframes.viz.Widget

Example

from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import histogram_widget

Map(
    Layer(
        'seattle_collisions',
        widgets=[
            histogram_widget(
                'vehcount',
                title='Number of Vehicles Involved',
                description='Select a range of values to filter',
                buckets=9
            )
        ]
    )
)
cartoframes.viz.widgets.time_series_widget(value, **kwargs)

Helper function for quickly creating a time series widget.

The time series widget enables you to display animated data (by aggregation) over a specified date or numeric field. Time series widgets provide a status bar of the animation, controls to play or pause, and the ability to filter on a range of values.

Parameters:
  • value (str) – Column name of the numeric or date value
  • title (str, optional) – Title of widget.
  • description (str, optional) – Description text widget placed under widget title.
  • footer (str, optional) – Footer text placed on the widget bottom
  • buckets (number, optional) – Number of histogram buckets. Set to 20 by default.
  • read_only (boolean, optional) – Interactively filter a range of numeric values by selecting them in the widget. Set to “False” by default.
Returns:

Widget with type=’time-series’

Return type:

cartoframes.viz.Widget

Example

from cartoframes.viz import Map, Layer
from cartoframes.viz.widgets import time_series_widget

Map(
    Layer(
        'seattle_collisions',
        'filter: animation($incdate, 20, fade(0.5,0.5))',
        widgets=[
            time_series_widget(
                value='incdate',
                title='Number of Collisions by Date',
                description= 'Play, pause, or select a range for the animation',
                buckets=10
            )]
    )
)

Layers

class cartoframes.viz.Layer(source, style=None, popup=None, legend=None, widgets=None, credentials=None, bounds=None)

Layer to display data on a map. This class can be used as one or more layers in Map or on its own in a Jupyter notebook to get a preview of a Layer.

Parameters:
  • source (str, Dataset, or pandas.DataFrame) – The source data.
  • style (str, dict, or Style, optional) – The style of the visualization: CARTO VL styling.
  • popup (dict or Popup, optional) – This option adds interactivity (click and hover) to a layer to show popups. The columns to be shown must be added in a list format for each event. It must be written using CARTO VL expressions syntax. See Popup for more information.
  • legend (dict or Legend, optional) – The legend definition for a layer. It contains the information to show a legend “type” (color-category, color-bins, color-continuous), “prop” (color) and also text information: “title”, “description” and “footer”. See Legend for more information.
  • widgets (dict, list, or WidgetList, optional) – Widget or list of widgets for a layer. It contains the information to display different widget types on the top right of the map. See WidgetList for more information.
  • credentials (Credentials) – A Credentials instance. This is only used for the simplified Source API. When a Source is pased as source, these credentials is simply ignored. If not provided the credentials will be automatically obtained from the default credentials.
  • bounds (dict or list, optional) – a dict with west, south, east, north keys, or an array of floats in the following structure: [[west, south], [east, north]]. If not provided the bounds will be automatically calculated to fit all features.

Example

Create a layer with a custom popup, legend, and widget.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Layer

set_default_credentials(
    base_url='https://cartovl.carto.com',
    api_key='default_public'
)

Layer(
    "SELECT * FROM populated_places WHERE adm0name = 'Spain'",
    'color: ramp(globalQuantiles($pop_max, 5), reverse(purpor))',
    popup={
        'hover': '$name',
        'click': ['$name', '$pop_max', '$pop_min']
    },
    legend={
        'type': 'color-category',
        'title': 'Population'
    },
    widgets=[{
        'type': 'formula',
        'title': 'Avg $pop_max',
        'value': 'viewportAvg($pop_max)'
    }]
)

Create a layer specifically tied to a Credentials and display it on a map.

from cartoframes.auth import Credentials
from cartoframes.viz import Layer, Map

credentials = Credentials(
    base_url='https://cartovl.carto.com',
    api_key='default_public'
)

pop_layer = Layer(
    'populated_places',
    'color: red',
    credentials=credentials
)
Map(pop_layer)

Preview a layer in a Jupyter notebook. Note: if in a Jupyter notebook, it is not required to explicitly add a Layer to a Map if only visualizing data as a single layer.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Layer, Map

set_default_credentials('https://cartoframes.carto.com')

pop_layer = Layer(
    'brooklyn_poverty',
    'color: ramp($poverty_per_pop, sunset)',
    legend={
        'type': 'color-continuous',
        'title': 'Poverty per pop'
    }
)
pop_layer