CARTOframes

A Python package for integrating CARTO maps, analysis, and data services into data science workflows.

This version includes breaking changes, check the CHANGELOG for more information

CARTOframes API Reference

Introduction

The CARTOframes API is organized in three parts: auth, data, and viz.

Authentication

It is possible to use CARTOframes without having a CARTO account. However, to have access to data enrichment or to discover useful datasets, being a CARTO user offers many advantages. This module is the responsible for connecting the user with its CARTO account through given user credentials.

Manage Data

From discovering and enriching data to applying data analyisis and geocoding methods, CARTOframes API is built with the purpose of managing data without leaving the context of your notebook.

Visualize Data

The viz API is designed to create useful, beautiful and straight forward visualizations. It is at the same time predefined and flexible, in order to give advanced users the possibility of building specific visualizations, but also to offer multiple built-in methods to work faster with a few lines of code.

Auth

Auth namespace contains the class to manage authentication: Credentials. It also includes the utility functions cartoframes.auth.set_default_credentials() and cartoframes.auth.get_default_credentials().

class cartoframes.auth.Credentials(username=None, api_key='default_public', base_url=None, session=None)

Bases: object

Credentials class for managing and storing user CARTO credentials. The arguments are listed in order of precedence: Credentials instances are first, key and base_url/username are taken next, and config_file (if given) is taken last. The config file is cartocreds.json by default. If no arguments are passed, then there will be an attempt to retrieve credentials from a previously saved session. One of the above scenarios needs to be met to successfully instantiate a Credentials object.

Parameters:
  • api_key (str, optional) – API key of user’s CARTO account. If the dataset is public, it can be set to ‘default_public’.
  • username (str, optional) – Username of CARTO account
  • base_url (str, optional) – Base URL used for API calls. This is usually of the form https://johnsmith.carto.com/ for user johnsmith. On premises installations (and others) have a different URL pattern.
  • session (requests.Session, optional) – requests session. See requests documentation for more information.

Example

Setting basic credentials:

from cartoframes.auth import Credentials
credentials = Credentials(username='johnsmith', api_key='abcdefg')
api_key

Credentials api_key

base_url

Credentials base_url

classmethod delete(config_file=None)

Deletes the credentials file specified in config_file. If no file is specified, it deletes the default user credential file (cartocreds.json)

Parameters:config_file (str) – Path to configuration file. Defaults to delete the user default location if None.

Tip

To see if there is a default user credential file stored, do the following:

>>> credentials = Credentials.from_file()
>>> print(credentials)
Credentials(username='johnsmith', api_key='abcdefg', base_url='https://johnsmith.carto.com/')
classmethod from_credentials(credentials)

Retrives credentials from another Credentials object

classmethod from_file(config_file=None, session=None)

Retrives credentials from a file. Defaults to the user config directory

get_do_token()

Returns the Data Observatory v2 token

save(config_file=None)

Saves current user credentials to user directory.

Parameters:config_file (str, optional) – Location where credentials are to be stored. If no argument is provided, it will be send to the default location.

Example

from cartoframes.auth import Credentials
credentials = Credentials(username='johnsmith', api_key='abcdefg')
credentials.save()  # save to default location
from cartoframes.auth import Credentials
credentials = Credentials(username='johnsmith', api_key='abcdefg')
credentials.save('path/to/credentials/file.json')
session

Credentials session

username

Credentials username

cartoframes.auth.set_default_credentials(first=None, second=None, credentials=None, filepath=None, username=None, base_url=None, api_key=None, session=None)

Set default credentials for all operations that require authentication against a CARTO account. CARTOframes methods cartoframes.viz.Layer (and helper layers in cartoframes.viz.helpers), cartoframes.data.clients.SQLClient, and others.

Parameters:
  • credentials (Credentials, optional) – A Credentials instance can be used in place of a username | base_url/api_key combination.
  • base_url (str, optional) – Base URL of CARTO user account. Cloud-based accounts should use the form https://{username}.carto.com (e.g., https://johnsmith.carto.com for user johnsmith) whether on a personal or multi-user account. On-premises installation users should ask their admin.
  • api_key (str, optional) – CARTO API key. Depending on the application, this can be a project API key or the account master API key.
  • username (str, optional) – CARTO user name of the account.
  • filepath (str, optional) – Location where credentials are stored as a JSON file.
  • session (requests.Session, optional) – requests session. See requests documentation for more information.

Note

The recommended way to authenticate in CARTOframes is to read user credentials from a JSON file that is structured like this:

{
    "username": "your user name",
    "api_key": "your api key",
    "base_url": "https://your_username.carto.com"
}

Note that the ``base_url`` will be different for on premises installations.

By using the cartoframes.auth.Credentials.save() method, this file will automatically be created for you in a default location depending on your operating system. A custom location can also be specified as an argument to the method.

This file can then be read in the following ways:

from cartoframes.auth import Credentials, set_default_credentials

# attempts to read file from default location if it exists
set_default_credentials()

# read credentials from specified location
set_default_credentials('./carto-project-credentials.json')

Example

Create Credentials from a username, api_key pair.

from cartoframes.auth import set_default_credentials

set_default_credentials(
    username='johnsmith',
    api_key='your api key'
)

# or

set_default_credentials(
    'johnsmith',
    'your api key'
)

Create credentials from only a username (only works with public datasets and those marked public with link). If the API key is not provided, the public API key default_public is used. With this setting, only read-only operations can occur (e.g., no publishing of maps, reading data from the Data Observatory, or creating new hosted datasets).

from cartoframes.auth import set_default_credentials
set_default_credentials('johnsmith')

From a pair base_url, api_key.

from cartoframes.auth import set_default_credentials
set_default_credentials(
    base_url='https://johnsmith.carto.com',
    api_key='your api key'
)
# or
set_default_credentials(
    'https://johnsmith.carto.com',
    'your api key'
)

From a base_url (for public datasets). The API key default_public is used by default.

from cartoframes.auth import set_default_credentials
set_default_credentials('https://johnsmith.carto.com')

From a Credentials class.

from cartoframes.auth import Credentials, set_default_credentials
credentials = Credentials(
    base_url='https://johnsmith.carto.com',
    api_key='your api key'
)
set_default_credentials(credentials)
cartoframes.auth.get_default_credentials()

Retrieve the default credentials if previously set with cartoframes.auth.set_default_credentials() in Python session.

Example

Retrieve default credentials.

from cartoframes.auth import set_default_credentials, get_default_credentials

set_default_credentials()

current_creds = get_default_credentials()
Returns:Default credentials previously set in current Python session. None will returned if default credentials were not previously set.
Return type:cartoframes.auth.Credentials

CartoDataFrame

class cartoframes.core.cartodataframe.CartoDataFrame(data, *args, **kwargs)

Bases: geopandas.geodataframe.GeoDataFrame

The CartoDataFrame class is an extension of the geopandas.GeoDataFrame class. It provides powerful cartographic visualizations, geometry detection and decoding, and read / write access to the CARTO platform.

static from_carto(*args, **kwargs)

Alternate constructor to create a CartoDataFrame from a table or SQL query in CARTO. It is needed to set up the cartoframes.auth.Credentials. Equivalent to read_carto.

Examples

Using a table name:

from cartoframes import CartoDataFrame
from cartoframes.auth import set_default_credentials

set_default_credentials('your_user_name', 'your api key')

cdf = CartoDataFrame.from_carto('table_name')

Using a SQL query:

from cartoframes import CartoDataFrame
from cartoframes.auth import set_default_credentials

set_default_credentials('your_user_name', 'your api key')

cdf = CartoDataFrame.from_carto('SELECT * FROM table_name WHERE value > 100')
classmethod from_file(filename, **kwargs)

Alternate constructor to create a CartoDataFrame from a file. Extends from the GeoDataFrame.from_file method.

Examples

from cartoframes import CartoDataFrame

cdf = CartoDataFrame.from_file('nybb.shp')
classmethod from_features(features, **kwargs)

Alternate constructor to create a CartoDataframe from GeoJSON features. Extends from the GeoDataFrame.from_features method.

Examples

from cartoframes import CartoDataFrame

cdf = CartoDataFrame.from_features('nybb.shp')
to_carto(*args, **kwargs)

Upload a CartoDataFrame to CARTO. It is needed to set up the cartoframes.auth.Credentials. Equivalent to to_carto.

Examples

viz(*args, **kwargs)

Creates a Map visualization

has_geometry()
set_geometry(col, drop=False, inplace=False, crs=None)
set_geometry_from_xy(x, y, drop=False, inplace=False, crs=None)
astype(*args, **kwargs)
merge(*args, **kwargs)
dissolve(*args, **kwargs)
explode(*args, **kwargs)

Utils

Functions to interact with the CARTO platform

cartoframes.io.carto.read_carto(source, credentials=None, limit=None, retry_times=3, schema=None, index_col=None, decode_geom=True)

