Skip to content

Commit

Permalink
Merge 5393595 into 250ec17
Browse files Browse the repository at this point in the history
  • Loading branch information
@oleurud
oleurud committed Jul 26, 2019
2 parents 250ec17 + 5393595 commit f2bcc67
Show file tree
Hide file tree
Showing 8 changed files with 290 additions and 302 deletions.
95 changes: 49 additions & 46 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -223,47 +223,47 @@ Publish map to CARTO
This will publish a map like `this one <https://cartoframes.carto.com/kuviz/2a7badc3-00b3-49d0-9bc8-3b138542cdcf>`__.

CARTO.js-based Maps
^^^^^^^^^^^^^^^^^^^
Data Observatory
----------------

The following will embed a CARTO map in a Jupyter notebook, allowing for custom styling of the maps driven by `TurboCARTO <https://github.com/CartoDB/turbo-carto>`__ and `CARTOColors <https://carto.com/blog/introducing-cartocolors>`__. See the `CARTOColors wiki <https://github.com/CartoDB/CartoColor/wiki/CARTOColor-Scheme-Names>`__ for a full list of available color schemes.
Interact with CARTO's `Data Observatory <https://carto.com/docs/carto-engine/data>`__:

Example: Get census tracts around Idaho Falls, Idaho, USA, and add median income from the US census. Without limiting the metadata, we get median income measures for each census in the Data Observatory.

.. code:: python
from cartoframes import Layer, BaseMap, styling
con = cartoframes.auth.Context(base_url=BASEURL,
api_key=APIKEY)
con.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)
.. image:: https://raw.githubusercontent.com/CartoDB/cartoframes/master/docs/img/map_demo.gif
from cartoframes.auth import set_default_credentials
from cartoframes.client import DataObsClient
Data Observatory
----------------
set_default_credentials(
base_url='https://your_user_name.carto.com',
api_key='your api key'
)
Interact with CARTO's `Data Observatory <https://carto.com/docs/carto-engine/data>`__:
do = DataObsClient()
.. code:: python
# will return Dataset with columns `the_geom` and `geom_ref`
tracts = do.boundaries(
boundary='us.census.tiger.census_tract',
region=[-112.096642,43.429932,-111.974213,43.553539])
import cartoframes
con = cartoframes.auth.Context(BASEURL, APIKEY)
# write geometries to a CARTO table
tracts.upload('idaho_falls_tracts')
# 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 = con.data('transactions', data_obs_measures)
# gather metadata needed to look up median income
median_income_meta = do.discovery(
'idaho_falls_tracts',
keywords='median income',
boundaries='us.census.tiger.census_tract')
# get median income data and original table as new Dataset
idaho_falls_income = do.augment(
'idaho_falls_tracts',
median_income_meta,
how='geom_refs')
# overwrite existing table with newly-enriched Dataset
idaho_falls_income.upload('idaho_falls_tracts', if_exists='replace')
CARTO Credential Management
Expand All @@ -272,24 +272,26 @@ CARTO Credential Management
Typical usage
^^^^^^^^^^^^^

The most common way to input credentials into cartoframes is through the `Context`, 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``.
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``.

