A Python package for integrating CARTO maps, analysis, and data services into data science workflows.
We will no longer support Data Observatory within this version of CARTOframes from the 1st of January 2021. We strongly recommend using the latest version of CARTOframes for the best experience.
This guide gets you set up with cartoframes by installing cartoframes, working in a Jupyter notebook, reading data from CARTO into your Python session, writing data to your CARTO account, and visualizing the data.
You can install CARTOframes with pip
. Simply type the following in the command line to do a system install:
1
$ pip install cartoframes
To install through a Jupyter notebook, you can run
1
!pip install cartoframes
It is recommended to install cartoframes in a virtual environment. For example, you can run the the following command line commands to create a virtual env, activate it, and install cartoframes:
1
2
3
$ virtualenv cfenv
$ source cfenv/bin/activate
(cfenv) $ pip install cartoframes
You’ll notice the virtual environment name in your command line prompt, like above. Type deactivate
to exit the virtualenv:
1
(cfenv) $ deactivate
To install Jupyter, type:
1
$ pip install jupyter
If working in a virtual environment, make sure you have activated the environment first.
Start up a Jupyter notebook with the following command:
1
$ jupyter notebook
After you type that command, you will see the notebook server starting up and a browser window with the directory contents open.
Next, create a new notebook. See Jupyter’s running a notebook for more information.
Before we can do anything with CARTOframes, we need to authenticate against a CARTO account by passing in CARTO credentials. You will need your username and API keys, which can be found at http://your_user_name.carto.com/your_apps
.
There are two methods of authentication:
base_url
and api_key
directly in CartoContext1
2
3
cc = CartoContext(
base_url='https://<your_user_name>.carto.com',
api_key='<your_api_key>')
1
2
3
from cartoframes import Credentials, CartoContext
creds = Credentials(username='<your_user_name>', key='<your_api_key>')
cc = CartoContext(creds=creds)
You can also save your credentials to use later, independent of the Python session. Your credentials will be saved locally on your machine for future sessions.
1
2
3
from cartoframes import Credentials, CartoContext
creds = Credentials(username='<your_user_name>', key='<your_api_key>')
creds.save() # save credentials for later use (not dependent on Python session)
Once your credientials are saved, you can start using CARTOframes more quickly:
1
2
from cartoframes import CartoContext
cc = CartoContext() # automatically loads credentials if previously saved
In this section, you will read a table from your CARTO account into your Python environment as a pandas DataFrame. If you don’t already have a table in your account that you want to use, you can send a dataset on poverty rates in Brooklyn, New York to your account with the following code:
1
2
from cartoframes.examples import read_brooklyn_poverty
cc.write(read_brooklyn_poverty(), 'brooklyn_poverty')
To get your table from CARTO, use the CartoContext.read
method:
1
2
# read a table from your CARTO account to a DataFrame
df = cc.read('brooklyn_poverty')
This pulls down the table brooklyn_poverty
from your CARTO account into a pandas DataFrame. The data types of the SQL table are copied over to the DataFrame and the index is cartodb_id
. To decode the geometries into Shapely geometries, use the decode_geom=True
flag.
Now that the data is in a DataFrame, you can use it just as a normal pandas DataFrame.
1
2
# do fancy pandas operations (add/drop columns, change values, etc.)
df['poverty_per_pop'] = df['poverty_count'] / df['total_population']
To write a table to CARTO, use the CartoContext.write
method as below:
1
cc.write(df, 'brooklyn_poverty_w_rates')
If the table already exists and you’d like to overwrite it, use the overwrite=True
flag like so:
1
cc.write(df, 'brooklyn_poverty', overwrite=True)
Now that you have a table in your account, you can visualize it using the CartoContext.map
method.
This creates an interactive map with only a basemap:
1
cc.map()
To add a data layer, import the Layer
class and pass it as an argument. We can go further and style by the poverty_per_pop
column to visualize based on a numeric value.
1
2
from cartoframes import Layer
cc.map(layers=Layer('brooklyn_poverty_w_rates', color='poverty_per_pop'))
Note: Legends are not yet implemented for stable releases of cartoframes. See this pull request for more information.