cartoframes.viz package

Module contents

cartoframes.viz.basemaps

alias of cartoframes.viz.basemaps.Basemaps

class cartoframes.viz.Map(layers=None, basemap='DarkMatter', bounds=None, size=None, viewport=None, default_legend=False, show_info=None, **kwargs)

Bases: object

Parameters:
  • layers (list of Layer-types) – List of layers. One or more of Layer.
  • 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.
  • bounds (dict or list) – a dict with east,`north`,`west`,`south` properties, or a list of floats in the following order: [west, south, east, north]. If not provided the bounds will be automatically calculated to fit all features.
  • size (tuple of int) – a (width, height) pair for the size of the map. Default is (1024, 632)
  • show_info (bool, optional) – Whether to display center and zoom information in the map or not. It is False by default.

Example

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

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

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

CARTO basemap style.

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

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

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

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

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

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

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

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

Color basemap style.

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

set_default_context(
    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)'
)

Custom bounds.

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

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

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

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

Show map center and zoom values

from cartoframes.auth import Context, set_default_context
from cartoframes.viz import Map, Layer

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

Map(Layer('table in your account'), show_info=True)
publish()
class cartoframes.viz.Layer(source, style=None, popup=None, legend=None, context=None)

Bases: object

:param source (str, Dataset,: Source): The source data. :param style (str, dict, Style,: optional): The style of the visualization: `CARTO VL styling

Parameters:
  • popup (dict, 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 <https://carto.com/developers/carto-vl/reference/#cartoexpressions>.
  • legend (dict, 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”.
  • context (Context) – A Context instance. This is only used for the simplified Source API. When a Source is pased as source, this context is simply ignored. If not provided the context will be automatically obtained from the default context.

Example

from cartoframes.auth import set_default_context
from cartoframes.viz import Layer

set_default_context(
    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',
        'prop': 'color',
        'title': 'Population'
    }
)

Setting the context.

from cartoframes.auth import Context
from cartoframes.viz import Layer

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

Layer(
    'populated_places',
    'color: "red"',
    context=context
)
class cartoframes.viz.Source(data, context=None, bounds=None, schema=None)

Bases: object

:param data (str, GeoFrame,: Dataset ): a table name, SQL query
,GeoJSON file, GeoFrame object or Dataset object.
Parameters:
  • context (Context) – A Conext instance. If not provided the context will be automatically obtained from the default context.
  • bounds (dict or list) – a dict with east,`north`,`west`,`south` properties, or a list of floats in the following order: [west, south, east, north]. If not provided the bounds will be automatically calculated to fit all features.

Example

Table name.

from cartoframes.auth import set_default_context
from cartoframes.viz import Source

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

Source('table_name')

SQL query.

from cartoframes.auth import set_default_context
from cartoframes.viz import Source

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

Source('SELECT * FROM table_name')

GeoJSON file.

from cartoframes.auth import set_default_context
from cartoframes.viz import Source

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

Source('path/to/file.geojson')

Dataset object.

from cartoframes.auth import set_default_context
from cartoframes.viz import Source
from cartoframes import Dataset

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

ds = Dataset.from_table('table_name')

Source(ds)

Setting the context.

from cartoframes.auth import Context
from cartoframes.viz import Source

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

Source('table_name', context)

Setting the bounds.

from cartoframes.auth import set_default_context
from cartoframes.viz import Source

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

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

Source('table_name', bounds=bounds)
class cartoframes.viz.Style(data=None)

Bases: object

Parameters:data (str, dict) – The style for the layer. It can be a dictionary or a viz string. More info at CARTO VL styling <https://carto.com/developers/carto-vl/guides/style-with-expressions/>

Example

String API.

Dict API.

compute_viz(geom_type, variables={})
class cartoframes.viz.Popup(data=None)

Bases: object

Parameters:data (dict) – The popup definition for a layer. It contains the information to show a popup on ‘click’ and ‘hover’ events with the attributes provided in the definition using the CARTO VL expressions syntax <https://carto.com/developers/carto-vl/reference/#cartoexpressions>.

Example

Show columns.

Show expressions.

Show titles.

get_interactivity()
get_variables()
class cartoframes.viz.Legend(data=None)

Bases: object

Parameters:data (dict) – 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”.

Example:

get_info(geom_type)