Read a table or a SQL query from the CARTO account.

Parameters:
  • source (str) – table name or SQL query.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • limit (int, optional) – The number of rows to download. Default is to download all rows.
  • retry_times (int, optional) – Number of time to retry the download in case it fails. Default is 3.
  • schema (str, optional) – prefix of the table. By default, it gets the current_schema() using the credentials.
  • index_col (str, optional) – name of the column to be loaded as index. It can be used also to set the index name.
  • decode_geom (bool, optional) – convert the “the_geom” column into a valid geometry column.
Returns:

CartoDataFrame

cartoframes.io.carto.to_carto(dataframe, table_name, credentials=None, if_exists='fail', geom_col=None, index=False, index_label=None, log_enabled=True, force_cartodbfy=False)

Upload a Dataframe to CARTO.

Parameters:
  • dataframe (DataFrame, GeoDataFrame, CartoDataFrame) – data to be uploaded.
  • table_name (str) – name of the table to upload the data.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • if_exists (str, optional) – ‘fail’, ‘replace’, ‘append’. Default is ‘fail’.
  • geom_col (str, optional) – name of the geometry column of the dataframe.
  • index (bool, optional) – write the index in the table. Default is False.
  • index_label (str, optional) – name of the index column in the table. By default it uses the name of the index from the dataframe.
cartoframes.io.carto.has_table(table_name, credentials=None, schema=None)

Check if the table exists in the CARTO account.

Parameters:
  • table_name (str) – name of the table.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • schema (str, optional) – prefix of the table. By default, it gets the current_schema() using the credentials.
cartoframes.io.carto.delete_table(table_name, credentials=None, log_enabled=True)

Delete the table from the CARTO account.

Parameters:
  • table_name (str) – name of the table.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
cartoframes.io.carto.describe_table(table_name, credentials=None, schema=None)

Describe the table in the CARTO account.

Parameters:
  • table_name (str) – name of the table.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • schema (str, optional) – prefix of the table. By default, it gets the current_schema() using the credentials.
Returns:

A dict with the privacy, num_rows and geom_type of the table.

Raises:

ValueError – If the table name is not a string.

cartoframes.io.carto.update_table(table_name, credentials=None, new_table_name=None, privacy=None, log_enabled=True)

Update the table information in the CARTO account.

Parameters:
  • table_name (str) – name of the table.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • new_table_name (str, optional) – new name for the table.
  • privacy (str, optional) – privacy of the table: ‘private’, ‘public’, ‘link’.
Raises:
  • ValueError – If the table name is not a string.
  • ValueError – If the privacy name is not ‘private’, ‘public’, or ‘link’.
cartoframes.io.carto.copy_table(table_name, new_table_name, credentials=None, if_exists='fail', log_enabled=True)

Copy a table into a new table in the CARTO account.

Parameters:
  • table_name (str) – name of the original table.
  • new_table_name (str, optional) – name for the new table.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • if_exists (str, optional) – ‘fail’, ‘replace’. Default is ‘fail’.
cartoframes.io.carto.create_table_from_query(query, new_table_name, credentials=None, if_exists='fail', log_enabled=True)

Create a new table from an SQL query in the CARTO account.

Parameters:
  • query (str) – SQL query
  • new_table_name (str) – name for the new table.
  • credentials (Credentials, optional) – instance of Credentials (username, api_key, etc).
  • if_exists (str, optional) – ‘fail’, ‘replace’. Default is ‘fail’.

Data Observatory

With CARTOframes it is possible to enrich your data by using our Data Observatory Catalog through the enrichment methods.

Important: The new Data Observatory 2.0 is accessible to selected CARTO Enterprise users in a private beta. We’re still open to more beta testers, so if you’re interested, please get in touch.

class cartoframes.data.observatory.Catalog

Bases: object

This class represents the Data Observatory metadata Catalog.

The catalog contains metadata that helps to discover and understand the data available in the Data Observatory for Dataset.download and Enrichment purposes.

You can get more information about the Data Observatory catalog from the CARTO website and in your CARTO user account dashboard.

The Catalog has three main purposes:
  • Explore and discover the datasets available in the repository (both public and premium datasets).
  • Subscribe to some premium datasets and manage your datasets licenses.
  • Download data and use your licensed datasets and variables to enrich your own data by means of the Enrichment functions.

The Catalog is public and you can explore it without the need of a CARTO account. Once you discover a Dataset of your interest and want to acquire a license to use it, then you’ll need a CARTO account to subscribe to it, by means of the Dataset.subscribe or Geography.subscribe functions.

The Catalog is composed of three main entities:
  • Dataset: It is the main CatalogEntity. It contains metadata of the actual data you can use to Dataset.download or for Enrichment purposes.
  • Geography: Datasets in the Data Observatory are aggregated by different geographic boundaries. The Geography entity contains metadata to understand the boundaries of a Dataset. It’s used for enrichment and you can also Geography.download the underlying data.
  • Variable: Variables contain metadata about the columns available in each dataset for enrichment. Let’s say you explore a dataset with demographic data for the whole US at the Census tract level. The variables give you information about the actual columns you have available, such as: total_population, total_males, etc. On the other hand, you use Variable instances or lists of Variable.id or Dataset.slug to enrich your own data.

Every Dataset is related to a Geography. You can have for example, demographics data at the Census tract, block groups or blocks levels.

When subscribing to a premium dataset, you should subscribe both to the Dataset.subscribe and the Geography.subscribe to be able to access both tables to enrich your own data.

The two main entities of the Catalog (Dataset and Geography) are related to other entities, that are useful for a hierarchical categorization and discovery of available data in the Data Observatory:

  • Category: Groups datasets of the same topic, for example, demographics, financial, etc.
  • Country: Groups datasets available by country
  • Provider: Gives you information about the provider of the source data

You can just list all the grouping entities. Take into account this is not the preferred way to discover the catalog metadata, since there can be thousands of entities on it:

from cartoframes.data.observatory import Category
from cartoframes.data.observatory import Country
from cartoframes.data.observatory import Provider

Category.get_all()
Country.get_all()
Provider.get_all()

Or you can get them by ID:

from cartoframes.data.observatory import Category
from cartoframes.data.observatory import Country
from cartoframes.data.observatory import Provider

Category.get('demographics')
Country.get('usa')
Provider.get('mrli')

Examples

The preferred way of discover the available datasets in the Catalog is through nested filters

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').datasets

You can include the geography as part of the nested filter like this:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').geography('ags_blockgroup_1c63771c').datasets

If a filter is already applied to a Catalog instance and you want to do a new hierarchical search, clear the previous filters with the Catalog().clear_filters() method:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').geography('ags_blockgroup_1c63771c').datasets
catalog.clear_filters()
catalog.country('esp').category('demographics').datasets

Otherwise the filters accumulate and you’ll get unexpected results.

During the discovery process, it’s useful to understand the related metadata to a given Geography or Dataset. A useful way of reading or filtering by metadata values consists on converting the entities to a pandas DataFrame:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').geography('ags_blockgroup_1c63771c').datasets.to_dataframe()

For each dataset in the Catalog, you can explore its variables, get a summary of its stats, etc.

from cartoframes.data.observatory import Catalog

catalog = Catalog()
dataset = catalog.country('usa').category('demographics').datasets.get('od_acs_13345497')
dataset.variables()

See the Catalog guides and examples in our public documentation website for more information.

categories

Get all the categories in the Catalog.

Returns:

CatalogList

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
category(category_id)

Add a category filter to the current Catalog instance.

Parameters:category_id (str) – Id value of the category to be used for filtering the Catalog.
Returns:Catalog
clear_filters()

Remove the current filters from this Catalog instance.

countries

Get all the countries with datasets available in the Catalog.

Returns:

CatalogList

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
country(country_id)

Add a country filter to the current Catalog instance.

Parameters:country_id (str) – Id value of the country to be used for filtering the Catalog.
Returns:Catalog
datasets

Get all the datasets in the Catalog.

Returns:

CatalogList

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
datasets_filter(filter_dataset)

Get all the datasets in the Catalog filtered :returns: Dataset

geographies

Get all the geographies in the Catalog.

Returns:

CatalogList

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
geography(geography_id)

Add a geography filter to the current Catalog instance.

Parameters:geography_id (str) – Id or slug value of the geography to be used for filtering the Catalog
Returns:Catalog
provider(provider_id)

Add a provider filter to the current Catalog instance

Parameters:provider_id (str) – Id value of the provider to be used for filtering the Catalog.
Returns:CatalogList
subscriptions(credentials=None)

Get all the subscriptions in the Catalog. You’ll get all the Dataset or Geography instances you have previously subscribed to.

Parameters:credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.
Returns:Subscriptions
class cartoframes.data.observatory.Category(data)

Bases: cartoframes.data.observatory.catalog.entity.CatalogEntity

