A Python package for integrating CARTO maps, analysis, and data services into data science workflows.
Python data analysis workflows often rely on the de facto standards pandas and Jupyter notebooks. Integrating CARTO into this workflow saves data scientists time and energy by not having to export datasets as files or retain multiple copies of the data. Instead, CARTOframes give the ability to communicate reproducible analysis while providing the ability to gain from CARTO’s services like hosted, dynamic or static maps and Data Observatory augmentation.
To install cartoframes on your machine, do the following to install the latest version:
1
$ pip install cartoframes
cartoframes is continuously tested on Python versions 2.7, 3.5, and 3.6. It is recommended to use cartoframes in Jupyter Notebooks (pip install jupyter). See the example usage section below or notebooks in the examples directory for using cartoframes in that environment.
Make sure your virtualenv package is installed and up-to-date. See the official Python packaging page for more information.
To setup cartoframes and Jupyter in a virtual environment:
1
2
3
4
$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install cartoframes jupyter
(venv) $ jupyter notebook
Then create a new notebook and try the example code snippets below with tables that are in your CARTO account.
Alternatively, pipenv provides an easy way to manage virtual environments. The steps below are:
1
2
3
$ pipenv --three
$ pipenv install cartoframes jupyter
$ pipenv shell
Next, run a Python kernel by typing $ python, $ jupyter notebook, or however you typically run Python.
If you install packages at a system level, you can install cartoframes with:
1
$ pip install cartoframes
Get table from CARTO, make changes in pandas, sync updates with CARTO:
1
2
3
4
5
6
7
8
9
10
11
12
13
import cartoframes
# `base_url`s are of the form `http://{username}.carto.com/` for most users
cc = cartoframes.CartoContext(base_url='https://eschbacher.carto.com/',
api_key=APIKEY)
# read a table from your CARTO account to a DataFrame
df = cc.read('brooklyn_poverty_census_tracts')
# do fancy pandas operations (add/drop columns, change values, etc.)
df['poverty_per_pop'] = df['poverty_count'] / df['total_population']
# updates CARTO table with all changes from this session
cc.write(df, 'brooklyn_poverty_census_tracts', overwrite=True)
Write an existing pandas DataFrame to CARTO.
1
2
3
4
5
6
import pandas as pd
import cartoframes
df = pd.read_csv('acadia_biodiversity.csv')
cc = cartoframes.CartoContext(base_url=BASEURL,
api_key=APIKEY)
cc.write(df, 'acadia_biodiversity')
The following will embed a CARTO map in a Jupyter notebook, allowing for custom styling of the maps driven by TurboCARTO and CARTOColors. See the CARTOColors wiki for a full list of available color schemes.
1
2
3
4
5
6
7
8
9
10
11
12
from cartoframes import Layer, BaseMap, styling
cc = cartoframes.CartoContext(base_url=BASEURL,
api_key=APIKEY)
cc.map(layers=[BaseMap('light'),
Layer('acadia_biodiversity',
color={'column': 'simpson_index',
'scheme': styling.tealRose(5)}),
Layer('peregrine_falcon_nest_sites',
size='num_eggs',
color={'column': 'bird_id',
'scheme': styling.vivid(10)})],
interactive=True)
Interact with CARTO’s Data Observatory:
1
2
3
4
5
6
7
8
9
10
11
12
import cartoframes
cc = cartoframes.CartoContext(BASEURL, APIKEY)
# total pop, high school diploma (normalized), median income, poverty status (normalized)
# See Data Observatory catalog for codes: https://cartodb.github.io/bigmetadata/index.html
data_obs_measures = [{'numer_id': 'us.census.acs.B01003001'},
{'numer_id': 'us.census.acs.B15003017',
'normalization': 'predenominated'},
{'numer_id': 'us.census.acs.B19013001'},
{'numer_id': 'us.census.acs.B17001002',
'normalization': 'predenominated'},]
df = cc.data('transactions', data_obs_measures)
The most common way to input credentials into cartoframes is through the
CartoContext, as below. Replace {your_user_name} with your CARTO
username and {your_api_key} with your API key, which you can find at
http://{your_user_name}.carto.com/your_apps
.
1
2
3
4
5
from cartoframes import CartoContext
cc = CartoContext(
base_url='https://{your_user_name}.carto.com',
api_key='{your_api_key}'
)
You can also set your credentials using the Credentials class:
1
2
3
4
from cartoframes import Credentials, CartoContext
cc = CartoContext(
creds=Credentials(key='{your_api_key}', username='{your_user_name}')
)
1
2
3
from cartoframes import Credentials, CartoContext
creds = Credentials(username='eschbacher', key='abcdefg')
creds.save() # save credentials for later use (not dependent on Python session)
Once you save your credentials, you can get started in future sessions more quickly:
1
2
from cartoframes import CartoContext
cc = CartoContext() # automatically loads credentials if previously saved