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.
Try it Out
If you do not have an API key, you can still use cartoframes for creating maps locally.
The example context only provides read access, so not all cartoframes features are available. For full access, Start a free 14 day trial or get free access with a GitHub Student Developer Pack.
Features
Create interactive maps from pandas DataFrames (CARTO account not required)
Publish interactive maps to CARTO’s platform
Write and read pandas DataFrames to/from CARTO tables and queries
Create customizable, interactive CARTO maps in a Jupyter notebook using DataFrames or hosted data
Augment your data with CARTO’s Data Observatory
Use CARTO for cloud-based analysis
Common Uses
Visualize spatial data programmatically as matplotlib images, as notebook-embedded interactive maps, or published map visualizations
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 Location Data Streams
More info
Complete documentation: https://carto.com/developers/cartoframes/
Source code: https://github.com/CartoDB/cartoframes
Bug tracker / feature requests: https://github.com/CartoDB/cartoframes/issues
cartoframes users must have a CARTO API key for most cartoframes functionality. For example, writing DataFrames to an account, reading from private tables, and visualizing data on maps all require an API key. CARTO provides API keys for education and nonprofit uses, among others. Request access at support@carto.com. API key access is also given through GitHub’s Student Developer Pack.
Install Instructions
To install cartoframes on your machine, do the following to install the latest version:
$ pip install cartoframes
To install the 1.0b7 beta version:
$ pip install cartoframes==1.0b7
cartoframes is continuously tested on Python versions 2.7, 3.5, 3.6, and 3.7. 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.
Example usage
Data workflow
Get table from CARTO, make changes in pandas, sync updates with CARTO:
from cartoframes import CartoDataFrame
from cartoframes.auth import set_default_credentials
# set your credentials
set_default_credentials(
username='your_user_name',
api_key='your API key'
)
# read a table from your CARTO account
cdf = CartoDataFrame.from_carto('brooklyn_poverty_census_tracts')
# perform operations on you dataframe
cdf['poverty_per_pop'] = cdf['poverty_count'] / cdf['total_population']
# update CARTO table with all changes from this session
cdf.to_carto(
table_name='brooklyn_poverty_census_tracts',
if_exists='replace'
)
Map workflow
Render Interactive Maps
Interactive vector maps can be created programmatically in CARTOframes. In addition to hosted tables and queries, these maps can also display geographic information in pandas DataFrames and geopandas GeoDataFrames. This means that these maps do not need to be tied to a CARTO account (i.e., no need for an API key).
from cartoframes.viz import Map
from cartoframes.viz.helpers import color_continuous_layer
from cartoframes.auth import set_default_credentials
set_default_credentials('cartoframes')
# display map in a notebook
Map(color_continuous_layer('brooklyn_poverty', 'poverty_per_pop'))
Publish map to CARTO
from cartoframes.viz import Map
from cartoframes.viz.helpers import color_continuous_layer
from cartoframes.auth import set_default_credentials
set_default_credentials(
base_url='https://your_user_name.carto.com',
api_key='your api key'
)
# display map in a notebook
bk_map = Map(color_continuous_layer('brooklyn_poverty', 'poverty_per_pop'))
bk_map.publish('Brooklyn Poverty')
This will publish a map like this one.
CARTO Credential Management
Typical usage
The most common way to input credentials into cartoframes is through the set_default_credentials method, 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.auth import set_default_credentials
set_default_credentials(
filepath='your_creds_file.json'
)
# or
set_default_credentials(
username='{your_user_name}',
api_key='{your_api_key}'
)
When the data we’re going to use is public, we don’t need the api_key parameter, it’s automatically set to default_public:
from cartoframes.auth import set_default_credentials
set_default_credentials('your_user_name')
You can also set your credentials using the base_url parameter:
from cartoframes.auth import set_default_credentials
set_default_credentials(
base_url='https://{your_user_name}.carto.com',
api_key='{your_api_key}'
)
Save/update credentials for later use
from cartoframes.auth import Credentials
credentials = Credentials('{your_user_name}', '{your_api_key}')
credentials.save('path/file/creds.json') # 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.auth import Credentials
credentials = Credentials.from_file('path/file/creds.json') # automatically loads credentials if previously saved
Project details
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
Hashes for cartoframes-1.0b7-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6dfa33359221f466b7c8b5f3243391a460c11e13d6b1461734935ae8a25150cf |
|
MD5 | d223bb53abe8fd366e379af77cc21786 |
|
BLAKE2b-256 | 25c231bebdfdae0ae040727f46257d8cac9a7ef59cd4e03c790ab6171daa4f8d |