This class represents a Category in the Catalog. Catalog datasets (Dataset class) are grouped by categories, so you can filter available datasets and geographies that belong (or are related) to a given Category.

Examples

List the available categories in the Catalog

from cartoframes.data.observatory import Catalog

catalog = Catalog()
categories = catalog.categories

Get a Category from the Catalog given its ID

from cartoframes.data.observatory import Catalog

catalog = Catalog()
category = catalog.categories.get('demographics')
datasets

Get the list of Dataset related to this category.

Returns:

CatalogList List of Dataset instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.

Examples

Get all the datasets Dataset available in the catalog for a Category instance

from cartoframes.data.observatory import Catalog

catalog = Catalog()
category = catalog.categories.get('demographics')
datasets = category.datasets

Same example as above but using nested filters:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
datasets = catalog.category('demographics').datasets

You can perform other operations with a CatalogList:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
datasets = catalog.category('demographics').datasets
# convert the list of datasets into a pandas DataFrame
# for further filtering and exploration
dataframe = datasets.to_dataframe()
# get a dataset by ID or slug
dataset = datasets.get(A_VALID_ID_OR_SLUG)
geographies

Get the list of Geography related to this category.

Returns:

CatalogList List of Geography instances.

Raises:
  • DiscoveryException – When no geographies found.
  • CartoException – If there’s a problem when connecting to the catalog.

Examples

Get all the geographies Dataset available in the catalog for a Category instance

from cartoframes.data.observatory import Catalog

catalog = Catalog()
category = catalog.categories.get('demographics')
geographies = category.geographies

Same example as above but using nested filters:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
geographies = catalog.category('demographics').geographies

You can perform these other operations with a CatalogList:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
geographies = catalog.category('demographics').geographies
# convert the list of datasets into a pandas DataFrame
# for further filtering and exploration
dataframe = geographies.to_dataframe()
# get a geography by ID or slug
dataset = geographies.get(A_VALID_ID_OR_SLUG)
name

Name of this category instance.

class cartoframes.data.observatory.Country(data)

Bases: cartoframes.data.observatory.catalog.entity.CatalogEntity

This class represents a Country in the Catalog. Catalog datasets (Dataset class) belong to a country, so you can filter available datasets and geographies that belong (or are related) to a given Country.

Examples

List the available countries in the Catalog

from cartoframes.data.observatory import Catalog

catalog = Catalog()
countries = catalog.countries

Get a Country from the Catalog given its ID

from cartoframes.data.observatory import Catalog

catalog = Catalog()
# country ID is a lowercase ISO Alpha 3 Code
category = catalog.countries.get('usa')
categories

Get the list of Category that are assigned to Dataset that cover data for this country.

Returns:

CatalogList List of Category instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.

Examples

Get all the categories Category available in the catalog for a Country instance

from cartoframes.data.observatory import Catalog

catalog = Catalog()
country = catalog.countries.get('usa')
categories = country.categories

Same example as above but using nested filters:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
category = catalog.country('usa').categories
datasets

Get the list of Dataset covering data for this country.

Returns:

CatalogList List of Dataset instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.

Examples

Get all the datasets Dataset available in the catalog for a Country instance

from cartoframes.data.observatory import Catalog

catalog = Catalog()
country = catalog.countries.get('usa')
datasets = country.datasets

Same example as above but using nested filters:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
datasets = catalog.country('usa').datasets

You can perform these other operations with a CatalogList:

from cartoframes.data.observatory import Catalog

datasets = catalog.country('usa').datasets
# convert the list of datasets into a pandas DataFrame
# for further filtering and exploration
dataframe = datasets.to_dataframe()
# get a dataset by ID or slug
dataset = datasets.get(A_VALID_ID_OR_SLUG)
geographies

Get the list of Geography covering data for this country.

Returns:

CatalogList List of Geography instances.

Raises:
  • DiscoveryException – When no geographies are found.
  • CartoException – If there’s a problem when connecting to the catalog.

Examples

Get all the geographies Geography available in the catalog for a Country instance

from cartoframes.data.observatory import Catalog

catalog = Catalog()
country = catalog.countries.get('usa')
geographies = country.geographies

Same example as above but using nested filters:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
geographies = catalog.country('usa').geographies

You can perform these other operations with a CatalogList:

from cartoframes.data.observatory import Catalog

geographies = catalog.country('usa').geographies
# convert the list of geographies into a pandas DataFrame
# for further filtering and exploration
dataframe = geographies.to_dataframe()
# get a geography by ID or slug
geography = geographies.get(A_VALID_ID_OR_SLUG)
class cartoframes.data.observatory.Dataset(data)

Bases: cartoframes.data.observatory.catalog.entity.CatalogEntity

A Dataset represents the metadata of a particular dataset in the catalog.

If you have Data Observatory enabled in your CARTO account you can:

  • Use any public dataset to enrich your data with the variables in it by means of the Enrichment functions.
  • Subscribe (Dataset.subscribe) to any premium dataset, to get a license, that grants you the right to enrich your data with the variables (Variable) in it.

See the enrichment guides for more information about datasets, variables and enrichment functions.

The metadata of a dataset allows you to understand the underlying data, from variables (the actual columns in the dataset, data types, etc.), to a description of the provider, source, country, geography available, etc.

See the attributes reference in this class to understand the metadata available for each dataset in the catalog.

Examples:

There are many different ways to explore the available datasets in the catalog.

You can just list all the available datasets:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
datasets = catalog.datasets

Since the catalog contains thousands of datasets, you can convert the list of datasets to a pandas DataFrame for further filtering:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
dataframe = catalog.datasets.to_dataframe()

The catalog supports nested filters for a hierarchical exploration. This way you could list the datasets available for different hierarchies: country, provider, category, geography or a combination of them.

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').geography('ags_blockgroup_1c63771c').datasets
category

Get the Category ID assigned to this dataset.sets

category_name

Name of the Category assigned to this dataset.

country

ISO 3166-1 alpha-3 code of the Country of this dataset.

counts()

Returns a summary of different counts over the actual dataset data.

Returns:pandas.Series

Example

# rows:         number of rows in the dataset
# cells:        number of cells in the dataset (rows * columns)
# null_cells:   number of cells with null value in the dataset
# null_cells_percent:   percent of cells with null value in the dataset
data_source

Id of the data source of this dataset.

describe()

Shows a summary of the actual stats of the variables (columns) of the dataset. Some of the stats provided per variable are: avg, max, min, sum, range, stdev, q1, q3, median and interquartile_range

Returns:pandas.DataFrame

Example

# avg                    average value
# max                    max value
# min                    min value
# sum                    sum of all values
# range
# stdev                  standard deviation
# q1                     first quantile
# q3                     third quantile
# median                 median value
# interquartile_range
description

Description of this dataset.

download(credentials=None)

Download dataset data as a local file. You need Data Observatory enabled in your CARTO account, please contact us at support@carto.com for more information.

For premium geographies (those with is_public_data set to False), you need a subscription to the geography. Check the subscription guides for more information.

Parameters:

credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.

Returns:

os.path with the local file path with the file downloaded

Raises:
  • CartoException – If you have not a valid license for the dataset being downloaded.
  • ValueError – If the credentials argument is not valud.
fields_by_type()

Returns a summary of the number of columns per data type in the dataset.

Returns:pandas.Series

Example

# float        number of columns with type float in the dataset
# string       number of columns with type string in the dataset
# integer      number of columns with type integer in the dataset
geography

Get the Geography ID associated to this dataset.

geography_description

Description of the Geography associated to this dataset.

geography_name

Get the name of the Geography associated to this dataset.

geom_coverage()

Shows a map to visualize the geographical coverage of the dataset.

Returns:cartoframes.viz.Map
classmethod get_all(filters=None, credentials=None)

Get all the Dataset instances that comply with the indicated filters (or all of them if no filters are passed). If credentials are given, only the datasets granted for those credentials are returned.

Parameters:
  • credentials (Credentials, optional) – credentials of CARTO user account. If provided, only datasets granted for those credentials are returned.
  • filters (dict, optional) – Dict containing pairs of dataset properties and its value to be used as filters to query the available datasets. If none is provided, no filters will be applied to the query.
Returns:

CatalogList List of Dataset instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
classmethod get_datasets_spatial_filtered(filter_dataset)
head()

Returns a sample of the 10 first rows of the dataset data.

If a dataset has fewer than 10 rows (e.g., zip codes of small countries), this method will return None

Returns:pandas.DataFrame
is_public_data

Allows to check if the content of this dataset can be accessed with public credentials or if it is a premium dataset that needs a subscription.

Returns:
  • True if the dataset is public
  • False if the dataset is premium
    (it requires to Dataset.subscribe)
Return type:A boolean value
language

ISO 639-3 code of the language that corresponds to the data of this dataset.

name

Name of this dataset.

provider

Id of the Provider of this dataset.

provider_name

