Skip to main content

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()
Example of creating a fresh cartoframe, performing an operation, and syncing with 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'))
Example of creating a fresh cartoframe, performing an operation, and syncing with carto

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')
Example of creating a cartoframe map in a Jupyter notebook

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()
Example of using data observatory augmentation methods

Project details


Release history Release notifications | RSS feed

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page