cartoframes.layer module¶
Layer classes for map creation. See examples in layer.Layer and layer.QueryLayer for example usage for data layers. See layer.BaseMap for basemap layers.
-
class
cartoframes.layer.
BaseMap
(source='voyager', labels='back', only_labels=False)¶ Bases:
cartoframes.layer.AbstractLayer
Layer object for adding basemaps to a cartoframes map.
Example
Add a custom basemap to a cartoframes map.
import cartoframes from cartoframes import BaseMap, Layer cc = cartoframes.CartoContext(BASEURL, APIKEY) cc.map(layers=[BaseMap(source='light', labels='front'), Layer('acadia_biodiversity')])
Parameters: - source (str, optional) – One of
light
ordark
. Defaults tovoyager
. Basemaps come from https://carto.com/location-data-services/basemaps/ - labels (str, optional) – One of
back
,front
, or None. Labels on the front will be above the data layers. Labels on back will be underneath the data layers but on top of the basemap. Setting labels toNone
will only show the basemap. - only_labels (bool, optional) – Whether to show labels or not.
-
is_basemap
= True¶
-
is_basic
()¶ Does BaseMap pull from CARTO default basemaps?
Returns: True if using a CARTO basemap (Dark Matter, Positron or Voyager), False otherwise. Return type: bool
- source (str, optional) – One of
-
class
cartoframes.layer.
Layer
(table_name, source=None, overwrite=False, time=None, color=None, size=None, opacity=None, tooltip=None, legend=None)¶ Bases:
cartoframes.layer.QueryLayer
A cartoframes Data Layer based on a specific table in user’s CARTO database. This layer class is used for visualizing individual datasets with
CartoContext.map
’s layers keyword argument.Example
import cartoframes from cartoframes import QueryLayer, styling cc = cartoframes.CartoContext(BASEURL, APIKEY) cc.map(layers=[Layer('fantastic_sql_table', size=7, color={'column': 'mr_fox_sightings', 'scheme': styling.prism(10)})])
Parameters: - table_name (str) – Name of table in CARTO account
- Styling – See
QueryLayer
- a full list of all arguments arguments for styling this map data (for) –
- layer. –
- source (pandas.DataFrame, optional) – Not currently implemented
- overwrite (bool, optional) – Not currently implemented
-
class
cartoframes.layer.
QueryLayer
(query, time=None, color=None, size=None, opacity=None, tooltip=None, legend=None)¶ Bases:
cartoframes.layer.AbstractLayer
cartoframes data layer based on an arbitrary query to the user’s CARTO database. This layer class is useful for offloading processing to the cloud to do some of the following:
- Visualizing spatial operations using PostGIS and PostgreSQL, which is the database underlying CARTO
- Performing arbitrary relational database queries (e.g., complex JOINs in SQL instead of in pandas)
- Visualizing a subset of the data (e.g.,
SELECT * FROM table LIMIT 1000
)
Used in the layers keyword in
CartoContext.map
.Example
Underlay a QueryLayer with a complex query below a layer from a table. The QueryLayer is colored by the calculated column
abs_diff
, and points are sized by the columni_measure
.import cartoframes from cartoframes import QueryLayer, styling cc = cartoframes.CartoContext(BASEURL, APIKEY) cc.map(layers=[QueryLayer(''' WITH i_cte As ( SELECT ST_Buffer(the_geom::geography, 500)::geometry As the_geom, cartodb_id, measure, date FROM interesting_data WHERE date > '2017-04-19' ) SELECT i.cartodb_id, i.the_geom, ST_Transform(i.the_geom, 3857) AS the_geom_webmercator, abs(i.measure - j.measure) AS abs_diff, i.measure AS i_measure FROM i_cte AS i JOIN awesome_data AS j ON i.event_id = j.event_id WHERE j.measure IS NOT NULL AND j.date < '2017-04-29' ''', color={'column': 'abs_diff', 'scheme': styling.sunsetDark(7)}, size='i_measure'), Layer('fantastic_sql_table')])
Parameters: - query (str) – Query to expose data on a map layer. At a minimum, a query needs to have the columns cartodb_id, the_geom, and the_geom_webmercator for the map to display. Read more about queries in CARTO’s docs.
- time (dict or str, optional) –
Time-based style to apply to layer.
If time is a
str
, it must be the name of a column which has a data type of datetime or float.from cartoframes import QueryLayer l = QueryLayer('SELECT * FROM acadia_biodiversity', time='bird_sighting_time')
If time is a
dict
, the following keys are options:- column (str, required): Column for animating map, which must be of type datetime or float.
- method (str, optional): Type of aggregation method for
operating on Torque TileCubes. Must be one of
avg
,sum
, or another PostgreSQL aggregate functions with a numeric output. Defaults tocount
. - cumulative (
bool
, optional): Whether to accumulate points over time (True
) or not (False
, default) - frames (int, optional): Number of frames in the animation. Defaults to 256.
- duration (int, optional): Number of seconds in the animation. Defaults to 30.
- trails (int, optional): Number of trails after the incidence of a point. Defaults to 2.
from cartoframes import Layer l = Layer('acadia_biodiversity', time={ 'column': 'bird_sighting_time', 'cumulative': True, 'frames': 128, 'duration': 15 })
- color (dict or str, optional) –
Color style to apply to map. For example, this can be used to change the color of all geometries in this layer, or to create a graduated color or choropleth map.
If color is a
str
, there are two options:- A column name to style by to create, for example, a choropleth map if working with polygons. The default classification is quantiles for quantitative data and category for qualitative data.
- A hex value or web color name.
# color all geometries red (#F00) from cartoframes import Layer l = Layer('acadia_biodiversity', color='red') # color on 'num_eggs' (using defalt color scheme and quantification) l = Layer('acadia_biodiversity', color='num_eggs')
If color is a
dict
, the following keys are options, with values described:- column (str): Column used for the basis of styling
- scheme (dict, optional): Scheme such as styling.sunset(7)
from the styling module of cartoframes that
exposes CARTOColors.
Defaults to mint scheme for quantitative
data and bold for qualitative data. More control is given by
using styling.scheme.
If you wish to define a custom scheme outside of CARTOColors, it is recommended to use the styling.custom utility function.
from cartoframes import QueryLayer, styling l = QueryLayer('SELECT * FROM acadia_biodiversity', color={ 'column': 'simpson_index', 'scheme': styling.mint(7, bin_method='equal') })
- size (dict or int, optional) –
Size style to apply to point data.
If size is an
int
, all points are sized by this value.from cartoframes import QueryLayer l = QueryLayer('SELECT * FROM acadia_biodiversity', size=7)
If size is a
str
, this value is interpreted as a column, and the points are sized by the value in this column. The classification method defaults to quantiles, with a min size of 5, and a max size of 5. Use thedict
input to override these values.from cartoframes import Layer l = Layer('acadia_biodiversity', size='num_eggs')
If size is a
dict
, the follow keys are options, with values described as:- column (str): Column to base sizing of points on
- bin_method (str, optional): Quantification method for dividing
data range into bins. Must be one of the methods in
BinMethod
(excluding category). - bins (int, optional): Number of bins to break data into. Defaults to 5.
- max (int, optional): Maximum point width (in pixels). Setting this overrides range. Defaults to 25.
- min (int, optional): Minimum point width (in pixels). Setting this overrides range. Defaults to 5.
- range (tuple or list, optional): a min/max pair. Defaults to [1, 5] for lines and [5, 25] for points.
from cartoframes import Layer l = Layer('acadia_biodiversity', size={ 'column': 'num_eggs', 'max': 10, 'min': 2 })
- opacity (float, optional) – Opacity of layer from 0 to 1. Defaults to 0.9.
- tooltip (tuple, optional) – Not yet implemented.
- legend – Not yet implemented.
Raises: - CartoException – If a column name used in any of the styling options is
not in the data source in query (or table if using
Layer
). - ValueError – If styling using a
dict
and acolumn
key is not present, or if the data type for a styling option is not supported. This is also raised if styling by a geometry column (i.e.,the_geom
orthe_geom_webmercator
). Futher, this is raised if requesting a time-based map with a data source that has geometries other than points.