Name of the Provider of this dataset.

subscribe(credentials=None)

Subscribe to a dataset. You need Data Observatory enabled in your CARTO account, please contact us at support@carto.com for more information.

Datasets with is_public_data set to True do not need a license (i.e., a subscription) to be used. Datasets with is_public_data set to False do need a license (i.e., a subscription) to be used. You’ll get a license to use this dataset depending on the estimated_delivery_days set for this specific dataset.

See subscription_info for more info

Once you subscribe to a dataset, you can Dataset.download its data and use the Enrichment functions. See the enrichment guides for more info.

You can check the status of your subscriptions by calling the subscriptions method in the Catalog with your CARTO Credentials.

Parameters:credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.
Raises:CartoException – If there’s a problem when connecting to the catalog.
subscription_info(credentials=None)

Get the subscription information of a Dataset, which includes the license, Terms of Service, rights, price, and estimated time of delivery, among other metadata of interest during the Dataset.subscription process.

Parameters:credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.
Returns:SubscriptionInfo SubscriptionInfo instance.
Raises:CartoException – If there’s a problem when connecting to the catalog.
summary

JSON object with extra metadata that summarizes different properties of the dataset content.

tail()

“Returns the last ten rows of the dataset”

If a dataset has fewer than 10 rows (e.g., zip codes of small countries), this method will return None

Returns:pandas.DataFrame
temporal_aggregation

Time amount in which data is aggregated in this dataset.

This is a free text field in this form: seconds, daily, hourly, monthly, yearly, etc.

time_coverage

Time range that covers the data of this dataset.

Returns:List of str

Example: [2015-01-01,2016-01-01)

update_frequency

Frequency in which the dataset is updated.

Returns:str

Example: monthly, yearly, etc.

variables

Get the list of Variable that corresponds to this dataset. Variables are used in the Enrichment functions to augment your local DataFrames with columns from a Dataset in the Data Observatory.

Returns:CatalogList List of Variable instances.
Raises:CartoException – If there’s a problem when connecting to the catalog.
variables_groups

Get the list of VariableGroup related to this dataset.

Returns:CatalogList List of VariableGroup instances.
Raises:CartoException – If there’s a problem when connecting to the catalog.
version

Internal version info of this dataset.

Returns:str
class cartoframes.data.observatory.Geography(data)

Bases: cartoframes.data.observatory.catalog.entity.CatalogEntity

A Geography represents the metadata of a particular geography dataset in the catalog.

If you have Data Observatory enabled in your CARTO account you can:

  • Use any public geography to enrich your data with the variables in it by means of the Enrichment functions.
  • Subscribe (Geography.subscribe) to any premium geography, to get a license, that grants you the right to enrich your data with the variables in it.

See the enrichment guides for more information about geographies, variables and enrichment functions.

The metadata of a geography allows you to understand the underlying data, from variables (the actual columns in the geography, data types, etc.), to a description of the provider, source, country, geography available, etc.

See the attributes reference in this class to understand the metadata available for each geography in the catalog.

Examples

There are many different ways to explore the available geographies in the catalog.

You can just list all the available geographies:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
geographies = catalog.geographies

Since the catalog contains thousands of geographies, you can convert the list of geographies to a pandas DataFrame for further filtering:

from cartoframes.data.observatory import Catalog

catalog = Catalog()
dataframe = catalog.geographies.to_dataframe()

The catalog supports nested filters for a hierarchical exploration. This way you could list the geographies available for different hierarchies: country, provider, category or a combination of them.

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').geographies

Usually you use a geography ID as an intermediate filter to get a list of datasets with aggregate data for that geographical resolution

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.country('usa').category('demographics').geography('ags_blockgroup_1c63771c').datasets
country

Code (ISO 3166-1 alpha-3) of the country of this geography.

datasets

Get the list of datasets related to this geography.

Returns:

CatalogList List of Dataset instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
description

Description of this geography.

download(credentials=None)

Download Geography data as a pandas DataFrame locally. You need Data Observatory enabled in your CARTO account, please contact us at support@carto.com for more information.

For premium geographies (those with is_public_data set to False), you need a subscription to the geography. Check the subscription guides for more information.

Parameters:

credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.

Returns:

A string with the local file path with the file downloaded

Raises:
  • CartoException – If you have not a valid license for the dataset being downloaded.
  • ValueError – If the credentials argument is not valud.
geom_coverage

Shows a map to visualize the geographical coverage of the geography data.

geom_type

Info about the type of geometry of this geography.

classmethod get_all(filters=None, credentials=None)

