An experimental Python pandas interface for using CARTO
Project description
A pandas interface for integrating CARTO into data science workflows.
Install Instructions
cartoframes relies on pandas and a development version of the CARTO Python SDK (on branch 1.0.0). To install cartoframes on your machine, do the following:
Clone this repository.
Change your directory to cartoframes and run the following:
$ pip install -r requirements.txt
$ pip install cartoframes
Once you’ve done this, cartoframes will be installed. See the example usage section below for using cartoframes in a Jupyter notebook.
Note: Eventually cartoframes will be fully installable from pip.
Example usage
Data workflow
Get table from carto, make changes in pandas, sync updates with carto:
df = pd.read_carto(username=username,
api_key=api_key,
tablename='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
# show all database access with debug=True
df.sync_carto()
Associate an existing pandas dataframe with CARTO, and optionally get the geometry.
import pandas as pd
import cartoframes
import numpy as np
arr = np.arange(10)
np.random.shuffle(arr)
ingest = {'ids': list('abcdefghij'),
'scores': np.random.random(10),
'other_rank': arr,
'lat': 40.7128 + (0.5 - np.random.random(10)),
'lon': -74.0059 + (0.5 - np.random.random(10))}
df = pd.DataFrame(ingest)
df.sync_carto(username=USERNAME,
api_key=APIKEY,
requested_tablename='awesome_new_table',
createtable=True,
is_org_user=True,
latlng_cols=('lat', 'lon'))
Map workflow
The following will embed a CARTO map in a Jupyter notebook, allowing for custom styling of the maps driving by Turbo Carto and CartoColors.
df.carto_map(color={'colname': 'net', 'ramp': 'Bold'},
size={'colname': 'depth', 'min': 6, 'max': 20, 'quant_method': 'headtails'},
basemap='http://{s}.tile.thunderforest.com/spinal-map/{z}/{x}/{y}.png')
Augment from Data Observatory
Interact with CARTO’s Data Observatory:
# 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', 'denominator': 'predenominated'},
{'numer_id': 'us.census.acs.B19013001'},
{'numer_id': 'us.census.acs.B17001002', 'denominator': 'predenominated'}]
df.carto_do_augment(data_obs_measures)
df.head()