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. Data Observatory 2.0 doesn’t work with this version. Upgrade to a newer version if you want to use it.

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')
property api_key

Credentials api_key

property username

Credentials username

property base_url

Credentials base_url

property session

Credentials session

classmethod from_file(config_file=None, session=None)

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

classmethod from_credentials(credentials)

Retrives credentials from another Credentials object

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')
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/')
get_do_token()

Returns the Data Observatory v2 token

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

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)

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 the GeoDataFrame geometry using either an existing column or the specified input. By default yields a new object.

The original geometry column is replaced with the input.

Parameters
  • col (column label or array) –

  • drop (boolean, default True) – Delete column to be used as the new geometry

  • inplace (boolean, default False) – Modify the GeoDataFrame in place (do not create a new object)

  • crs (str/result of fion.get_crs (optional)) – Coordinate system to use. If passed, overrides both DataFrame and col’s crs. Otherwise, tries to get crs from passed col values or DataFrame.

Examples

>>> df1 = df.set_geometry([Point(0,0), Point(1,1), Point(2,2)])
>>> df2 = df.set_geometry('geom1')
Returns

geodataframe

Return type

GeoDataFrame

set_geometry_from_xy(x, y, drop=False, inplace=False, crs=None)
astype(*args, **kwargs)

Cast a pandas object to a specified dtype dtype.

Returns a GeoDataFrame when the geometry column is kept as geometries, otherwise returns a pandas DataFrame.

See the pandas.DataFrame.astype docstring for more details.

Returns

Return type

GeoDataFrame or DataFrame

merge(*args, **kwargs)

Merge two GeoDataFrame objects with a database-style join.

Returns a GeoDataFrame if a geometry column is present; otherwise, returns a pandas DataFrame.

Returns

Return type

GeoDataFrame or DataFrame

Notes

The extra arguments *args and keyword arguments **kwargs are passed to DataFrame.merge.

https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.merge.html

dissolve(*args, **kwargs)

Dissolve geometries within groupby into single observation. This is accomplished by applying the unary_union method to all geometries within a groupself.

Observations associated with each groupby group will be aggregated using the aggfunc.

Parameters
  • by (string, default None) – Column whose values define groups to be dissolved

  • aggfunc (function or string, default "first") – Aggregation function for manipulation of data associated with each group. Passed to pandas groupby.agg method.

  • as_index (boolean, default True) – If true, groupby columns become index of result.

Returns

Return type

GeoDataFrame

explode(*args, **kwargs)

Explode muti-part geometries into multiple single geometries.

Each row containing a multi-part geometry will be split into multiple rows with single geometries, thereby increasing the vertical size of the GeoDataFrame.

The index of the input geodataframe is no longer unique and is replaced with a multi-index (original index with additional level indicating the multiple geometries: a new zero-based index for each single part geometry per multi-part geometry).

Returns

Exploded geodataframe with each single geometry as a separate entry in the geodataframe.

Return type

GeoDataFrame

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.

property 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.

property 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.

property 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.

property 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.

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

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

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

clear_filters()

Remove the current filters from this Catalog instance.

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

datasets_filter(filter_dataset)

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

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')
property 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)
property 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)
property 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')
property 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)
property 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)
property 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
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
property category

Get the Category ID assigned to this dataset.sets

property category_name

Name of the Category assigned to this dataset.

property 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
property 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
property 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
property geography

Get the Geography ID associated to this dataset.

property geography_description

Description of the Geography associated to this dataset.

property 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

property 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

property language

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

property name

Name of this dataset.

property provider

Id of the Provider of this dataset.

property 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.

property 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

property 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.

property time_coverage

Time range that covers the data of this dataset.

Returns

List of str

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

property update_frequency

Frequency in which the dataset is updated.

Returns

str

Example: monthly, yearly, etc.

property 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.

property 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.

property 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
property 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.

property name

Name of this geography.

property description

Description of this geography.

property country

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

property language

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

property provider

Id of the Provider of this geography.

property provider_name

Name of the Provider of this geography.

property geom_coverage

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

property geom_type

Info about the type of geometry of this geography.

property update_frequency

Frequency in which the geography data is updated.

Example: monthly, yearly, etc.

property version

Internal version info of this geography.

property 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

property summary

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

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.

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.

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.

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')
property 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
property 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
property 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.

property name

Name of this variable.

property description

Description of this variable.

property column_name

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

property db_type

Type in the database.

Returns

str

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

property dataset

ID of the Dataset to which this variable belongs.

property agg_method

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

property variable_group

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

property starred

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

property summary

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

property project_name
property schema_name
property dataset_name
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
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

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

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
quantiles()

Returns the quantiles of the variable data.

top_values()

Returns information about the top values of the variable data.

histogram()

Plots an histogram with the variable data.

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.

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])
AGGREGATION_DEFAULT = 'default'

Use default aggregation method for polygons enrichment. More info in Enrichment.enrich_polygons

AGGREGATION_NONE = 'none'

Do not aggregate data in polygons enrichment. More info in Enrichment.enrich_polygons

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

id_field = 'id'
export_excluded_fields = ['summary_json', 'available_in', 'geom_coverage']
property id

The ID of the entity.

property slug

The slug (short ID) of the entity.

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.

to_series()

Converts the entity instance to a pandas Series.

to_dict()

Converts the entity instance to a Python dict.

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

property datasets

List of Dataset you have a subscription for.

Raises

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

property 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.

property id

The ID of the dataset or geography.

property 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

property subscription_list_price

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

property tos

Legal Terms Of Service.

Link to additional information for the legal Terms Of Service.

property licenses

Description of the licenses.

Link to additional information about the available licenses.

property rights

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

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 cartoframes.viz.basemaps.Basemaps

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

Delete the published map Kuviz.

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

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.

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.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)
get_credentials()
get_geom_type()
compute_metadata(columns=None)
is_local()
is_public()
schema()
get_table_names()
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={})
cartoframes.viz.themes

alias of cartoframes.viz.themes.Themes

class cartoframes.viz.Widget(f_arg, **kwargs)

Bases: object

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_widgets_info()
get_variables()

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: 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: Exception

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