Get all the Geography instances that comply with the indicated filters (or all of them if no filters are passed. If credentials are given, only the geographies granted for those credentials are returned.

Parameters:
  • credentials (Credentials, optional) – credentials of CARTO user account. If provided, only geographies granted for those credentials are returned.
  • filters (dict, optional) – Dict containing pairs of geography properties and its value to be used as filters to query the available geographies. If none is provided, no filters will be applied to the query.
Returns:

CatalogList List of Geography instances.

Raises:
  • DiscoveryException – When no geographies are found.
  • CartoException – If there’s a problem when connecting to the catalog.
is_public_data

Allows to check if the content of this geography can be accessed with public credentials or if it is a premium geography that needs a subscription.

Returns:
  • True if the geography is public
  • False if the geography is premium
    (it requires to Geography.subscribe)
Return type:A boolean value
language

Code (ISO 639-3) of the language that corresponds to the data of this geography.

name

Name of this geography.

provider

Id of the Provider of this geography.

provider_name

Name of the Provider of this geography.

subscribe(credentials=None)

Subscribe to a Geography. You need Data Observatory enabled in your CARTO account, please contact us at support@carto.com for more information.

Geographies with is_public_data set to True, do not need a license (i.e. a subscription) to be used. Geographies with is_public_data set to False, do need a license (i.e. a subscription) to be used. You’ll get a license to use this geography depending on the estimated_delivery_days set for this specific geography.

See subscription_info for more info

Once you Geography.subscribe to a geography you can Geography.download its data and use the enrichment functions. See the enrichment guides for more info.

You can check the status of your subscriptions by calling the subscriptions method in the Catalog with your CARTO credentials.

Parameters:credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.
Raises:CartoException – If there’s a problem when connecting to the catalog.
subscription_info(credentials=None)

Get the subscription information of a Geography, which includes the license, TOS, rights, prize and estimated_time_of_delivery, among other metadata of interest during the subscription process.

Parameters:credentials (Credentials, optional) – credentials of CARTO user account. If not provided, a default credentials (if set with set_default_credentials) will be used.
Returns:SubscriptionInfo SubscriptionInfo instance.
Raises:CartoException – If there’s a problem when connecting to the catalog.
summary

dict with extra metadata that summarizes different properties of the geography content.

update_frequency

Frequency in which the geography data is updated.

Example: monthly, yearly, etc.

version

Internal version info of this geography.

class cartoframes.data.observatory.Provider(data)

Bases: cartoframes.data.observatory.catalog.entity.CatalogEntity

This class represents a Provider of datasets and geographies in the Catalog.

Examples

List the available providers in the Catalog in combination with nested filters (categories, countries, etc.)

from cartoframes.data.observatory import Provider

providers = Provider.get_all()

Get a Provider from the Catalog given its ID

from cartoframes.data.observatory import Catalog

catalog = Catalog()
provider = catalog.provider('mrli')
datasets

Get the list of datasets related to this provider.

Returns:

CatalogList List of Dataset instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.

Examples

from cartoframes.data.observatory import Catalog

catalog = Catalog()
datasets = catalog.provider('mrli').datasets
name

Name of this provider.

class cartoframes.data.observatory.Variable(data)

Bases: cartoframes.data.observatory.catalog.entity.CatalogEntity

This class represents a Variable of datasets in the Catalog.

Variables contain column names, description, data type, aggregation method and some other metadata that is useful to understand the underlying data inside a Dataset

Examples

List the variables of a Dataset in combination with nested filters (categories, countries, etc.)

from cartoframes.data.observatory import Catalog

catalog = new Catalog()
dataset = catalog.country('usa').category('demographics').datasets.get('mbi_retail_turn_705247a')
dataset.variables
agg_method

Text representing a description of the aggregation method used to compute the values in this Variable

column_name

Column name of the actual table related to the variable in the Dataset.

counts()

Returns a summary of different counts over the actual variable values.

Example

# all               total number of valiues
# null              total number of null values
# zero              number of zero-valued entries
# extreme           number of values 3stdev outside the interquartile range
# distinct          number of distinct (unique) entries
# outliers          number of outliers (outside 1.5stdev the interquartile range
# zero_percent      percent of values that are zero
# distinct_percent  percent of values that are distinct
dataset

ID of the Dataset to which this variable belongs.

dataset_name
datasets

Get the list of datasets related to this variable.

Returns:

CatalogList List of Dataset instances.

Raises:
  • DiscoveryException – When no datasets are found.
  • CartoException – If there’s a problem when connecting to the catalog.
db_type

Type in the database.

Returns:str

Examples: INTEGER, STRING, FLOAT, GEOGRAPHY, JSON, BOOL, etc.

describe()

Shows a summary of the actual stats of the variable (column) of the dataset. Some of the stats provided per variable are: avg, max, min, sum, range, stdev, q1, q3, median and interquartile_range

Example

# avg                    average value
# max                    max value
# min                    min value
# sum                    sum of all values
# range
# stdev                  standard deviation
# q1                     first quantile
# q3                     third quantile
# median                 median value
# interquartile_range
description

Description of this variable.

head()

Returns a sample of the 10 first values of the variable data.

For the cases of datasets with a content fewer than 10 rows (i.e. zip codes of small countries), this method won’t return anything

histogram()

Plots an histogram with the variable data.

name

Name of this variable.

project_name
quantiles()

Returns the quantiles of the variable data.

schema_name
starred

Boolean indicating whether this variable is a starred one or not. Internal usage only

summary

JSON object with extra metadata that summarizes different properties of this variable.

tail()

Returns a sample of the 10 last values of the variable data.

For the cases of datasets with a content fewer than 10 rows (i.e. zip codes of small countries), this method won’t return anything

top_values()

Returns information about the top values of the variable data.

variable_group

If any, ID of the variable group to which this variable belongs.

class cartoframes.data.observatory.Enrichment(credentials=None)

Bases: cartoframes.data.observatory.enrichment.enrichment_service.EnrichmentService

This is the main class to enrich your own data with data from the Data Observatory

To be able to use the Enrichment functions you need A CARTO account with Data Observatory v2 enabled. Contact us at support@carto.com for more information about this.

Please, see the Catalog discovery and subscription guides, to understand how to explore the Data Observatory repository and subscribe to premium datasets to be used in your enrichment workflows.

Parameters:credentials (Credentials, optional) – credentials of user account. If not provided, a default credentials (if set with set_default_credentials) will attempted to be used.
AGGREGATION_DEFAULT = 'default'
AGGREGATION_NONE = 'none'
enrich_points(dataframe, variables, geom_col=None, filters=[])

Enrich your points DataFrame with columns (Variable) from one or more Dataset in the Data Observatory, intersecting the points in the source DataFrame with the geographies in the Data Observatory.

Extra columns as area and population will be provided in the resulting DataFrame for normalization purposes.

Parameters:
  • (pandas DataFrame, geopandas GeoDataFrame (dataframe) – or CartoDataFrame): a DataFrame instance to be enriched.
  • variables (Variable, list, str) – variable ID, slug or Variable instance or list of variable IDs, slugs or Variable instances taken from the Data Observatory Catalog.
  • geom_col (str, optional) – string indicating the geometry column name in the source DataFrame.
  • filters (list, optional) – list of VariableFilter to filter rows from the enrichment data. Example: [VariableFilter(variable1, “= ‘a string’”)]
Returns:

A CartoDataFrame enriched with the variables passed as argument.

Note that if the points of the `dataframe` you provide are contained in more than one geometry in the enrichment dataset, the number of rows of the returned `CartoDataFrame` could be different than the `dataframe` argument number of rows.

Examples

Enrich a points DataFrame with Catalog classes:

import pandas
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment, Catalog

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
variables = catalog.country('usa').category('demographics').datasets[0].variables

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_points(df, variables)

Enrich a points dataframe with several Variables using their ids:

import pandas
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment, Catalog

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
all_variables = catalog.country('usa').category('demographics').datasets[0].variables
variable1 = all_variables[0]
variable2 = all_variables[1]
variables = [
    variable1.id,
    variable2.id
]

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_points(df, variables)

Enrich a points dataframe with filters:

import pandas
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment, Catalog, VariableFilter

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
variable = catalog.country('usa').category('demographics').datasets[0].variables[0]
filter = VariableFilter(variable, "= '2019-09-01'")

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_points(df, variables=[variable], filters=[filter])
enrich_polygons(dataframe, variables, geom_col=None, filters=[], aggregation='default')

Enrich your polygons DataFrame with columns (Variable) from one or more Dataset in the Data Observatory by intersecting the polygons in the source DataFrame with geographies in the Data Observatory.

When a polygon intersects with multiple geographies, the proportional part of the intersection will be used to interpolate the quantity of the polygon value intersected, aggregating them. Most of Variable instances have a Variable.agg_method property which is used by default as aggregation function, but you can overwrite it using the aggregation parameter (not even doing the aggregation). If a variable does not have the agg_method property set and you do not overwrite it either (with the aggregation parameter), the variable column will be skipped from the enrichment.

Parameters:
  • (pandas DataFrame, geopandas GeoDataFrame (dataframe) – or CartoDataFrame): a DataFrame instance to be enriched.
  • variables (Variable, list, str) – variable ID, slug or Variable instance or list of variable IDs, slugs or Variable instances taken from the Data Observatory Catalog.
  • geom_col (str, optional) – string indicating the geometry column name in the source DataFrame.
  • filters (list, optional) – list of VariableFilter to filter rows from the enrichment data. Example: [VariableFilter(variable1, “= ‘a string’”)]
  • aggregation (str, list, optional) –

    sets the data aggregation. The polygons in the source DataFrame can intersect with one or more polygons from the Data Observatory. With this method you can select how to aggregate the resulting data.

    An aggregation method can be one of these values: ‘MIN’, ‘MAX’, ‘SUM’, ‘AVG’, ‘COUNT’, ‘ARRAY_AGG’, ‘ARRAY_CONCAT_AGG’, ‘STRING_AGG’ but check this documentation for a complete list of aggregate functions.

    The options are:

    aggregation method in the Variable.agg_method property and it will be used to aggregate the data (a variable could not have agg_method defined and in this case, the variables will be skipped).

    You will receive a row of data from each polygon instersected.

    • str: if you want to overwrite every default aggregation method, you can pass a string with the

    aggregation method to use.

    • dictionary: if you want to overwrite some default aggregation methods from your selected

    variables, use a dict as Variable.id: aggregation method pairs, for example: {variable1.id: ‘SUM’, variable3.id: ‘AVG’}.

Returns:

A CartoDataFrame enriched with the variables passed as argument.

Note that if the geometry of the `dataframe` you provide intersects with more than one geometry in the enrichment dataset, the number of rows of the returned `CartoDataFrame` could be different than the `dataframe` argument number of rows.

Examples

Enrich a polygons dataframe with one Variable:

import pandas
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment, Catalog

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
variable = catalog.country('usa').category('demographics').datasets[0].variables[0]
variables = [variable]

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_polygons(df, variables)

Enrich a polygons dataframe with all Variables from a Catalog Dataset:

import pandas
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment, Catalog

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
variables = catalog.country('usa').category('demographics').datasets[0].variables

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_polygons(df, variables)

Enrich a polygons dataframe with several Variables using their ids:

import pandas
from cartoframes.auth import set_default_credentials
from cartoframes.data.observatory import Enrichment, Catalog

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
all_variables = catalog.country('usa').category('demographics').datasets[0].variables
variable1 = all_variables[0]
variable2 = all_variables[1]
variables = [
    variable1.id,
    variable2.id
]

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_polygons(df, variables)

Enrich a polygons dataframe with filters:

import pandas
from cartoframes.data.observatory import Enrichment, Catalog, VariableFilter
from cartoframes.auth import set_default_credentials, Credentials

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
variable = catalog.country('usa').category('demographics').datasets[0].variables[0]
filter = VariableFilter(variable, "= '2019-09-01'")

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_polygons(df, variables=[variable], filters=[filter])

Enrich a polygons dataframe overwriting every variables aggregation methods to use SUM function:

import pandas
from cartoframes.data.observatory import Enrichment, Catalog
from cartoframes.auth import set_default_credentials, Credentials

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
all_variables = catalog.country('usa').category('demographics').datasets[0].variables
variable1 = all_variables[0] // variable1.agg_method is 'AVG' but you want 'SUM'
variable2 = all_variables[1] // variable2.agg_method is 'AVG' and it is what you want
variable3 = all_variables[2] // variable3.agg_method is 'SUM' but you want 'AVG'

variables = [variable1, variable2, variable3]

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_polygons(df, variables, aggregation='SUM')

Enrich a polygons dataframe overwriting some of the variables aggregation methods:

import pandas
from cartoframes.data.observatory import Enrichment, Catalog
from cartoframes.auth import set_default_credentials, Credentials

set_default_credentials()

df = pandas.read_csv('...')

catalog = Catalog()
all_variables = catalog.country('usa').category('demographics').datasets[0].variables
variable1 = all_variables[0] // variable1.agg_method is 'AVG' but you want 'SUM'
variable2 = all_variables[1] // variable2.agg_method is 'AVG' and it is what you want
variable3 = all_variables[2] // variable3.agg_method is 'SUM' but you want 'AVG'

variables = [variable1, variable2, variable3]

aggregation = {
    variable1.id: 'SUM',
    variable3.id: 'AVG'
}

enrichment = Enrichment()
cdf_enrich = enrichment.enrich_polygons(df, variables, aggregation=aggregation)
class cartoframes.data.observatory.VariableFilter(variable, query)

Bases: object

This class can be used for filtering the results of Enrichment functions. It works by appending the VariableFilter SQL operators to the WHERE clause of the resulting enrichment SQL with the AND operator.

Args:
variable (str or Variable):
The variable name or Variable instance
query (str):
The SQL query filter to be appended to the enrichment SQL query.

Examples:

  • Equal to number: VariableFilter(variable, ‘= 3’)
  • Equal to string: VariableFilter(variable, “= ‘the string’”)
  • Greater that 3: VariableFilter(variable, ‘> 3’)

Next example uses a VariableFilter instance to calculate the SUM of car-free households Variable of the Catalog for each polygon of my_local_dataframe pandas DataFrame only for areas with more than 100 free car-free households

from cartoframes.data.observatory import Enrichment, Variable, VariableFilter

variable = Variable.get('no_cars_d19dfd10')
enriched_dataset_cdf = Enrichment().enrich_polygons(
    my_local_dataframe,
    variables=[variable],
    aggregation=[VariableAggregation(variable, 'SUM')]
    filters=[VariableFilter(variable, '> 100')]
)
class cartoframes.data.observatory.Subscriptions(datasets, geographies)

Bases: object

This class is used to list the datasets and geographies you have a acquired a subscription (or valid license) for.

This class won’t show any dataset or geography tagged in the catalog as is_public_data since those data do not require a subscription.

datasets

List of Dataset you have a subscription for.

Raises:CartoException – If there’s a problem when connecting to the catalog.
geographies

List of Geography you have a subscription for.

Raises:CartoException – If there’s a problem when connecting to the catalog.
class cartoframes.data.observatory.SubscriptionInfo(raw_data)

Bases: object

This class represents a SubscriptionInfo of datasets and geographies in the Catalog

It contains private metadata (you need a CARTO account to query them) that is useful when you want a subscription license for a specific dataset or geography.

estimated_delivery_days

Estimated days in which, once you Dataset.subscribe or Geography.subscribe, you’ll get a license.

Your licensed datasets and geographies will be returned by the catalog.subscriptions method.

For the datasets and geographies listed in the catalog.subscriptions method you can: - Dataset.download or Geography.download - Use their Dataset.variables in the Enrichment functions

id

The ID of the dataset or geography.

licenses

Description of the licenses.

Link to additional information about the available licenses.

rights

Rights over the dataset or geography when you buy a license by means of a subscription.

subscription_list_price

Price in $ for a one year subscription for this dataset.

tos

Legal Terms Of Service.

Link to additional information for the legal Terms Of Service.

class cartoframes.data.observatory.CatalogEntity(data)

Bases: abc.ABC

This is an internal class the rest of the classes related to the catalog discovery extend.

It contains:
  • Properties: id, slug (a shorter ID).
  • Static methods: get, get_all, get_list to retrieve elements or lists of objects in the catalog such as datasets, categories, variables, etc.
  • Instance methods to convert to pandas Series, Python dict, compare instances, etc.

As a rule of thumb you don’t use directly this class, it is documented for inheritance purposes.

export_excluded_fields = ['summary_json', 'available_in', 'geom_coverage']
classmethod get(id_)

Get an instance of an entity by ID or slug.

Parameters:

id (str) – ID or slug of a catalog entity.

Raises:
  • DiscoveryException – When no entities found.
  • CartoException – If there’s a problem when connecting to the catalog.
classmethod get_all(filters=None)

List all instances of an entity.

Parameters:filters (dict, optional) – Dict containing pairs of entity properties and its value to be used as filters to query the available entities. If none is provided, no filters will be applied to the query.
classmethod get_list(id_list)

Get a list of instance of an entity by a list of IDs or slugs.

Parameters:

id_list (list) – List of sD or slugs of a entities in the catalog to retrieve instances.

Raises:
  • DiscoveryException – When no entities found.
  • CartoException – If there’s a problem when connecting to the catalog.
id

The ID of the entity.

id_field = 'id'
slug

The slug (short ID) of the entity.

to_dict()

Converts the entity instance to a Python dict.

to_series()

Converts the entity instance to a pandas Series.

class cartoframes.data.observatory.CatalogList(data)

Bases: list

This is an internal class that represents a list of entities in the catalog of the same type.

It contains:
  • Instance methods to convert to get an instance of the entity by ID and to convert the list to a pandas DataFrame for further filtering and exploration.

As a rule of thumb you don’t use directly this class, it is documented for inheritance purposes.

get(item_id)

Gets an entity by ID or slug

Examples

from cartoframes.data.observatory import Catalog

catalog = Catalog()
category = catalog.categories.get('demographics')
to_dataframe()

Converts a list to a pandas DataFrame.

Examples

from cartoframes.data.observatory import Catalog

catalog = Catalog()
catalog.categories.to_dataframe()

Data Services

class cartoframes.data.services.Geocoding(credentials=None)

Bases: cartoframes.data.services.service.Service

Geocoding using CARTO data services.

This requires a CARTO account with and API key that allows for using geocoding services; (through explicit argument in constructor or via the default credentials).

To prevent having to geocode records that have been previously geocoded, and thus spend quota unnecessarily, you should always preserve the the_geom and carto_geocode_hash columns generated by the geocoding process. This will happen automatically if your input is a table from CARTO processed in place (i.e. without a table_name parameter) or if you save your results in a CARTO table using the table_name parameter, and only use the resulting table for any further geocoding.

In case you’re geocoding local data from a DataFrame that you plan to re-geocode again, (e.g. because you’re making your work reproducible by saving all the data preparation steps in a notebook), we advise to save the geocoding results immediately to the same store from when the data is originally taken, for example:

dataframe = pandas.read_csv('my_data')
dataframe = Geocoding().geocode(dataframe, 'address').data
dataframe.to_csv('my_data')

As an alternative you can use the cached option to store geocoding results in a CARTO table and reuse them in later geocodings. It is needed to use the table_name parameter with the name of the table used to cache the results.

If the same dataframe if geocoded repeatedly no credits will be spent, but note there is a time overhead related to uploading the dataframe to a temporary table for checking for changes.

dataframe = pandas.read_csv('my_data')
dataframe = Geocoding().geocode(dataframe, 'address', table_name='my_data', cached=True).data

If you execute the previous code multiple times it will only spend credits on the first geocoding; later ones will reuse the results stored in the my_data table. This will require extra processing time. If the CSV file should ever change, cached results will only be applied to unmodified records, and new geocoding will be performed only on new or changed records.

geocode(source, street, city=None, state=None, country=None, status={'gc_status_rel': 'relevance'}, table_name=None, if_exists='fail', dry_run=False, cached=None)

Geocode method

Parameters:
  • source (str, DataFrame, GeoDataFrame, CartoDataFrame) – table, SQL query or DataFrame object to be geocoded.
  • street (str) – name of the column containing postal addresses
  • city (dict, optional) – dictionary with either a column key with the name of a column containing the addresses’ city names or a value key with a literal city value value, e.g. ‘New York’. It also accepts a string, in which case column is implied.
  • state (dict, optional) – dictionary with either a column key with the name of a column containing the addresses’ state names or a value key with a literal state value value, e.g. ‘WA’. It also accepts a string, in which case column is implied.
  • country (dict, optional) – dictionary with either a column key with the name of a column containing the addresses’ country names or a value key with a literal country value value, e.g. ‘US’. It also accepts a string, in which case column is implied.
  • status (dict, optional) – dictionary that defines a mapping from geocoding state attributes (‘relevance’, ‘precision’, ‘match_types’) to column names. (See https://carto.com/developers/data-services-api/reference/) Columns will be added to the result data for the requested attributes. By default a column gc_status_rel will be created for the geocoding _relevance_. The special attribute ‘*’ refers to all the status attributes as a JSON object.
  • table_name (str, optional) – the geocoding results will be placed in a new CARTO table with this name.
  • if_exists (str, optional) – Behavior for creating new datasets, only applicable if table_name isn’t None; Options are ‘fail’, ‘replace’, or ‘append’. Defaults to ‘fail’.
  • cached (bool, optional) – Use cache geocoding results, saving the results in a table. This parameter should be used along with table_name.
  • dry_run (bool, optional) – no actual geocoding will be performed (useful to check the needed quota)
Returns:

py:class:CartoDataFrame <cartoframes.CartoDataFrame> and a metadata dictionary with global information about the geocoding process.

The data contains a geometry column with point locations for the geocoded addresses and also a carto_geocode_hash that, if preserved, can avoid re-geocoding unchanged data in future calls to geocode.

The metadata, as described in https://carto.com/developers/data-services-api/reference/, contains the following information:

Name Type Description
precision text precise or interpolated
relevance number 0 to 1, higher being more relevant
match_types array list of match type strings point_of_interest, country, state, county, locality, district, street, intersection, street_number, postal_code

By default the relevance is stored in an output column named gc_status_rel. The name of the column and in general what attributes are added as columns can be configured by using a status dictionary associating column names to status attribute.

Return type:

A named-tuple (data, metadata) containing either a data

Examples

Geocode a DataFrame:

import pandas
from data.services import Geocoding
from cartoframes.auth import set_default_credentials

set_default_credentials('YOUR_USER_NAME', 'YOUR_API_KEY')

df = pandas.DataFrame([['Gran Vía 46', 'Madrid'], ['Ebro 1', 'Sevilla']], columns=['address','city'])
gc = Geocoding()
geocoded_cdf, metadata = gc.geocode(df, street='address', city='city', country={'value': 'Spain'})

geocoded_cdf.head()

Geocode a table from CARTO:

from data.services import Geocoding
from cartoframes import CartoDataFrame
from cartoframes.auth import set_default_credentials

set_default_credentials('YOUR_USER_NAME', 'YOUR_API_KEY')

cdf = CartoDataFrame.from_carto('table_name')
gc = Geocoding()
geocoded_cdf, metadata = gc.geocode(cdf, street='address')

geocoded_cdf.head()

Geocode a query against a table from CARTO:

from data.services import Geocoding
from cartoframes import CartoDataFrame
from cartoframes.auth import set_default_credentials

set_default_credentials('YOUR_USER_NAME', 'YOUR_API_KEY')

cdf = CartoDataFrame.from_carto('SELECT * FROM table_name WHERE value > 1000')
gc = Geocoding()
geocoded_cdf, metadata = gc.geocode(cdf, street='address')

geocoded_cdf.head()

Obtain the number of credits needed to geocode a CARTO table:

from data.services import Geocoding
from cartoframes import CartoDataFrame
from cartoframes.auth import set_default_credentials

set_default_credentials('YOUR_USER_NAME', 'YOUR_API_KEY')

cdf = CartoDataFrame.from_carto('table_name')
gc = Geocoding()
geocoded_cdf, metadata = gc.geocode(cdf, street='address', dry_run=True)

print(metadata['required_quota'])

Filter results by relevance:

import pandas
from data.services import Geocoding
from cartoframes.auth import set_default_credentials

set_default_credentials('YOUR_USER_NAME', 'YOUR_API_KEY')

df = pandas.DataFrame([['Gran Vía 46', 'Madrid'], ['Ebro 1', 'Sevilla']], columns=['address','city'])
gc = Geocoding()
geocoded_cdf, metadata = gc.geocode(
    df,
    street='address',
    city='city',
    country={'value': 'Spain'},
    status=['relevance']
)

# show rows with relevance greater than 0.7:
print(geocoded_cdf[geocoded_cdf['carto_geocode_relevance'] > 0.7, axis=1)])
class cartoframes.data.services.Isolines(credentials=None)

Bases: cartoframes.data.services.service.Service

Time and distance Isoline services using CARTO dataservices.

isochrones(source, ranges, **args)

isochrone areas

This method computes areas delimited by isochrone lines (lines of constant travel time) based upon public roads.

Parameters:
  • source (str, DataFrame, GeoDataFrame, CartoDataFrame) – table, SQL query or DataFrame containing the source points for the isochrones: travel routes from the source points are computed to determine areas within specified travel times.
  • ranges (list) – travel time values in seconds; for each range value and source point a result polygon will be produced enclosing the area within range of the source.
  • exclusive (bool, optional) – when False, inclusive range areas are generated, each one containing the areas for smaller time values (so the area is reachable from the source whithin the given time). When True (the default), areas are exclusive, each one corresponding time values between the immediately smaller range value (or zero) and the area range value.
  • table_name (str, optional) – the resulting areas will be saved in a new CARTO table with this name.
  • if_exists (str, optional) – Behavior for creating new datasets, only applicable if table_name isn’t None; Options are ‘fail’, ‘replace’, or ‘append’. Defaults to ‘fail’.
  • dry_run (bool, optional) – no actual computattion will be performed, and metadata will be returned including the required quota.
  • mode (str, optional) – defines the travel mode: 'car' (the default) or 'walk'.
  • is_destination (bool, optional) – indicates that the source points are to be taken as destinations for the routes used to compute the area, rather than origins.
  • mode_type (str, optional) – type of routes computed: 'shortest' (default) or 'fastests'.
  • mode_traffic (str, optional) – use traffic data to compute routes: 'disabled' (default) or 'enabled'.
  • resolution (float, optional) – level of detail of the polygons in meters per pixel. Higher resolution may increase the response time of the service.
  • maxpoints (int, optional) – Allows to limit the amount of points in the returned polygons. Increasing the number of maxpoints may increase the response time of the service.
  • quality – (int, optional): Allows you to reduce the quality of the polygons in favor of the response time. Admitted values: 1/2/3.
  • geom_col (str, optional) – string indicating the geometry column name in the source DataFrame.
Returns:

py:class:CartoDataFrame <cartoframes.CartoDataFrame> and a metadata dictionary. For dry runs the data will be None. The data contains a range_data column with a numeric value and a the_geom geometry with the corresponding area. It will also contain a source_id column that identifies the source point corresponding to each area if the source has a cartodb_id column.

Return type:

A named-tuple (data, metadata) containing a data

isodistances(source, ranges, **args)

isodistance areas

This method computes areas delimited by isodistance lines (lines of constant travel distance) based upon public roads.

Parameters:
  • source (str, DataFrame, GeoDataFrame, CartoDataFrame) – table, SQL query or DataFrame containing the source points for the isodistances: travel routes from the source points are computed to determine areas within specified travel distances.
  • ranges (list) – travel distance values in meters; for each range value and source point a result polygon will be produced enclosing the area within range of the source.
  • exclusive (bool, optional) – when False, inclusive range areas are generated, each one containing the areas for smaller distance values (so the area is reachable from the source whithin the given distance). When True, areas are exclusive (the default), each one corresponding distance values between the immediately smaller range value (or zero) and the area range value.
  • table_name (str, optional) – the resulting areas will be saved in a new CARTO table with this name.
  • if_exists (str, optional) – Behavior for creating new datasets, only applicable if table_name isn’t None; Options are ‘fail’, ‘replace’, or ‘append’. Defaults to ‘fail’.
  • dry_run (bool, optional) – no actual computattion will be performed, and metadata will be returned including the required quota.
  • mode (str, optional) – defines the travel mode: 'car' (the default) or 'walk'.
  • is_destination (bool, optional) – indicates that the source points are to be taken as destinations for the routes used to compute the area, rather than origins.
  • mode_type (str, optional) – type of routes computed: 'shortest' (default) or 'fastests'.
  • mode_traffic (str, optional) – use traffic data to compute routes: 'disabled' (default) or 'enabled'.
  • resolution (float, optional) – level of detail of the polygons in meters per pixel. Higher resolution may increase the response time of the service.
  • maxpoints (int, optional) – Allows to limit the amount of points in the returned polygons. Increasing the number of maxpoints may increase the response time of the service.
  • quality – (int, optional): Allows you to reduce the quality of the polygons in favor of the response time. Admitted values: 1/2/3.
  • geom_col (str, optional) – string indicating the geometry column name in the source DataFrame.
Returns:

py:class:CartoDataFrame <cartoframes.CartoDataFrame> and a metadata dictionary. For dry runs the data will be None. The data contains a range_data column with a numeric value and a the_geom geometry with the corresponding area. It will also contain a source_id column that identifies the source point corresponding to each area if the source has a cartodb_id column.

Return type:

A named-tuple (data, metadata) containing a data

Viz

Viz namespace contains all the classes to create a visualization, mainly Map and Layer. It also includes our basemaps and the helper methods.

cartoframes.viz.basemaps

alias of Basemaps

cartoframes.viz.themes

alias of Themes

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)