.. code:: python
from cartoframes.auth import Context
con = Context(
base_url='https://{your_user_name}.carto.com',
from cartoframes.auth import set_default_credentials
set_default_credentials(
username='{your_user_name}',
api_key='{your_api_key}'
)
You can also set your credentials using the `Credentials` class:
You can also set your credentials using the `base_url` parameter:

.. code:: python
from cartoframes.auth import Credentials, Context
con = Context(
creds=Credentials(api_key='{your_api_key}', username='{your_user_name}')
from cartoframes.auth import set_default_credentials
set_default_credentials(
base_url='https://{your_user_name}.carto.com',
api_key='{your_api_key}'
)
Expand All @@ -298,13 +300,14 @@ Save/update credentials for later use

.. code:: python
from cartoframes.auth import Credentials, Context
creds = Credentials(username='eschbacher', api_key='abcdefg')
creds.save() # save credentials for later use (not dependent on Python session)
from cartoframes.auth import Credentials
credentials = Credentials('{your_user_name}', '{your_api_key}')
credentials.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:

.. code:: python
from cartoframes.auth import Context
con = Context() # automatically loads credentials if previously saved
from cartoframes.auth import Credentials
credentials = Credentials.from_file() # automatically loads credentials if previously saved
124 changes: 64 additions & 60 deletions cartoframes/examples.py
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,8 @@
"""Download, preview, and query example datasets for use in cartoframes
examples. Try examples by `running the notebooks in binder
<https://mybinder.org/v2/gh/CartoDB/cartoframes/master?filepath=examples>`__,
or trying the `Example Datasets notebook
<https://github.com/CartoDB/cartoframes/blob/master/examples/Example%20Datasets.ipynb>`__.
<https://mybinder.org/v2/gh/CartoDB/cartoframes/master?filepath=examples>`__
In addition to the functions listed below, this examples module provides a
:py:class:`Context <cartoframes.auth.Context>` that is
In addition to the functions listed below, this examples module is
authenticated against all public datasets in the https://cartoframes.carto.com
account. This means that besides reading the datasets from CARTO, users can
also create maps from these datasets.
Expand All @@ -15,33 +12,36 @@
.. code::
from cartoframes.examples import example_context
from cartoframes import Layer
example_context.map(Layer('brooklyn_poverty', color='poverty_per_pop'))
from cartoframes.examples import examples
examples.map('brooklyn_poverty')
.. image:: https://cartoframes.carto.com/api/v1/map/static/named/cartoframes_ver20170406_layers1_time0_baseid2_labels1_zoom0/800/400.png?config=%7B%22basemap_url%22%3A+%22https%3A%2F%2F%7Bs%7D.basemaps.cartocdn.com%2Frastertiles%2Fvoyager_nolabels%2F%7Bz%7D%2F%7Bx%7D%2F%7By%7D.png%22%2C+%22cartocss_0%22%3A+%22%23layer+%7B++polygon-fill%3A+ramp%28%5Bpoverty_per_pop%5D%2C+cartocolor%28Mint%29%2C+quantiles%285%29%2C+%3E%29%3B+polygon-opacity%3A+0.9%3B+polygon-gamma%3A+0.5%3B+line-color%3A+%23FFF%3B+line-width%3A+0.5%3B+line-opacity%3A+0.25%3B+line-comp-op%3A+hard-light%3B%7D%23layer%5Bpoverty_per_pop+%3D+null%5D+%7B++polygon-fill%3A+%23ccc%3B%7D%22%2C+%22sql_0%22%3A+%22SELECT+%2A+FROM+brooklyn_poverty%22%7D&anti_cache=0.2903456538919632&bbox=-74.041916%2C40.569596%2C-73.833422%2C40.739158
To query datasets, use the :py:meth:`Context.query
<cartoframes.auth.Context.query>` method. The following example finds
the poverty rate in the census tract a McDonald's fast food joint is located
(preview of static map below code).
To query datasets, use the :py:class:`Dataset <cartoframes.data.Dataset>` class.
The following example finds the poverty rate in the census tract a McDonald's fast
food joint is located (preview of static map below code).
.. code::
from cartoframes.examples import import example_context
from cartoframes.examples import examples
from cartoframes.data import Dataset
# query to get poverty rates where mcdonald's are located in brooklyn
q = '''
SELECT m.the_geom, m.cartodb_id, m.the_geom_webmercator, con.poverty_per_pop
FROM mcdonalds_nyc as m, brooklyn_poverty as c
WHERE ST_Intersects(m.the_geom, con.the_geom)
'''
# get data
df = example_context.query(q)
# visualize data
from cartoframes import QueryLayer
example_context.map(QueryLayer(q, size='poverty_per_pop'))
query = '''
SELECT m.the_geom, m.cartodb_id, m.the_geom_webmercator, c.poverty_per_pop
FROM mcdonalds_nyc as m, brooklyn_poverty as c WHERE ST_Intersects(m.the_geom, c.the_geom)
'''
credentials = examples.get_credentials()
ds = Dataset(query, credentials=credentials)
# download and show the data
ds.download()
ds.dataframe
# map
examples.map(ds)
.. image:: https://cartoframes.carto.com/api/v1/map/static/named/cartoframes_ver20170406_layers1_time0_baseid2_labels0_zoom0/800/400.png?config=%7B%22basemap_url%22%3A+%22https%3A%2F%2F%7Bs%7D.basemaps.cartocdn.com%2Frastertiles%2Fvoyager_labels_under%2F%7Bz%7D%2F%7Bx%7D%2F%7By%7D.png%22%2C+%22cartocss_0%22%3A+%22%23layer+%7B++marker-width%3A+ramp%28%5Bpoverty_per_pop%5D%2C+range%285%2C25%29%2C+quantiles%285%29%29%3B+marker-fill%3A+%235D69B1%3B+marker-fill-opacity%3A+0.9%3B+marker-allow-overlap%3A+true%3B+marker-line-width%3A+0.5%3B+marker-line-color%3A+%23FFF%3B+marker-line-opacity%3A+1%3B%7D%22%2C+%22sql_0%22%3A+%22%5CnSELECT+m.the_geom%2C+m.cartodb_id%2C+m.the_geom_webmercator%2C+c.poverty_per_pop%5CnFROM+mcdonalds_nyc+as+m%2C+brooklyn_poverty+as+c%5CnWHERE+ST_Intersects%28m.the_geom%2C+c.the_geom%29%5Cn%22%7D&anti_cache=0.040403611167980635&bbox=-74.0277516749999%2C40.57955036%2C-73.8603420299999%2C40.7303652850001
Expand All @@ -51,45 +51,43 @@
.. code::
from cartoframes.auth import Context
from cartoframes.auth import Credentials
from cartoframes.data import Dataset
from cartoframes.examples import read_taxi
USERNAME = 'your user name'
APIKEY = 'your API key'
con = Context(
base_url='https://{}.carto.com'.format(USERNAME),
credentials = Credentials(
username=USERNAME,
api_key=APIKEY
)
con.write(
read_taxi(),
'taxi_data_examples_acct',
lnglat=('pickup_latitude', 'pickup_longitude')
)
Dataset(read_taxi()).upload(
table_name='taxi_data_examples_acct',
lnglat=('pickup_latitude', 'pickup_longitude')
credentials=credentials)
""" # noqa
from cartoframes.auth import Credentials
from cartoframes.data import Dataset, tables
from cartoframes.viz import Map, Layer

EXAMPLE_BASE_URL = 'https://cartoframes.carto.com'
EXAMPLE_API_KEY = 'default_public'


class Examples():
"""A Context with a CARTO account containing example data. This
special :py:class:`Context <cartoframes.auth.Context>`
provides read access to all the datasets in the cartoframes CARTO account.
"""This special class provides read access to all the datasets in the cartoframes CARTO account.
The recommended way to use this class is to import the `example_context`
The recommended way to use this class is to import the `examples`
from the `cartoframes.examples` module:
.. code::
from cartoframes.examples import example_context
df = example_context.read_taxi()
from cartoframes.examples import examples
df = examples.read_taxi()
The following tables are available for use with the
:py:meth:`Context.read <cartoframes.auth.Context.read>`,
:py:meth:`Context.map <cartoframes.auth.Context.map>`, and
:py:meth:`Context.query <cartoframes.auth.Context.query>`
methods.
The following tables are available:
- ``brooklyn_poverty`` - basic poverty information for Brooklyn, New York
- ``mcdonalds_nyc`` - McDonald's locations in New York City
Expand All @@ -100,13 +98,11 @@ class Examples():
`pickup_latitude`/`pickup_longitude` columns, the
`dropoff_latitude`/`dropoff_longitude` columns, or through some other
process. When writing this table to your account, make sure to specify
the `lnglat` flag in :py:meth:`Context.write
<cartoframes.auth.Context.write>`
the `lnglat` flag in :py:meth:`Dataset.upload
<cartoframes.data.Dataset.upload>`
Besides the standard :py:class:`Context
<cartoframes.auth.Context>` methods, this class includes a
convenience method for each of the tables listed above. See the full list
below.
This class includes a convenience method for each of the tables listed above.
See the full list below.
"""

Expand Down Expand Up @@ -206,6 +202,12 @@ def read_nat(self, limit=None, **kwargs):
def tables(self):
return tables(self._credentials)

def map(self, source):
return Map(Layer(source, credentials=self._credentials))

def get_credentials(self):
return self._credentials


examples = Examples()

Expand All @@ -220,7 +222,7 @@ def read_ne_50m_graticules_15(limit=None, **kwargs):
limit (int, optional): Limit results to `limit`. Defaults to return all
rows of the original dataset
**kwargs: Arguments accepted in :py:meth:`Context.read <cartoframes.auth.Context.read>`
**kwargs: Arguments accepted in :py:meth:`Dataset.download <cartoframes.data.Dataset.download>`
Returns:
Expand Down Expand Up @@ -252,7 +254,7 @@ def read_brooklyn_poverty(limit=None, **kwargs):
limit (int, optional): Limit results to `limit`. Defaults to return all
rows of the original dataset
**kwargs: Arguments accepted in :py:meth:`Context.read <cartoframes.auth.Context.read>`
**kwargs: Arguments accepted in :py:meth:`Dataset.download <cartoframes.data.Dataset.download>`
Returns:
Expand Down Expand Up @@ -285,7 +287,7 @@ def read_mcdonalds_nyc(limit=None, **kwargs):
limit (int, optional): Limit results to `limit`. Defaults to return all
rows of the original dataset
**kwargs: Arguments accepted in :py:meth:`Context.read <cartoframes.auth.Context.read>`
**kwargs: Arguments accepted in :py:meth:`Dataset.download <cartoframes.data.Dataset.download>`
Returns:
Expand Down Expand Up @@ -318,7 +320,7 @@ def read_nyc_census_tracts(limit=None, **kwargs):
limit (int, optional): Limit results to `limit`. Defaults to return all
rows of the original dataset
**kwargs: Arguments accepted in :py:meth:`Context.read <cartoframes.auth.Context.read>`
**kwargs: Arguments accepted in :py:meth:`Dataset.download <cartoframes.data.Dataset.download>`
Returns:
Expand Down Expand Up @@ -346,12 +348,16 @@ def read_taxi(limit=None, **kwargs):
.. note:: This dataset does not have geometries. The geometries have to be
created by using the pickup or drop-off lng/lat pairs. These can be
specified in `Context.write`.
specified in `Dataset.upload`.
To create geometries with `example_context.query`, write a query such
To create geometries with `examples.query`, write a query such
as this::
example_context.query('''
from cartoframes.client import SQLClient
sql = SQLClient(examples.get_credentials())
sql.query('''
SELECT
CDB_LatLng(pickup_latitude, pickup_longitude) as the_geom,
cartodb_id,
Expand All @@ -369,8 +375,7 @@ def read_taxi(limit=None, **kwargs):
limit (int, optional): Limit results to `limit`. Defaults to return all
rows of the original dataset
**kwargs: Arguments accepted in :py:meth:`Context.read
<cartoframes.auth.Context.read>`
**kwargs: Arguments accepted in :py:meth:`Dataset.download <cartoframes.data.Dataset.download>`
Returns:
Expand Down Expand Up @@ -402,8 +407,7 @@ def read_nat(limit=None, **kwargs):
limit (int, optional): Limit results to `limit`. Defaults to return all
rows of the original dataset
**kwargs: Arguments accepted in :py:meth:`Context.read
<cartoframes.auth.Context.read>`
**kwargs: Arguments accepted in :py:meth:`Dataset.download <cartoframes.data.Dataset.download>`
Returns:
Expand Down
Loading

0 comments on commit f2bcc67

Please sign in to comment.