diff --git a/cartoframes/__version__.py b/cartoframes/__version__.py index d2cd642a7..f3fad9939 100644 --- a/cartoframes/__version__.py +++ b/cartoframes/__version__.py @@ -1 +1 @@ -__version__ = '0.2.4b4' +__version__ = '0.3.0b5' diff --git a/cartoframes/context.py b/cartoframes/context.py index 71f55d1fe..405b7f45b 100644 --- a/cartoframes/context.py +++ b/cartoframes/context.py @@ -58,22 +58,18 @@ class CartoContext(object): """CartoContext class for authentication with CARTO and high-level operations such as reading tables from CARTO into dataframes, writing dataframes to - CARTO tables, and creating custom maps from dataframes and CARTO tables. - Future methods interact with CARTO's services like - `Data Observatory `__, and `routing, - geocoding, and isolines `__. + CARTO tables, creating custom maps from dataframes and CARTO tables, and + augmenting data using CARTO's `Data Observatory + `__. Future methods will interact with + CARTO's services like `routing, geocoding, and isolines + `__, PostGIS backend for spatial + processing, and much more. Manages connections with CARTO for data and map operations. Modeled after `SparkContext `__. - Example: - Create a CartoContext object:: - - import cartoframes - cc = cartoframes.CartoContext(BASEURL, APIKEY) - - Attrs: + Attributes: creds (cartoframes.Credentials): :obj:`Credentials` instance Args: @@ -92,6 +88,12 @@ class CartoContext(object): Returns: :obj:`CartoContext`: A CartoContext object that is authenticated against the user's CARTO account. + + Example: + Create a CartoContext object:: + + import cartoframes + cc = cartoframes.CartoContext(BASEURL, APIKEY) """ def __init__(self, base_url=None, api_key=None, creds=None, session=None, verbose=0): @@ -118,24 +120,28 @@ def _is_org_user(self): def read(self, table_name, limit=None, index='cartodb_id', decode_geom=False): - """Read tables from CARTO into pandas DataFrames. - - Example: - .. code:: python - - import cartoframes - cc = cartoframes.CartoContext(BASEURL, APIKEY) - df = cc.read('acadia_biodiversity') + """Read a table from CARTO into a pandas DataFrames. Args: table_name (str): Name of table in user's CARTO account. - limit (int, optional): Read only ``limit`` lines from - ``table_name``. Defaults to `None`, which reads the full table. + limit (int, optional): Read only `limit` lines from + `table_name`. Defaults to ``None``, which reads the full table. index (str, optional): Not currently in use. + decode_geom (bool, optional): Decodes CARTO's geometries into a + `Shapely `__ + object that can be used, for example, in `GeoPandas + `__. Returns: pandas.DataFrame: DataFrame representation of `table_name` from CARTO. + + Example: + .. code:: python + + import cartoframes + cc = cartoframes.CartoContext(BASEURL, APIKEY) + df = cc.read('acadia_biodiversity') """ query = 'SELECT * FROM "{table_name}"'.format(table_name=table_name) if limit is not None: @@ -572,15 +578,21 @@ def query(self, query, table_name=None, decode_geom=False): operations (creating/dropping tables, adding columns, updates, etc.). Args: - query (str): Query to run against CARTO user database. + query (str): Query to run against CARTO user database. This data + will then be converted into a pandas DataFrame. table_name (str, optional): If set, this will create a new - table in the user's CARTO account that is the result of the - query. Defaults to None (no table created). + table in the user's CARTO account that is the result of the + query. Defaults to None (no table created). + decode_geom (bool, optional): Decodes CARTO's geometries into a + `Shapely `__ + object that can be used, for example, in `GeoPandas + `__. + Returns: pandas.DataFrame: DataFrame representation of query supplied. Pandas data types are inferred from PostgreSQL data types. - In the case of PostgreSQL date types, the data type 'object' is - used. + In the case of PostgreSQL date types, dates are attempted to be + converted, but on failure a data type 'object' is used. """ self._debug_print(query=query) if table_name: @@ -695,8 +707,9 @@ def map(self, layers=None, interactive=True, ``interactive`` is ``False``. Returns: - IPython.display.HTML: Interactive maps are rendered in an - ``iframe``, while static maps are rendered in ``img`` tags. + IPython.display.HTML or matplotlib Axes: Interactive maps are + rendered as HTML in an `iframe`, while static maps are returned as + matplotlib Axes objects or IPython Image. """ # TODO: add layers preprocessing method like # layers = process_layers(layers) diff --git a/cartoframes/layer.py b/cartoframes/layer.py index e3977e7d8..b26d39e12 100644 --- a/cartoframes/layer.py +++ b/cartoframes/layer.py @@ -1,6 +1,7 @@ """Layer classes for map creation. See examples in `layer.Layer <#layer.Layer>`__ and `layer.QueryLayer <#layer.QueryLayer>`__ -for example usage. +for example usage for data layers. See `layer.BaseMap <#layer.BaseMap>`__ for +basemap layers. """ import pandas as pd @@ -194,6 +195,7 @@ class QueryLayer(AbstractLayer): If `color` is a :obj:`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 <#module-styling>`__ of cartoframes that diff --git a/docs/_sources/index.rst.txt b/docs/_sources/index.rst.txt index 83ce90fee..48b432323 100644 --- a/docs/_sources/index.rst.txt +++ b/docs/_sources/index.rst.txt @@ -9,18 +9,23 @@ :maxdepth: 2 :caption: Contents: + modules + CARTOFrames Functionality ========================= CartoContext ------------ .. autoclass:: context.CartoContext - :members: + :member-order: bysource + :members: read, query, delete, map, data_augment + + .. automethod:: write(df, table_name, temp_dir=SYSTEM_TMP_PATH, overwrite=False, lnglat=None, encode_geom=False, geom_col=None, \*\*kwargs) Map Layer Classes ----------------- .. automodule:: layer - :members: + :members: BaseMap, Layer, QueryLayer Map Styling Functions --------------------- @@ -43,3 +48,5 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +:Version: |version| diff --git a/docs/_static/basic.css b/docs/_static/basic.css index 6df76b0a6..3c7223b17 100644 --- a/docs/_static/basic.css +++ b/docs/_static/basic.css @@ -445,10 +445,14 @@ dd { margin-left: 30px; } -dt:target, .highlighted { +dt:target, span.highlighted { background-color: #fbe54e; } +rect.highlighted { + fill: #fbe54e; +} + dl.glossary dt { font-weight: bold; font-size: 1.1em; diff --git a/docs/_static/doctools.js b/docs/_static/doctools.js index 565497723..24992e644 100644 --- a/docs/_static/doctools.js +++ b/docs/_static/doctools.js @@ -45,7 +45,7 @@ jQuery.urlencode = encodeURIComponent; * it will always return arrays of strings for the value parts. */ jQuery.getQueryParameters = function(s) { - if (typeof s == 'undefined') + if (typeof s === 'undefined') s = document.location.search; var parts = s.substr(s.indexOf('?') + 1).split('&'); var result = {}; @@ -66,29 +66,53 @@ jQuery.getQueryParameters = function(s) { * span elements with the given class name. */ jQuery.fn.highlightText = function(text, className) { - function highlight(node) { - if (node.nodeType == 3) { + function highlight(node, addItems) { + if (node.nodeType === 3) { var val = node.nodeValue; var pos = val.toLowerCase().indexOf(text); if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { - var span = document.createElement("span"); - span.className = className; + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } span.appendChild(document.createTextNode(val.substr(pos, text.length))); node.parentNode.insertBefore(span, node.parentNode.insertBefore( document.createTextNode(val.substr(pos + text.length)), node.nextSibling)); node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var bbox = span.getBBox(); + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + var parentOfText = node.parentNode.parentNode; + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } } } else if (!jQuery(node).is("button, select, textarea")) { jQuery.each(node.childNodes, function() { - highlight(this); + highlight(this, addItems); }); } } - return this.each(function() { - highlight(this); + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; }; /* @@ -131,21 +155,21 @@ var Documentation = { * i18n support */ TRANSLATIONS : {}, - PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, LOCALE : 'unknown', // gettext and ngettext don't access this so that the functions // can safely bound to a different name (_ = Documentation.gettext) gettext : function(string) { var translated = Documentation.TRANSLATIONS[string]; - if (typeof translated == 'undefined') + if (typeof translated === 'undefined') return string; - return (typeof translated == 'string') ? translated : translated[0]; + return (typeof translated === 'string') ? translated : translated[0]; }, ngettext : function(singular, plural, n) { var translated = Documentation.TRANSLATIONS[singular]; - if (typeof translated == 'undefined') + if (typeof translated === 'undefined') return (n == 1) ? singular : plural; return translated[Documentation.PLURALEXPR(n)]; }, @@ -216,7 +240,7 @@ var Documentation = { var src = $(this).attr('src'); var idnum = $(this).attr('id').substr(7); $('tr.cg-' + idnum).toggle(); - if (src.substr(-9) == 'minus.png') + if (src.substr(-9) === 'minus.png') $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); else $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); @@ -248,7 +272,7 @@ var Documentation = { var path = document.location.pathname; var parts = path.split(/\//); $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { - if (this == '..') + if (this === '..') parts.pop(); }); var url = parts.join('/'); diff --git a/docs/_static/searchtools.js b/docs/_static/searchtools.js index c82157380..33fedf43e 100644 --- a/docs/_static/searchtools.js +++ b/docs/_static/searchtools.js @@ -540,6 +540,9 @@ var Search = { }); } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { var suffix = DOCUMENTATION_OPTIONS.SOURCELINK_SUFFIX; + if (suffix === undefined) { + suffix = '.txt'; + } $.ajax({url: DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + item[5] + (item[5].slice(-suffix.length) === suffix ? '' : suffix), dataType: "text", complete: function(jqxhr, textstatus) { diff --git a/docs/cartoframes.context.html b/docs/cartoframes.context.html index 2396e07e0..9bf254b88 100644 --- a/docs/cartoframes.context.html +++ b/docs/cartoframes.context.html @@ -5,13 +5,13 @@ - cartoframes.context module — cartoframes 0.0.1 documentation + cartoframes.context module — cartoframes 0.3.0b5 documentation + + @@ -122,22 +124,18 @@

Bases: object

CartoContext class for authentication with CARTO and high-level operations such as reading tables from CARTO into dataframes, writing dataframes to -CARTO tables, and creating custom maps from dataframes and CARTO tables. -Future methods interact with CARTO’s services like -Data Observatory, and routing, -geocoding, and isolines.

+CARTO tables, creating custom maps from dataframes and CARTO tables, and +augmenting data using CARTO’s Data Observatory. Future methods will interact with +CARTO’s services like routing, geocoding, and isolines, PostGIS backend for spatial +processing, and much more.

Manages connections with CARTO for data and map operations. Modeled after SparkContext.

-

Example

-

Create a CartoContext object:

-
import cartoframes
-cc = cartoframes.CartoContext(BASEURL, APIKEY)
-
-
-
-
Attrs:
-
creds (cartoframes.Credentials): Credentials instance
-
+
+
+creds
+

cartoframes.Credentials – Credentials instance

+
+ @@ -165,6 +163,12 @@
+

Example

+

Create a CartoContext object:

+
import cartoframes
+cc = cartoframes.CartoContext(BASEURL, APIKEY)
+
+
data_augment(table_name, metadata)
@@ -343,11 +347,12 @@ -Returns:

Interactive maps are rendered in an -iframe, while static maps are rendered in img tags.

+Returns:

Interactive maps are +rendered as HTML in an iframe, while static maps are returned as +matplotlib Axes objects or IPython Image.

-Return type:

IPython.display.HTML

+Return type:

IPython.display.HTML or matplotlib Axes

@@ -365,17 +370,21 @@ Parameters:
    -
  • query (str) – Query to run against CARTO user database.
    • +
  • query (str) – Query to run against CARTO user database. This data +will then be converted into a pandas DataFrame.
  • table_name (str, optional) – If set, this will create a new table in the user’s CARTO account that is the result of the query. Defaults to None (no table created).
    • +
  • decode_geom (bool, optional) – Decodes CARTO’s geometries into a +Shapely +object that can be used, for example, in GeoPandas.
Returns:

DataFrame representation of query supplied. Pandas data types are inferred from PostgreSQL data types. -In the case of PostgreSQL date types, the data type ‘object’ is -used.

+In the case of PostgreSQL date types, dates are attempted to be +converted, but on failure a data type ‘object’ is used.

Return type:

pandas.DataFrame

@@ -388,22 +397,19 @@
read(table_name, limit=None, index='cartodb_id', decode_geom=False)
-

Read tables from CARTO into pandas DataFrames.

-

Example

-
import cartoframes
-cc = cartoframes.CartoContext(BASEURL, APIKEY)
-df = cc.read('acadia_biodiversity')
-
-
+

Read a table from CARTO into a pandas DataFrames.

@@ -416,6 +422,12 @@
Parameters:
  • table_name (str) – Name of table in user’s CARTO account.
    • -
  • limit (int, optional) – Read only limit lines from -table_name. Defaults to None, which reads the full table.
    • +
  • limit (int, optional) – Read only limit lines from +table_name. Defaults to None, which reads the full table.
  • index (str, optional) – Not currently in use.
    • +
  • decode_geom (bool, optional) – Decodes CARTO’s geometries into a +Shapely +object that can be used, for example, in GeoPandas.
+

Example

+
import cartoframes
+cc = cartoframes.CartoContext(BASEURL, APIKEY)
+df = cc.read('acadia_biodiversity')
+
+
@@ -433,7 +445,7 @@
-write(df, table_name, temp_dir='/tmp', overwrite=False, lnglat=None, encode_geom=False, geom_col=None, **kwargs)
+write(df, table_name, temp_dir='/Users/peschbacher/Library/Caches/cartoframes', overwrite=False, lnglat=None, encode_geom=False, geom_col=None, **kwargs)

Write a DataFrame to a CARTO table.

Example

Write a pandas DataFrame to CARTO.

@@ -444,8 +456,15 @@ guessing to create a geometry from the country column. This uses a CARTO Import API param content_guessing parameter.

url = 'https://en.wikipedia.org/wiki/List_of_countries_by_life_expectancy'
+# retrieve first HTML table from that page
 df = pd.read_html(url, header=0)[0]
-cc.write(df, 'life_expectancy', content_guessing=True)
+# send to carto, let it guess polygons based on the 'country'
+#   column. Also set privacy to 'public'
+cc.write(df, 'life_expectancy',
+         content_guessing=True,
+         privacy='public')
+cc.map(layers=Layer('life_expectancy',
+                    color='both_sexes_life_expectancy'))
@@ -489,6 +508,12 @@
+
+

Note

+

DataFrame indexes are changed to ordinary columns. CARTO creates +an index called cartodb_id for every table that runs from 1 to +the length of the DataFrame.

+
@@ -504,6 +529,12 @@

Related Topics

@@ -532,7 +563,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/cartoframes.credentials.html b/docs/cartoframes.credentials.html index 8b31488cf..39acf1b75 100644 --- a/docs/cartoframes.credentials.html +++ b/docs/cartoframes.credentials.html @@ -5,13 +5,13 @@ - cartoframes.credentials module — cartoframes 0.0.1 documentation + cartoframes.credentials module — cartoframes 0.3.0b5 documentation + + @@ -276,6 +278,12 @@

Related Topics

@@ -304,7 +312,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/cartoframes.html b/docs/cartoframes.html index 1c53dc6ca..d533f86b3 100644 --- a/docs/cartoframes.html +++ b/docs/cartoframes.html @@ -5,13 +5,13 @@ - cartoframes package — cartoframes 0.0.1 documentation + cartoframes package — cartoframes 0.3.0b5 documentation + + @@ -76,6 +78,10 @@

Table Of Contents

Related Topics

@@ -104,7 +110,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/cartoframes.layer.html b/docs/cartoframes.layer.html index 304f97a98..b1489a439 100644 --- a/docs/cartoframes.layer.html +++ b/docs/cartoframes.layer.html @@ -5,13 +5,13 @@ - cartoframes.layer module — cartoframes 0.0.1 documentation + cartoframes.layer module — cartoframes 0.3.0b5 documentation + + @@ -41,7 +43,8 @@

cartoframes.layer module

Layer classes for map creation. See examples in layer.Layer and layer.QueryLayer -for example usage.

+for example usage for data layers. See layer.BaseMap for +basemap layers.

class cartoframes.layer.AbstractLayer
@@ -115,8 +118,9 @@ class cartoframes.layer.Layer(table_name, source=None, overwrite=False, time=None, color=None, size=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 useful for visualizing individual datasets -with CartoContext.map().

+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
@@ -127,24 +131,38 @@
                             'scheme': styling.prism(10)})])
-

Parameters: See QueryLayer for a full list of arguments.

+ +++ + + + +
Parameters:
    +
  • table_name (str) – Name of table in CARTO account
    • +
  • Styling – See QueryLayer for a full list of all arguments +arguments for styling this map data 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, tooltip=None, legend=None)

Bases: cartoframes.layer.AbstractLayer

-

cartoframes Data Layer based on an arbitrary query to the user’s CARTO +

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:

    -
  • pull down a snapshot of the data (e.g., selecting only important columns -instead of all columns in the dataset)
    • -
  • doing spatial processing using PostGIS and -PostgreSQL, which is the database +
  • Visualizing spatial operations using PostGIS +and PostgreSQL, which is the database underlying CARTO
    • -
  • performing arbitrary relational database queries (e.g., complex JOINs +
  • 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

@@ -186,62 +204,77 @@ Parameters:
    -
  • query (str) – Query that is fed into a pandas DataFrame. At a minimum, -all queries need to have the columns cartodb_id, the_geom, and -the_geom_webmercator. Read more in -CARTO’s docs -for more information.
    • -
  • time (dict or str, optional) –

    Style to apply to layer. -If time is a dict, the following keys are options:

    +
  • 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.

    +

    If time is a dict, the following keys are options:

      -
    • column (str, required): Column for animating map from. Data must +
    • 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 +
    • 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 to count.
      • -
    • cumulative (bool, optional): Whether to accumulate points over +
    • cumulative (bool, optional): Whether to accumulate points over time (True) or not (False, default)
      • -
    • frames (int, optional): Number of frames in the animation. +
    • frames (int, optional): Number of frames in the animation. Defaults to 256.
      • -
    • duration (int, optional): Number of seconds in the animation. +
    • duration (int, optional): Number of seconds in the animation. Defaults to 30.
      • -
    • trails (int, optional): Number of trails after the incidence of +
    • trails (int, optional): Number of trails after the incidence of a point. Defaults to 2.
    -

    If time is a str, then it must be a column name available in -the query that is of type numeric or datetime.

    • -
  • color (dict or str, optional) –

    Color style to apply to map. -If color is a dict, the following keys are options, with +

  • 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.
      • +
    +

    If color is a dict, the following keys are options, with values described:

      -
    • column (str): Column to base coloring from.
      • -
    • scheme (str, optinal): Color scheme from -CartoColors. -Defaults to Mint.
      • -
    • bin_method (str, optional): Quantification method for dividing -data range into bins. Must be one of: quantiles, equal, -headtails, or jenks. Defaults to quantiles.
      • -
    • bins (int, optional): Number of bins to divide data amongst in -the bin_method. Defaults to 5.
      • +
    • 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.

      +
    • -
  • size (dict or int, optional) –

    Size style to apply to point data. -If size is a dict, the follow keys are options, with values -described as:

    +
  • size (dict or int, optional) –

    Size style to apply to point data.

    +

    If size is an int, all points are sized by this value.

    +

    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 the dict input to override these +values.

    +

    If size is a dict, the follow keys are options, with +values described as:

      -
    • column (str): Column to base sizing of points on
      • +
    • 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: quantiles, equal, -headtails, or jenks. Defaults to quantiles.
      • -
    • bins (int, optional): Number of bins to break data into. Defaults +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). Defaults +to 25.
      • +
    • min (int, optional): Minimum point width (in pixels). Defaults to 5.
      • -
    • max (int, optional): Maximum point width (in pixels). Defaults to -25.
      • -
    • min (int, optional): Minimum point width (in pixels). Defaults to -5.
  • tooltip (tuple, optional) – Not yet implemented.
    • @@ -264,6 +297,12 @@

    Related Topics

@@ -292,7 +331,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/cartoframes.maps.html b/docs/cartoframes.maps.html index 18d567745..7207af6af 100644 --- a/docs/cartoframes.maps.html +++ b/docs/cartoframes.maps.html @@ -5,13 +5,13 @@ - cartoframes.maps module — cartoframes 0.0.1 documentation + cartoframes.maps module — cartoframes 0.3.0b5 documentation + + @@ -77,6 +79,12 @@

Related Topics

@@ -105,7 +113,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/cartoframes.styling.html b/docs/cartoframes.styling.html index 6ed640862..79eb6deb0 100644 --- a/docs/cartoframes.styling.html +++ b/docs/cartoframes.styling.html @@ -5,13 +5,13 @@ - cartoframes.styling module — cartoframes 0.0.1 documentation + cartoframes.styling module — cartoframes 0.3.0b5 documentation + + @@ -47,29 +49,60 @@
class cartoframes.styling.BinMethod

Bases: object

+

Data classification methods used for the styling of data on maps.

+
+
+quantiles
+

str – Quantiles classification for quantitative data

+
+ +
+
+jenks
+

str – Jenks classification for quantitative data

+
+ +
+
+headtails
+

str – Head/Tails classification for quantitative data

+
+ +
+
+equal
+

str – Equal Interval classification for quantitative data

+
+
-category = 'category'
+category +

str – Category classification for qualitative data

+
+ +
+
+category = 'category'
-
-equal = 'equal'
+
+equal = 'equal'
-
-headtails = 'headtails'
+
+headtails = 'headtails'
-
-jenks = 'jenks'
+
+jenks = 'jenks'
-
-quantiles = 'quantiles'
+
+quantiles = 'quantiles'
@@ -125,7 +158,23 @@
cartoframes.styling.custom(colors, bins=None, bin_method='quantiles')
-

Get custom scheme

+

Create a custom scheme.

+ +++ + + + +
Parameters:
    +
  • colors (list of str) – List of hex values for styling data
    • +
  • bins (int, optional) – Number of bins to style by. If not given, the +number of colors will be used.
    • +
  • bin_method (str, optional) – Classification method. One of the values +in BinMethod. Defaults to quantiles, which only works with +quantitative data.
    • +
+
@@ -230,6 +279,32 @@

CartoColor Safe qualitative scheme

+
+
+cartoframes.styling.scheme(name, bins, bin_method)
+

Return a custom scheme based on CartoColors.

+ +++ + + + +
Parameters:
    +
  • name (str) – Name of a CartoColor.
    • +
  • bins (int) – Number of bins for classifying data. CartoColors have 7 +bins max for quantitative data, and 11 max for qualitative data.
    • +
  • bin_method (str) – One of methods in BinMethod.
    • +
+
+
+

Warning

+

Input types are particularly sensitive in this function, and little +feedback is given for errors. name and bin_method arguments +are case-sensitive.

+
+
+
cartoframes.styling.sunset(bins, bin_method='quantiles')
@@ -289,6 +364,12 @@

Related Topics

@@ -317,7 +398,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/cartoframes.utils.html b/docs/cartoframes.utils.html index 48e518c9d..a5325eef5 100644 --- a/docs/cartoframes.utils.html +++ b/docs/cartoframes.utils.html @@ -5,13 +5,13 @@ - cartoframes.utils module — cartoframes 0.0.1 documentation + cartoframes.utils module — cartoframes 0.3.0b5 documentation + @@ -119,6 +120,11 @@

Related Topics

@@ -147,7 +153,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/doctrees/cartoframes.context.doctree b/docs/doctrees/cartoframes.context.doctree index b28f97985..15870b6cb 100644 Binary files a/docs/doctrees/cartoframes.context.doctree and b/docs/doctrees/cartoframes.context.doctree differ diff --git a/docs/doctrees/cartoframes.layer.doctree b/docs/doctrees/cartoframes.layer.doctree index 5d178af76..6fab92615 100644 Binary files a/docs/doctrees/cartoframes.layer.doctree and b/docs/doctrees/cartoframes.layer.doctree differ diff --git a/docs/doctrees/cartoframes.styling.doctree b/docs/doctrees/cartoframes.styling.doctree index 6c1ca3fcd..2dee22173 100644 Binary files a/docs/doctrees/cartoframes.styling.doctree and b/docs/doctrees/cartoframes.styling.doctree differ diff --git a/docs/doctrees/environment.pickle b/docs/doctrees/environment.pickle index defc27f8b..a006a5f22 100644 Binary files a/docs/doctrees/environment.pickle and b/docs/doctrees/environment.pickle differ diff --git a/docs/doctrees/index.doctree b/docs/doctrees/index.doctree index ce824cd25..3ecbc7bd6 100644 Binary files a/docs/doctrees/index.doctree and b/docs/doctrees/index.doctree differ diff --git a/docs/genindex.html b/docs/genindex.html index 387cffaf7..50b8f9c25 100644 --- a/docs/genindex.html +++ b/docs/genindex.html @@ -6,13 +6,13 @@ - Index — cartoframes 0.0.1 documentation + Index — cartoframes 0.3.0b5 documentation + @@ -164,6 +165,13 @@

CARTO Credential Management +

Contents:

+ @@ -176,22 +184,18 @@

CartoContextclass context.CartoContext(base_url=None, api_key=None, creds=None, session=None, verbose=0)

CartoContext class for authentication with CARTO and high-level operations such as reading tables from CARTO into dataframes, writing dataframes to -CARTO tables, and creating custom maps from dataframes and CARTO tables. -Future methods interact with CARTO’s services like -Data Observatory, and routing, -geocoding, and isolines.

+CARTO tables, creating custom maps from dataframes and CARTO tables, and +augmenting data using CARTO’s Data Observatory. Future methods will interact with +CARTO’s services like routing, geocoding, and isolines, PostGIS backend for spatial +processing, and much more.

Manages connections with CARTO for data and map operations. Modeled after SparkContext.

-

Example

-

Create a CartoContext object:

-
import cartoframes
-cc = cartoframes.CartoContext(BASEURL, APIKEY)
-
-
-
-
Attrs:
-
creds (cartoframes.Credentials): Credentials instance
-
+
+
+creds
+

cartoframes.Credentials – Credentials instance

+
+ @@ -214,39 +218,39 @@

CartoContext

Return type:

CartoContext

+
Return type:

CartoContext
-
-
-data_augment(table_name, metadata)
-

Augment an existing CARTO table with Data Observatory measures. See the full Data -Observatory catalog for all available -measures. The result of this operation is:

-
    -
  1. It updates table_name by adding columns from the Data Observatory
    2. -
  2. It returns a pandas DataFrame representation of that newly augmented -table.
    3. -
-
-

Note

-

This method alters table_name in the user’s CARTO database by -adding additional columns. To avoid this, create a copy of the -table first and use the new copy instead.

-

Example

-

Add new measures to a CARTO table and pass it to a pandas -DataFrame. Using the “Median Household Income in the past 12 -months” measure from the Data Observatory Catalog.

+

Create a CartoContext object:

import cartoframes
 cc = cartoframes.CartoContext(BASEURL, APIKEY)
-median_income = [{'numer_id': 'us.census.acs.B19013001',
-                  'geom_id': 'us.census.tiger.block_group',
-                  'numer_timespan': '2011 - 2015'}]
-df = cc.data_augment('transaction_events',
-                     median_income)
+
+
+
+
+write(df, table_name, temp_dir=SYSTEM_TMP_PATH, overwrite=False, lnglat=None, encode_geom=False, geom_col=None, **kwargs)
+

Write a DataFrame to a CARTO table.

+

Example

+

Write a pandas DataFrame to CARTO.

+
cc.write(df, 'brooklyn_poverty', overwrite=True)
+
+
+

Scrape an HTML table from Wikipedia and send to CARTO with content +guessing to create a geometry from the country column. This uses +a CARTO Import API param content_guessing parameter.

+
url = 'https://en.wikipedia.org/wiki/List_of_countries_by_life_expectancy'
+# retrieve first HTML table from that page
+df = pd.read_html(url, header=0)[0]
+# send to carto, let it guess polygons based on the 'country'
+#   column. Also set privacy to 'public'
+cc.write(df, 'life_expectancy',
+         content_guessing=True,
+         privacy='public')
+cc.map(layers=Layer('life_expectancy',
+                    color='both_sexes_life_expectancy'))
@@ -254,64 +258,84 @@

CartoContext

- -
Parameters:
    -
  • table_name (str) – Name of table on CARTO account that Data -Observatory measures are to be added to.
    • -
  • metadata (list of dicts) –

    List of all measures to add to -table_name. Each dict has the following keys:

    -
      -
    • numer_id (str): The identifier for the desired measurement
      • -
    • geom_id (str, optional): Identifier for a desired -geographic boundary level to use when calculating measures. -Will be automatically assigned if undefined
      • -
    • normalization (str, optional): The desired normalization. -One of ‘area’, ‘prenormalized’, or ‘denominated’. ‘Area’ will -normalize the measure per square kilometer, ‘prenormalized’ -will return the original value, and ‘denominated’ will -normalize by a denominator.
      • -
    • denom_id (str, optional): Measure ID from DO catalog
      • -
    • numer_timespan (str, optional): The desired timespan for -the measurement. Defaults to most recent timespan available -if left unspecified.
      • -
    • geom_timespan (str, optional): The desired timespan for the -geometry. Defaults to timespan matching numer_timespan if -left unspecified.
      • -
    • target_area (str, optional): Instead of aiming to have -target_geoms in the area of the geometry passed as extent, -fill this area. Unit is square degrees WGS84. Set this to -0 if you want to use the smallest source geometry for this -element of metadata, for example if you’re passing in points.
      • -
    • target_geoms (str, optional): Override global -target_geoms for this element of metadata
      • -
    • max_timespan_rank (str, optional): Override global -max_timespan_rank for this element of metadata
      • -
    • max_score_rank (str, optional): Override global -max_score_rank for this element of metadata
      • -
    -
    • +
  • df (pandas.DataFrame) – DataFrame to write to table_name in user +CARTO account
    • +
  • table_name (str) – Table to write df to in CARTO.
    • +
  • temp_dir (str, optional) – Directory for temporary storage of data +that is sent to CARTO. Default is /tmp (Unix-like systems).
    • +
  • overwrite (bool, optional) – Behavior for overwriting table_name +if it exits on CARTO. Defaults to False.
    • +
  • lnglat (tuple, optional) – lng/lat pair that can be used for +creating a geometry on CARTO. Defaults to None. In some +cases, geometry will be created without specifying this. See +CARTO’s Import API +for more information.
    • +
  • encode_geom (bool, optional) – Whether to write geom_col to CARTO +as the_geom.
    • +
  • geom_col (str, optional) – The name of the column where geometry +information is stored. Used in conjunction with encode_geom.
    • +
  • kwargs – Keyword arguments from CARTO’s Import API. See the params +listed in the documentation +for more information. For example, when using +content_guessing=’true’, a column named ‘countries’ with +country names will be used to generate polygons for each +country. To avoid unintended consequences, avoid file, url, +and other similar arguments.
Returns:

A DataFrame representation of table_name which -has new columns for each measure in metadata.

+
Returns:

If lnglat flag is set and the +DataFrame has more than 100,000 rows, a BatchJobStatus +instance is returned. Otherwise, None.
Return type:

pandas.DataFrame

+
Return type:

BatchJobStatus or None
+
+

Note

+

DataFrame indexes are changed to ordinary columns. CARTO creates +an index called cartodb_id for every table that runs from 1 to +the length of the DataFrame.

+
-
-data_boundaries(df=None, table_name=None)
-

Not currently implemented

-
- -
-
-data_discovery(keywords=None, regex=None, time=None, boundary=None)
-

Not currently implemented

+
+read(table_name, limit=None, index='cartodb_id', decode_geom=False)
+

Read a table from CARTO into a pandas DataFrames.

+ +++ + + + + + + + +
Parameters:
    +
  • table_name (str) – Name of table in user’s CARTO account.
    • +
  • limit (int, optional) – Read only limit lines from +table_name. Defaults to None, which reads the full table.
    • +
  • index (str, optional) – Not currently in use.
    • +
  • decode_geom (bool, optional) – Decodes CARTO’s geometries into a +Shapely +object that can be used, for example, in GeoPandas.
    • +
+
Returns:

DataFrame representation of table_name from +CARTO.

+
Return type:

pandas.DataFrame

+
+

Example

+
import cartoframes
+cc = cartoframes.CartoContext(BASEURL, APIKEY)
+df = cc.read('acadia_biodiversity')
+
+
@@ -330,6 +354,41 @@

CartoContext +
+query(query, table_name=None, decode_geom=False)
+

Pull the result from an arbitrary SQL query from a CARTO account +into a pandas DataFrame. Can also be used to perform database +operations (creating/dropping tables, adding columns, updates, etc.).

+ +++ + + + + + + + +
Parameters:
    +
  • query (str) – Query to run against CARTO user database. This data +will then be converted into a pandas DataFrame.
    • +
  • table_name (str, optional) – If set, this will create a new +table in the user’s CARTO account that is the result of the +query. Defaults to None (no table created).
    • +
  • decode_geom (bool, optional) – Decodes CARTO’s geometries into a +Shapely +object that can be used, for example, in GeoPandas.
    • +
+
Returns:

DataFrame representation of query supplied. +Pandas data types are inferred from PostgreSQL data types. +In the case of PostgreSQL date types, dates are attempted to be +converted, but on failure a data type ‘object’ is used.

+
Return type:

pandas.DataFrame

+
+

+
map(layers=None, interactive=True, zoom=None, lat=None, lng=None, size=(800, 400), ax=None)
@@ -397,11 +456,12 @@

CartoContextReturns:

Interactive maps are rendered in an -iframe, while static maps are rendered in img tags.

+Returns:

Interactive maps are +rendered as HTML in an iframe, while static maps are returned as +matplotlib Axes objects or IPython Image.

-Return type:

IPython.display.HTML

+Return type:

IPython.display.HTML or matplotlib Axes

@@ -409,97 +469,33 @@

CartoContext -
-query(query, table_name=None, decode_geom=False)
-

Pull the result from an arbitrary SQL query from a CARTO account -into a pandas DataFrame. Can also be used to perform database -operations (creating/dropping tables, adding columns, updates, etc.).

- --- - - - - - - - -
Parameters:
    -
  • query (str) – Query to run against CARTO user database.
    • -
  • table_name (str, optional) – If set, this will create a new -table in the user’s CARTO account that is the result of the -query. Defaults to None (no table created).
    • -
-
Returns:

DataFrame representation of query supplied. -Pandas data types are inferred from PostgreSQL data types. -In the case of PostgreSQL date types, the data type ‘object’ is -used.

-
Return type:

pandas.DataFrame

-
-

- -
-
-read(table_name, limit=None, index='cartodb_id', decode_geom=False)
-

Read tables from CARTO into pandas DataFrames.

-

Example

-
import cartoframes
-cc = cartoframes.CartoContext(BASEURL, APIKEY)
-df = cc.read('acadia_biodiversity')
-
-
- --- - - - - - - - -
Parameters:
    -
  • table_name (str) – Name of table in user’s CARTO account.
    • -
  • limit (int, optional) – Read only limit lines from -table_name. Defaults to None, which reads the full table.
    • -
  • index (str, optional) – Not currently in use.
    • -
-
Returns:

DataFrame representation of table_name from -CARTO.

-
Return type:

pandas.DataFrame

-
-
- -
-
-sync(dataframe, table_name)
-

Depending on the size of the DataFrame or CARTO table, perform -granular operations on a DataFrame to only update the changed cells -instead of a bulk upload. If on the large side, perform granular -operations, if on the smaller side use Import API.

+
+data_augment(table_name, metadata)
+

Augment an existing CARTO table with Data Observatory measures. See the full Data +Observatory catalog for all available +measures. The result of this operation is:

+
    +
  1. It updates table_name by adding columns from the Data Observatory
    2. +
  2. It returns a pandas DataFrame representation of that newly augmented +table.
    3. +

Note

-

Not yet implemented.

+

This method alters table_name in the user’s CARTO database by +adding additional columns. To avoid this, create a copy of the +table first and use the new copy instead.

-
- -
-
-write(df, table_name, temp_dir='/tmp', overwrite=False, lnglat=None, encode_geom=False, geom_col=None, **kwargs)
-

Write a DataFrame to a CARTO table.

Example

-

Write a pandas DataFrame to CARTO.

-
cc.write(df, 'brooklyn_poverty', overwrite=True)
-
-
-

Scrape an HTML table from Wikipedia and send to CARTO with content -guessing to create a geometry from the country column. This uses -a CARTO Import API param content_guessing parameter.

-
url = 'https://en.wikipedia.org/wiki/List_of_countries_by_life_expectancy'
-df = pd.read_html(url, header=0)[0]
-cc.write(df, 'life_expectancy', content_guessing=True)
+
Add new measures to a CARTO table and pass it to a pandas
+DataFrame. Using the “Median Household Income in the past 12
+months” measure from the Data Observatory Catalog.

+
import cartoframes
+cc = cartoframes.CartoContext(BASEURL, APIKEY)
+median_income = [{'numer_id': 'us.census.acs.B19013001',
+                  'geom_id': 'us.census.tiger.block_group',
+                  'numer_timespan': '2011 - 2015'}]
+df = cc.data_augment('transaction_events',
+                     median_income)
 

 

 
@@ -507,38 +503,48 @@ 
CartoContext
 

-
-
@@ -551,13 +557,8 @@ 
CartoContext
 
Map Layer Classes

 
Layer classes for map creation. See examples in layer.Layer and layer.QueryLayer
-for example usage.

-

-

-class layer.AbstractLayer

-
Abstract Layer object

-

-
+for example usage for data layers. See layer.BaseMap for
+basemap layers.

 

 

 class layer.BaseMap(source='voyager', labels='back', only_labels=False)

@@ -612,8 +613,9 @@ 
CartoContext
 class layer.Layer(table_name, source=None, overwrite=False, time=None, color=None, size=None, tooltip=None, legend=None)
 
A cartoframes Data Layer based on a specific table in user’s CARTO
-database. This layer class is useful for visualizing individual datasets
-with CartoContext.map().

+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
@@ -624,23 +626,37 @@ 
CartoContext'scheme': styling.prism(10)})])
 

 

-
Parameters: See QueryLayer for a full list of arguments.

+

 
Parameters:
    
-
  • df (pandas.DataFrame) – DataFrame to write to table_name in user
-CARTO account
    • 
-
  • table_name (str) – Table to write df to in CARTO.
    • 
-
  • temp_dir (str, optional) – Directory for temporary storage of data
-that is sent to CARTO. Default is /tmp (Unix-like systems).
    • 
-
  • overwrite (bool, optional) – Behavior for overwriting table_name
-if it exits on CARTO. Defaults to False.
    • 
-
  • lnglat (tuple, optional) – lng/lat pair that can be used for
-creating a geometry on CARTO. Defaults to None. In some
-cases, geometry will be created without specifying this. See
-CARTO’s Import API
-for more information.
    • 
-
  • encode_geom (bool, optional) – Whether to write geom_col to CARTO
-as the_geom.
    • 
-
  • geom_col (str, optional) – The name of the column where geometry
-information is stored. Used in conjunction with encode_geom.
    • 
-
  • kwargs – Keyword arguments from CARTO’s Import API. See the params
-listed in the documentation
-for more information. For example, when using
-content_guessing=’true’, a column named ‘countries’ with
-country names will be used to generate polygons for each
-country. To avoid unintended consequences, avoid file, url,
-and other similar arguments.
    • 
+
  • table_name (str) – Name of table on CARTO account that Data
+Observatory measures are to be added to.
    • 
+
  • metadata (list of dicts) – 
    List of all measures to add to
+table_name. Each dict has the following keys:
    
+
      
+
    • numer_id (str): The identifier for the desired measurement
      • 
+
    • geom_id (str, optional): Identifier for a desired
+geographic boundary level to use when calculating measures.
+Will be automatically assigned if undefined
      • 
+
    • normalization (str, optional): The desired normalization.
+One of ‘area’, ‘prenormalized’, or ‘denominated’. ‘Area’ will
+normalize the measure per square kilometer, ‘prenormalized’
+will return the original value, and ‘denominated’ will
+normalize by a denominator.
      • 
+
    • denom_id (str, optional): Measure ID from DO catalog
      • 
+
    • numer_timespan (str, optional): The desired timespan for
+the measurement. Defaults to most recent timespan available
+if left unspecified.
      • 
+
    • geom_timespan (str, optional): The desired timespan for the
+geometry. Defaults to timespan matching numer_timespan if
+left unspecified.
      • 
+
    • target_area (str, optional): Instead of aiming to have
+target_geoms in the area of the geometry passed as extent,
+fill this area. Unit is square degrees WGS84. Set this to
+0 if you want to use the smallest source geometry for this
+element of metadata, for example if you’re passing in points.
      • 
+
    • target_geoms (str, optional): Override global
+target_geoms for this element of metadata
      • 
+
    • max_timespan_rank (str, optional): Override global
+max_timespan_rank for this element of metadata
      • 
+
    • max_score_rank (str, optional): Override global
+max_score_rank for this element of metadata
      • 
+
    
+
    • 
 

 		
 
Returns:
If lnglat flag is set and the
-DataFrame has more than 100,000 rows, a BatchJobStatus
-instance is returned. Otherwise, None.

+
Returns:
A DataFrame representation of table_name which
+has new columns for each measure in metadata.

 		
 
Return type:
BatchJobStatus or None

+
Return type:
pandas.DataFrame

 		
 

 

+++
+
+
+
+



Parameters:
    
+
  • table_name (str) – Name of table in CARTO account
    • 
+
  • Styling – See QueryLayer for a full list of all arguments
+arguments for styling this map data layer.
    • 
+
  • source (pandas.DataFrame, optional) – Not currently implemented
    • 
+
  • overwrite (bool, optional) – Not currently implemented
    • 
+

+
class layer.QueryLayer(query, time=None, color=None, size=None, tooltip=None, legend=None)
-

cartoframes Data Layer based on an arbitrary query to the user’s CARTO +

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:

    -
  • pull down a snapshot of the data (e.g., selecting only important columns -instead of all columns in the dataset)
    • -
  • doing spatial processing using PostGIS and -PostgreSQL, which is the database +
  • Visualizing spatial operations using PostGIS +and PostgreSQL, which is the database underlying CARTO
    • -
  • performing arbitrary relational database queries (e.g., complex JOINs +
  • 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

@@ -682,62 +698,77 @@

CartoContext Parameters:
    -
  • query (str) – Query that is fed into a pandas DataFrame. At a minimum, -all queries need to have the columns cartodb_id, the_geom, and -the_geom_webmercator. Read more in -CARTO’s docs -for more information.
    • -
  • time (dict or str, optional) –

    Style to apply to layer. -If time is a dict, the following keys are options:

    +
  • 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.

    +

    If time is a dict, the following keys are options:

      -
    • column (str, required): Column for animating map from. Data must +
    • 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 +
    • 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 to count.
      • -
    • cumulative (bool, optional): Whether to accumulate points over +
    • cumulative (bool, optional): Whether to accumulate points over time (True) or not (False, default)
      • -
    • frames (int, optional): Number of frames in the animation. +
    • frames (int, optional): Number of frames in the animation. Defaults to 256.
      • -
    • duration (int, optional): Number of seconds in the animation. +
    • duration (int, optional): Number of seconds in the animation. Defaults to 30.
      • -
    • trails (int, optional): Number of trails after the incidence of +
    • trails (int, optional): Number of trails after the incidence of a point. Defaults to 2.
    -

    If time is a str, then it must be a column name available in -the query that is of type numeric or datetime.

    • -
  • color (dict or str, optional) –

    Color style to apply to map. -If color is a dict, the following keys are options, with +

  • 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.
      • +
    +

    If color is a dict, the following keys are options, with values described:

      -
    • column (str): Column to base coloring from.
      • -
    • scheme (str, optinal): Color scheme from -CartoColors. -Defaults to Mint.
      • -
    • bin_method (str, optional): Quantification method for dividing -data range into bins. Must be one of: quantiles, equal, -headtails, or jenks. Defaults to quantiles.
      • -
    • bins (int, optional): Number of bins to divide data amongst in -the bin_method. Defaults to 5.
      • +
    • 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.

      +
    • -
  • size (dict or int, optional) –

    Size style to apply to point data. -If size is a dict, the follow keys are options, with values -described as:

    +
  • size (dict or int, optional) –

    Size style to apply to point data.

    +

    If size is an int, all points are sized by this value.

    +

    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 the dict input to override these +values.

    +

    If size is a dict, the follow keys are options, with +values described as:

      -
    • column (str): Column to base sizing of points on
      • +
    • 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: quantiles, equal, -headtails, or jenks. Defaults to quantiles.
      • -
    • bins (int, optional): Number of bins to break data into. Defaults +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). Defaults +to 25.
      • +
    • min (int, optional): Minimum point width (in pixels). Defaults to 5.
      • -
    • max (int, optional): Maximum point width (in pixels). Defaults to -25.
      • -
    • min (int, optional): Minimum point width (in pixels). Defaults to -5.
  • tooltip (tuple, optional) – Not yet implemented.
    • @@ -755,6 +786,42 @@

    CartoContextGitHub repository.

    CartoColors +
    +
    +class styling.BinMethod
    +

    Data classification methods used for the styling of data on maps.

    +
    +
    +quantiles
    +

    str – Quantiles classification for quantitative data

    +
    + +
    +
    +jenks
    +

    str – Jenks classification for quantitative data

    +
    + +
    +
    +headtails
    +

    str – Head/Tails classification for quantitative data

    +
    + +
    +
    +equal
    +

    str – Equal Interval classification for quantitative data

    +
    + +
    +
    +category
    +

    str – Category classification for qualitative data

    +
    + +
    +
    styling.antique(bins, bin_method='category')
    @@ -806,7 +873,23 @@

    CartoContext
    styling.custom(colors, bins=None, bin_method='quantiles')
    -

    Get custom scheme

    +

    Create a custom scheme.

    + +++ + + + +
    Parameters:
      +
    • colors (list of str) – List of hex values for styling data
      • +
    • bins (int, optional) – Number of bins to style by. If not given, the +number of colors will be used.
      • +
    • bin_method (str, optional) – Classification method. One of the values +in BinMethod. Defaults to quantiles, which only works with +quantitative data.
      • +
    +

    @@ -911,6 +994,32 @@

    CartoContext +
    +styling.scheme(name, bins, bin_method)
    +

    Return a custom scheme based on CartoColors.

    + +++ + + + +
    Parameters:
      +
    • name (str) – Name of a CartoColor.
      • +
    • bins (int) – Number of bins for classifying data. CartoColors have 7 +bins max for quantitative data, and 11 max for qualitative data.
      • +
    • bin_method (str) – One of methods in BinMethod.
      • +
    +
    +
    +

    Warning

    +

    Input types are particularly sensitive in this function, and little +feedback is given for errors. name and bin_method arguments +are case-sensitive.

    +
    +

    +
    styling.sunset(bins, bin_method='quantiles')
    @@ -968,7 +1077,7 @@

    BatchJobStatusBatch SQL API docs about responses and how to interpret them.

    Example

    -

    Poll for a job’s status if you’ve caught the BatchJobStatus +

    Poll for a job’s status if you’ve caught the BatchJobStatus instance.

    import time
 job = cc.write(df, 'new_table',
@@ -981,7 +1090,7 @@ 
    BatchJobStatustime.sleep(5)
    -

    Create a BatchJobStatus instance if you have a job_id output +

    Create a BatchJobStatus instance if you have a job_id output from a cc.write operation.

    >>> from cartoframes import CartoContext, BatchJobStatus
 >>> cc = CartoContext(username='...', api_key='...')
@@ -1272,6 +1381,14 @@ 
    Indices and tablesModule Index
 
  • Search Page
    •

+ +++ + + + +
Version:0.3.0b5
@@ -1311,6 +1428,7 @@

Table Of Contents

Related Topics

@@ -1339,7 +1457,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/modules.html b/docs/modules.html index 3ccebd891..1a44ca376 100644 --- a/docs/modules.html +++ b/docs/modules.html @@ -5,13 +5,13 @@ - cartoframes — cartoframes 0.0.1 documentation + cartoframes — cartoframes 0.3.0b5 documentation + + @@ -68,6 +70,8 @@

cartoframesDocumentation overview @@ -96,7 +100,7 @@

Quick search

©2017, Andy Eschbacher, Stuart Lynn. | - Powered by Sphinx 1.6.3 + Powered by Sphinx 1.6.5 & Alabaster 0.7.10 | diff --git a/docs/objects.inv b/docs/objects.inv index 6fb3a2970..768cd2e11 100644 Binary files a/docs/objects.inv and b/docs/objects.inv differ diff --git a/docs/py-modindex.html b/docs/py-modindex.html index c58e01728..84e1f2dd6 100644 --- a/docs/py-modindex.html +++ b/docs/py-modindex.html @@ -5,13 +5,13 @@ - Python Module Index — cartoframes 0.0.1 documentation + Python Module Index — cartoframes 0.3.0b5 documentation