Bases: object

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)
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.
delete_publication()

Delete the published map Kuviz.

get_content()
publish(name, table_name=None, credentials=None, password=None)

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

Parameters:
  • name (str) – The Kuviz name on CARTO
  • table_name (str, optional) – Desired table name for the dataset on CARTO. It is required working with local data (we need to upload it to 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. It is used to create the publication and also to save local data (if exists) into your CARTO account
  • 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')
update_publication(name, password)

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
class cartoframes.viz.Layout(maps, n_size=None, m_size=None, viewport=None, map_height=250, is_static=True)

Bases: object

Create a layout of visualizations in order to compare them.

Parameters:
  • maps (list of Map) – List of maps. Zero or more of Map.
  • N_SIZE (number, optional) – Number of columns of the layout
  • M_SIZE (number, optional) – Number of rows of the layout
  • viewport (dict, optional) – Properties for display of the maps viewport. Keys can be bearing or pitch.

Examples

Basic usage.

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

set_default_credentials('your_account')

Layout([
    Map(Layer('table_in_your_account')), Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account')), Map(Layer('table_in_your_account'))
])

Display a 2x2 layout.

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

set_default_credentials('your_account')

Layout([
    Map(Layer('table_in_your_account')), Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account')), Map(Layer('table_in_your_account'))
], 2, 2)

Custom Titles.

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

set_default_credentials('your_account')

Layout([
    Map(Layer('table_in_your_account'), title="Visualization 1 custom title"),
    Map(Layer('table_in_your_account'), title="Visualization 2 custom title")),
])

