Widgets Documentation

cartoframes/viz/constants.py

@@ -2,7 +2,7 @@
 CARTO_VL_DEV = '/dist/carto-vl.js'
 CARTO_VL_URL = 'https://libs.cartocdn.com/carto-vl/{}/carto-vl.min.js'.format(CARTO_VL_VERSION)
 
-AIRSHIP_VERSION = 'cartoframes'
+AIRSHIP_VERSION = 'v2.2.0-rc.2'
 AIRSHIP_COMPONENTS_DEV = '/packages/components/dist/airship.js'
 AIRSHIP_BRIDGE_DEV = '/packages/bridge/dist/asbridge.js'
 AIRSHIP_MODULE_DEV = '/packages/components/dist/airship/airship.esm.js'
@@ -67,4 +67,19 @@
     'time-series'
 ]
 
+FORMULA_OPERATIONS_VIEWPORT = {
+  'count': 'viewportCount',
+  'avg': 'viewportAvg',
+  'min': 'viewportMin',
+  'max': 'viewportMax',
+  'sum': 'viewportSum'
+}
+
+FORMULA_OPERATIONS_GLOBAL = {
+  'count': 'globalCount',
+  'avg': 'globalAvg',
+  'min': 'globalMin',
+  'max': 'globalMax',
+  'sum': 'globalSum'
+}
 THEMES = ['dark', 'light']

cartoframes/viz/widget.py

@@ -11,7 +11,6 @@ class Widget():
         data (dict): The widget definition for a layer. It contains the information to render a widget:
             `type`: 'default', 'formula', time-series', 'animation', 'category', 'histogram'
             `value`: A constant value or a CARTO VL expression
-            `options`: Options for the widget, this varies depending on the widget
 
             The widget also can display text information: `title`, `description` and `footer`.
     Example:
@@ -94,4 +93,6 @@ def _get_options_from_data(self, data):
         for key, value in data.items():
             if key not in attributes:
                 options[key] = value
+
+        options['read_only'] = data.get('read_only', False)
         return options

cartoframes/viz/widget_list.py

@@ -4,24 +4,26 @@
 
 
 class WidgetList(object):
-    """List
+    """WidgetList
      Args:
         widgets (dict, list, Widget): The list of widgets for a layer.
 
     Example:
-     .. code::
-         from cartoframes.viz import Widget
-
-         WidgetList([{
-            type: 'formula',
-            value: 'viewportSum($amount)'
-            title: '...',
-            description: '...',
-            footer: '...'
-        }, {
-            'type': 'default',
-            'value': '"Custom Info"',
-        }])
+
+        .. code::python
+
+            from cartoframes.viz import Widget
+
+            WidgetList([{
+                type: 'formula',
+                value: 'viewportSum($amount)'
+                title: '...',
+                description: '...',
+                footer: '...'
+            }, {
+                'type': 'default',
+                'value': '"Custom Info"',
+            }])
     """
 
     def __init__(self, widgets=None):

cartoframes/viz/widgets/__init__.py

@@ -1,5 +1,5 @@
 """
