CARTO Python package for data scientists
Project description
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.
Features
Write pandas DataFrames to CARTO tables
Read CARTO tables and queries into pandas DataFrames
Create customizable, interactive CARTO maps in a Jupyter notebook
Interact with CARTO’s Data Observatory
Use CARTO’s spatially-enabled database for analysis
Try it out without needing a CARTO account by using the Examples functionality
Common Uses
Visualize spatial data programmatically as matplotlib images or embedded interactive maps
Perform cloud-based spatial data processing using CARTO’s analysis tools
Extract, transform, and Load (ETL) data using the Python ecosystem for getting data into and out of CARTO
Data Services integrations using CARTO’s Data Observatory and other Data Services APIs
Try it out
The easiest way to try out cartoframes is to use the cartoframes example notebooks running in binder: https://mybinder.org/v2/gh/CartoDB/cartoframes/master?filepath=examples If you already have an API key, you can follow along and complete all of the example notebooks.
If you do not have an API key, you can use the Example Context to read the example data, make maps, and run arbitrary queries from the datasets there. The best place to get started is in the “Example Datasets” notebook found when running binder or downloading from the examples directory in the cartoframes GitHub repository.
More info
Complete documentation: http://cartoframes.readthedocs.io/en/latest/
Source code: https://github.com/CartoDB/cartoframes
bug tracker / feature requests: https://github.com/CartoDB/cartoframes/issues
Install Instructions
To install cartoframes on your machine, do the following to install the latest version:
$ pip install cartoframescartoframes 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.
Virtual Environment
Using virtualenv
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:
$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install cartoframes jupyter
(venv) $ jupyter notebookThen create a new notebook and try the example code snippets below with tables that are in your CARTO account.
Using pipenv
Alternatively, pipenv provides an easy way to manage virtual environments. The steps below are:
Create a virtual environment with Python 3.4+ (recommended instead of Python 2.7)
Install cartoframes and Jupyter (optional) into the virtual environment
Enter the virtual environment
Launch a Jupyter notebook server
$ pipenv --three
$ pipenv install cartoframes jupyter
$ pipenv shellNext, run a Python kernel by typing $ python, $ jupyter notebook, or however you typically run Python.
Native pip
If you install packages at a system level, you can install cartoframes with:
$ pip install cartoframesExample usage
Data workflow
Get table from CARTO, make changes in pandas, sync updates with CARTO:
import cartoframes
# `base_url`s are of the form `https://{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.
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')Map workflow
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.
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)
Data Observatory
Interact with CARTO’s Data Observatory:
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)CARTO Credential Management
Typical usage
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 https://{your_user_name}.carto.com/your_apps.
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:
from cartoframes import Credentials, CartoContext
cc = CartoContext(
creds=Credentials(key='{your_api_key}', username='{your_user_name}')
)Save/update credentials for later use
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:
from cartoframes import CartoContext
cc = CartoContext() # automatically loads credentials if previously savedExperimental features
CARTOframes includes experimental features that we are testing for future releases into cartoframes core. These features exist as separate modules in contrib. These features are stand-alone other than sometimes relying on some cartoframes utilities, etc. Contrib features will also change often and without notice, so they should never be used in a production environment.
To import an experimental feature, like vector maps, do the following:
from cartoframes.contrib import vector
from cartoframes import CartoContext
cc = CartoContext()
vector.vmap([vector.Layer('<table name>'), ])Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cartoframes-0.7.0.tar.gz.
File metadata
- Download URL: cartoframes-0.7.0.tar.gz
- Upload date:
- Size: 75.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2c89cd40045989baf77bd351e931d1661407b62bb3869d3a5ea1a851dc272bb0
|
|
| MD5 |
6dc336a9a5dc24968780cde7fe819bc3
|
|
| BLAKE2b-256 |
3e730c11aad0dbca80ea9a6c06191a713703e0ce552d54721e705f0cc41171e4
|
File details
Details for the file cartoframes-0.7.0-py2.py3-none-any.whl.
File metadata
- Download URL: cartoframes-0.7.0-py2.py3-none-any.whl
- Upload date:
- Size: 54.9 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f2aba1cfcaee6b146189593a750211de96aaf8fae28efdd504a5a2a6035293f9
|
|
| MD5 |
2e506af846ee70392d28a629e0113e46
|
|
| BLAKE2b-256 |
dab10b2bcd01f40527530eafb25f330244837f099358466c4da283a635761b4e
|