Viewport.

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

set_default_credentials('your_account')

Layout([
    Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account'))
], viewport={ 'zoom': 2 })
from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer, Layout

set_default_credentials('your_account')

Layout([
    Map(Layer('table_in_your_account'), viewport={ 'zoom': 0.5 }),
    Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account')),
    Map(Layer('table_in_your_account'))
], viewport={ 'zoom': 2 })
class cartoframes.viz.Layer(source, style=None, popup=None, legend=None, widgets=None, credentials=None, bounds=None, geom_col=None)

Bases: object

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.

:param source (str, CartoDataFrame,: pandas.DataFrame, geopandas.GeoDataFrame): The source data. :param style: The style of the visualization. :type style: str, dict, or Style, optional :param popup: 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. See Popup for more information.
Parameters:
  • 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, optional) – 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.
  • geom_col (str, optional) – string indicating the geometry column name in the source DataFrame.

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
class cartoframes.viz.Source(source, credentials=None, geom_col=None)

Bases: object

Parameters:
  • (str, pandas.DataFrame, geopandas.GeoDataFrame, (data) – CartoDataFrame ): a table name, SQL query, DataFrame, GeoDataFrame or CartoDataFrame instance.
  • credentials (Credentials, optional) – A Credentials instance. If not provided, the credentials will be automatically obtained from the default credentials if available.
  • 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.
  • geom_col (str, optional) – string indicating the geometry column name in the source DataFrame.