-Widget functions to generate widgets faster.
+Widget helpers to generate widgets faster.
 """
 
 from __future__ import absolute_import

cartoframes/viz/widgets/animation_widget.py

@@ -4,6 +4,42 @@
 
 
 def animation_widget(**kwargs):
+    """Helper function for quickly creating an animated widget.
+
+    The animation widget includes an animation status bar as well as controls to play or pause animated data.
+    The `filter` property of your map's style, applied to either a date or numeric field, drives both
+    the animation and the widget. Only **one** animation can be controlled per layer.
+    To learn more about creating animations visit:
+      - https://carto.com/developers/carto-vl/guides/animated-visualizations.
+
+    Args:
+        title (str, optional): Title of widget.
+        description (str, optional): Description text widget placed under widget title.
+        footer (str, optional): Footer text placed on the widget bottom
+
+    Returns:
+        cartoframes.viz.Widget: Widget with type='animation'
+
+    Example:
+
+        .. code::
+
+            from cartoframes.viz import Map, Layer
+            from cartoframes.viz.widgets import animation_widget
+
+            Map(
+                Layer(
+                    'seattle_collisions',
+                    'filter: animation($incdate, 20, fade(0.5,0.5))',
+                    widgets=[
+                        animation_widget(
+                            title='Collision Date',
+                            description= 'Play, pause, or select the range of the animation'
+                        )]
+                )
+            )
+    """
+
     data = kwargs
     data['type'] = 'animation'
     return Widget(data)

cartoframes/viz/widgets/category_widget.py

@@ -4,7 +4,42 @@
 
 
 def category_widget(value, **kwargs):
+    """Helper function for quickly creating a category widget.
+
+    Args:
+        value (str): Column name of the category value
+        title (str, optional): Title of widget.
+        description (str, optional): Description text widget placed under widget title.
+        footer (str, optional): Footer text placed on the widget bottom
+        read_only (boolean, optional): Interactively filter a category by selecting it in the widget.
+          Set to "False" by default.
+
+    Returns:
+        cartoframes.viz.Widget: Widget with type='category'
+
+    Example:
+
+        .. code::
+
+            from cartoframes.viz import Map, Layer
+            from cartoframes.viz.widgets import category_widget
+
+            Map(
+                Layer(
+                    'seattle_collisions',
+                    widgets=[
+                        category_widget(
+                            'collisiontype',
+                            title='Type of Collision',
+                            description='Select a category to filter',
+                        )
+                    ]
+                )
+            )
+    """
+
     data = kwargs
     data['type'] = 'category'
     data['value'] = value
+    data['read_only'] = kwargs.get('read_only', False)
     return Widget(data)

cartoframes/viz/widgets/default_widget.py

@@ -4,6 +4,38 @@
 
 
 def default_widget(**kwargs):
+    """Helper function for quickly creating a default widget.
+
+    The default widget is a general purpose widget that can be used to provide additional information about your map.
+
+    Args:
+        title (str, optional): Title of widget.
+        description (str, optional): Description text widget placed under widget title.
+        footer (str, optional): Footer text placed on the widget bottom
+
+    Returns:
+        cartoframes.viz.Widget: Widget with type='default'
+
+    Example:
+
+        .. code::
+
+            from cartoframes.viz import Map, Layer
+            from cartoframes.viz.widgets import default_widget
+
+            Map(
+                Layer(
+                    'seattle_collisions',
+                    widgets=[
+                        default_widget(
+                            title='Road Collisions in 2018',
+                            description='An analysis of collisions in Seattle, WA',
+                            footer='Data source: City of Seattle'
+                        )]
+                )
+            )
+    """
+
     data = kwargs
     data['type'] = 'default'
     return Widget(data)

cartoframes/viz/widgets/formula_widget.py

@@ -1,11 +1,95 @@
 from __future__ import absolute_import
 
 from ..widget import Widget
+from ..constants import FORMULA_OPERATIONS_VIEWPORT, FORMULA_OPERATIONS_GLOBAL
 
 
-def formula_widget(value, **kwargs):
+def formula_widget(value, operation=None, **kwargs):
+    """Helper function for quickly creating a formula widget.
+
+    Formula widgets calculate aggregated values ('Avg', 'Max', 'Min', 'Sum') from numeric columns
+    or counts of features ('Count') in a dataset.
+
+    A formula widget's aggregations can be calculated on 'global' or 'viewport' based values.
+    If you want the values in a formula widget to update on zoom and/or pan, use viewport based aggregations.
+
+    Args:
+        value (str): Column name of the numeric value
+        operation (str): attribute for widget's aggregated value ('count', 'avg', 'max', 'min', 'sum')
+        title (str, optional): Title of widget.
+        description (str, optional): Description text widget placed under widget title.
+        footer (str, optional): Footer text placed on the widget bottom
+        is_global (boolean, optional): Account for calculations based on the entire dataset ('global') vs.
+            the default of 'viewport' features.
+
+    Returns:
+        cartoframes.viz.Widget: Widget with type='formula'
+
+    Example:
+
+        .. code::
+
+            from cartoframes.viz import Map, Layer
+            from cartoframes.viz.widgets import formula_widget
+
+            Map(
+                Layer(
+                    'seattle_collisions',
+                    widgets=[
+                        formula_widget(
+                            'count',
+                            title='Number of Collisions',
+                            description='Zoom and/or pan the map to update count',
+                            footer='collisions in this view'
+                        )
+                    ]
+                )
+            )
+
+        .. code::
+
+            from cartoframes.viz import Map, Layer
+            from cartoframes.viz.widgets import formula_widget
+
+            Map(
+                Layer(
+                    'seattle_collisions',
+                    widgets=[
+                        formula_widget(
+                            'pedcount',
+                            'sum',
+                            is_global=True,
+                            title='Total Number of Pedestrians',
+                            description='involved over all collisions',
+                            footer='pedestrians'
+                        )
+                    ]
+                )
+            )
+    """
+
     data = kwargs
     data['type'] = 'formula'
-    data['value'] = value
+    is_global = kwargs.get('is_global', False)
+    data['value'] = get_value_expression(operation, value, is_global)
 
     return Widget(data)
+
+
+def get_formula_operation(operation, is_global):
+    if is_global:
+        return FORMULA_OPERATIONS_GLOBAL.get(operation)
+    else:
+        return FORMULA_OPERATIONS_VIEWPORT.get(operation)
+
+
+def get_value_expression(operation, value, is_global):
+    if value == 'count':
+        formula_operation = get_formula_operation(value, is_global)
+        return formula_operation + '()'
+    else:
+        if operation:
+            formula_operation = get_formula_operation(operation, is_global)
+            return formula_operation + '($' + value + ')'
+        else:
+            return '$' + value

cartoframes/viz/widgets/histogram_widget.py

@@ -4,7 +4,49 @@
 
 
 def histogram_widget(value, **kwargs):
+    """Helper function for quickly creating a histogram widget.
+
+    Histogram widgets display the distribution of a numeric attribute, in buckets, to group
+    ranges of values in your data.
+    By default, you can hover over each bar to see each bucket's values and count, and also
+    filter your map's data within a given range
+
+    Args:
+        value (str): Column name of the numeric or date value
+        title (str, optional): Title of widget.
+        description (str, optional): Description text widget placed under widget title.
+        footer (str, optional): Footer text placed on the widget bottom
+        buckets (number, optional): Number of histogram buckets. Set to 20 by default.
+        read_only (boolean, optional): Interactively filter a range of numeric values by selecting them in the widget.
+          Set to "False" by default.
+
+    Returns:
+        cartoframes.viz.Widget: Widget with type='histogram'
+
+    Example:
+
+        .. code::
+
+            from cartoframes.viz import Map, Layer
+            from cartoframes.viz.widgets import histogram_widget
+
+            Map(
+                Layer(
+                    'seattle_collisions',
+                    widgets=[
+                        histogram_widget(
+                            'vehcount',
+                            title='Number of Vehicles Involved',
+                            description='Select a range of values to filter',
+                            buckets=9
+                        )
+                    ]
+                )
+            )
+    """
+
     data = kwargs
     data['type'] = 'histogram'
     data['value'] = value
+    data['read_only'] = kwargs.get('read_only', False)
     return Widget(data)