Example

Table name.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Source

set_default_credentials('your_user_name', 'your api key')

Source('table_name')

SQL query.

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Source

set_default_credentials('your_user_name', 'your api key')

Source('SELECT * FROM table_name')

CartoDataFrame object.

from cartoframes.viz import Source
from cartoframes import CartoDataFrame

set_default_credentials('your_user_name', 'your api key')

cdf = CartoDataFrame.from_carto('table_name')

Source(cdf)

Setting the credentials.

from cartoframes.auth import Credentials
from cartoframes.viz import Source

credentials = Credentials('your_user_name', 'your api key')

Source('table_name', credentials)
compute_metadata(columns=None)
get_credentials()
get_geom_type()
get_table_names()
is_local()
is_public()
schema()
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.

from cartoframes.viz import Style

Style('color: blue')

Style('''
    @sum: sqrt($pop_max) / 100
    @grad: [red, blue, green]
    color: ramp(globalEqIntervals($pop_min, 3), @grad)
    filter: @sum > 20
''')

Dict API.

from cartoframes.viz import Style

Style({
    'color': 'blue'
})

Style({
    'vars': {
        'sum': 'sqrt($pop_max) / 100',
        'grad': '[red, blue, green]'
    },
    'color': 'ramp(globalEqIntervals($pop_min, 3), @grad)',
    'filter': '@sum > 20'
})
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.

from cartoframes.viz import Popup

Popup({
    'hover': ['$name'],
    'click': ['$name', '$pop_max']
})

Show expressions.

from cartoframes.viz import Popup

Popup({
    'click': ['$pop_min % 100', 'sqrt($pop_max)']
})

Show titles.

from cartoframes.viz import Popup

Popup({
    'hover': [{
        'title': 'Name',
        'value': '$name'
    }],
    'click': [{
        'title': 'Name',
        'value': '$name'
    }, {
        'title': 'Pop max',
        'value': '$pop_max'
    }]
})
get_interactivity()
get_variables()
class cartoframes.viz.Legend(f_arg, **kwargs)

Bases: object

Parameters:
  • type (str) – ‘color-category’, ‘color-bins’, ‘color-continuous’, ‘size-bins’, or ‘size-continuous’.
  • prop (str, optional) – ‘color’, ‘width’, ‘strokeColor’, or ‘strokeWidth’.
  • dynamic (boolean, optional) – Update an render the legend depending on viewport changes. Defaults to True.
  • title (str, optional) – Title of legend.
  • description (str, optional) – Description in legend.
  • footer (str, optional) – Footer of legend. This is often used to attribute data sources.
  • variable (str, optional) – If the information in the legend depends on a different value than the information set to the style property, it is possible to set an independent variable.

Example

from cartoframes.viz import Legend

Legend('color-category', title='Legend Title', 'description': '[description]', 'footer': '[footer]')
from cartoframes.viz import Layer, Legend, Style

Layer(
    "SELECT * FROM populated_places WHERE adm0name = 'Spain'",
    Style('''
        color: ramp(globalQuantiles($pop_max, 5), reverse(purpor))
        @custom_legend: ramp($pop_max, reverse(purpor))
    '''),
    legend=Legend('color-category', title='Population', variable='custom_legend')
)
get_info(geom_type=None)
class cartoframes.viz.LegendList(legends=None)

Bases: object

Parameters:legends (dict, list, Legend) – List of legends for a layer.

Example

get_info(geom_type=None)
class cartoframes.viz.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]')
get_default_prop(data)
get_info()
has_bridge()
class cartoframes.viz.WidgetList(widgets=None)

Bases: object

Parameters:widgets (dict, list, Widget) – The list of widgets for a layer.

Example:

get_variables()
get_widgets_info()

Widgets

Widget helpers to generate widgets faster.

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
            )]
    )
)

Helpers

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, credentials=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 (list<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.
  • credentials (Credentials, optional) – 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.
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, credentials=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 (list<str>, optional) – Category list. Must be a valid list of categories.
  • 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.
  • credentials (Credentials, optional) – 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.
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='', range_min=None, range_max=None, palette=None, size=None, opacity=None, stroke_color=None, stroke_width=None, description='', footer='', legend=True, popup=True, widget=False, animate=None, credentials=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 and popup hover.
  • range_min (int, optional) – The minimum value of the data range for the continuous color ramp. Defaults to the globalMIN of the dataset.
  • range_max (int, optional) – The maximum value of the data range for the continuous color ramp. Defaults to the globalMAX of the dataset.
  • 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, Popup, 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.
  • credentials (Credentials, optional) – 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.
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, credentials=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 (list<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.
  • credentials (Credentials, optional) – 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.
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, credentials=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 (list<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.
  • credentials (Credentials, optional) – 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.
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='', range_min=None, range_max=None, size=None, color=None, opacity=None, stroke_width=None, stroke_color=None, description='', footer='', legend=True, popup=True, widget=False, animate=None, credentials=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 and popup hover.
  • range_min (int, optional) – The minimum value of the data range for the continuous size ramp. Defaults to the globalMIN of the dataset.
  • range_max (int, optional) – The maximum value of the data range for the continuous size ramp. Defaults to the globalMAX of the dataset.
  • 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.
  • credentials (Credentials, optional) – 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.
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, credentials=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, optional) – Cluster operation, defaults to ‘count’. Other options available are ‘avg’, ‘min’, ‘max’, and ‘sum’.
  • resolution (int, optional) – 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.
  • credentials (Credentials, optional) – 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.
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='', credentials=None)

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).
  • credentials (Credentials, optional) – 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.
Returns:

Layer styled by value. Includes Widget value.

Return type:

cartoframes.viz.Layer

cartoframes.viz.helpers.isolines_layer(source, value='range_label', **kwargs)

Helper function for quickly creating an isolines color map.

Parameters:
  • source (str, DataFrame) –
  • value (str, optional) – Column to symbolize by. By default is “range_label”.
  • 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 (list<str>, optional) – Category list. Must be a valid list of categories.
  • 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.

Example

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

from cartoframes.viz.helpers import isolines_layer

[...]

data, metadata = Isolines().isodistances(df, [1200, 2400, 3600])

isolines_layer(data, palette='purpor')
Returns:Layer styled by value. Includes a legend, popup and widget on value.
Return type:cartoframes.viz.Layer

Exceptions

exception cartoframes.exceptions.DiscoveryException(message)

Bases: exceptions.Exception

This exception is raised when a problem is encountered while using the Catalog Discovery functions (i.e. requesting an element with an unknown ID).

exception cartoframes.exceptions.EnrichmentException(message)

Bases: exceptions.Exception

This exception is raised when a problem is encountered while using enrichment functions.