Visualization API research

Proposal

UPDATED

Based on the information provided in this thread, I add here the final conclusions:

• Add Style helpers (from Layer helpers, in cartoframes.viz.styles)
  • basic_style
  • color_bins_style
  • color_category_style
  • color_continuous_style
  • size_bins_style
  • size_category_style
  • size_continuous_style
• Add default UI component helpers
  • default_legend
  • default_widget
  • default_popup
• Allow legends/widgets/popups=True/False to enable the defaults to the Layer
• Add title, description, footer to the Layer
• Refactor Layer helper methods? Should we remove them?

from cartoframes.viz import Layer, size_continuous_style

Layer(
    source='starbucks_points',
    style=size_continuous_style(
        value='revenue',
        color='white',
        opacity='0.2',
        stroke_color='blue',
        size=[20, 80]
    ),
    legends=True,
    title='Revenue $'
)

from cartoframes.viz import Layer, size_continuous_style, default_legend

Layer(
    source='starbucks_points',
    style=size_continuous_style(
        value='revenue',
        color='white',
        opacity='0.2',
        stroke_color='blue',
        size=[20, 80]
    ),
    legends=[
        ....,
        default_legend(title='Revenue $'),
        ....
    ]
)

[makella]

Below are some initial thoughts/ideas on how we can unify our current visualization patterns. The first section talks about enhancements needed to the style class of the Layer to remove the dependency on VL syntax and the second section (thematic maps) focuses on how we can 1) extend current viz layer helpers to be more flexible in widgets and popups and 2) how we can make the cartographic thinking we’ve built into the helpers easily accessible in the Layer

Non-thematic maps

These maps are ones where users aren’t symbolizing an attribute in their data but simply symbolizing a dataset where all features are equal. Whether to modify the defaults or present the results of an analysis, these maps are currently not served by our viz layer helpers and in order to make, a user has to know VL syntax. This will also eliminate the styling confusion (strokeWidth: / width= and width: / size=, etc.) that a user needs to know in our current implementation.

In this case, we will assume the user will add their own Legend, Widgets and Popups so the main thing here is to simplify how the Style is defined.

Example proposal:

Add table to a Layer and get default symbology:

Layer ('starbucks_points')

Modify/customize a basic style:

Layer(
  'starbucks_points',
  style=(
    color= 'green',
    size= 5,
    opacity= 0.5,
    stroke_width= 1,
    stroke_color= 'purple'
  )
)

To discuss:

• We would need to slightly modify the ‘default legend’ to help users make a complete map with this simple style as described in this ticket: https://github.com/CartoDB/cartoframes/issues/1192

Related tickets:

• https://github.com/CartoDB/cartoframes/issues/927

Thematic Maps

This is when a user wants to symbolize on a numeric, categorical, or time-based attribute. In this case, with our current implementation, a user can use a viz layer helper but if they have started their workflow at the Layer level and added other components like Widgets and Popups, they have to in essence start from scratch. In addition, our current implementation of the viz layer only supports mapping and adding related components for one attribute (except in the case where a user chooses to animate by another attribute using the option animate='attribute_name').

Therefore, the workflow for a thematic maps should not be limited to only one attribute and through our discussions there are two potential paths to make this kind of map both of which we should address.

Path 1: Use a viz layer helper

From our internal research, what we have seen is that viz layer helpers are too limited in their offerings. Specifically with regards to Widgets and Popups in the cases where users want to add additional information to the map to support their analysis.

For this path, we would add the ability to add more/different Widgets and Popups. The Legend would be the same default that we provide as part of the benefit of using a viz layer is to get default cartography which the Legend is an important part of.

We should discuss the different options for this to happen…one way is for the viz layers to accept additional information using the popup and widget classes inside of the helper layer definition. The benefit of this is if a user is working at the Layer level and already has popups and widgets defined, that they could easily switch the Layer to something like size_continuous_layer and not lose all of that other work.

The thinking here is what @elenatorro has tested and looks like:

size_continuous_layer(
        geo_cdf,
        'revenue',
        title='Revenue $',
        color='white',
        opacity='0.2',
        stroke_color='blue',
        size=[20, 80],
        popup=Popup({
            'hover': [{
                    'title': 'Address',
                    'value': '$address'
                }, {
                    'title': 'Precision',
                    'value': '$gc_status_rel'
                }, {
                    'title': 'Revenue',
                    'value': '$revenue'
                }]
        })
    )

To discuss:

• As previously mentioned, for me, providing an appropriate legend by default is an important part of the visualization therefore, I would keep the current legend pattern we have where we add the appropriate one and provide the user the option to add a title, description and footer.
• If, for example, no popups are defined with the popup class, would a user still be able to take advantage of the helper’s default popup? I was thinking something like default_popup=True if set, you get our default popup and if not, you can add your custom popups with the popup class and same for the widgets. Should we think about the same thing for legends? We provide a default legend but if the user wants to take advantage of the Legend API and sets default_legend=False what would happen with the title, footer and description parameters if already set?
• To make this the most user-friendly, the proposal to unify legend/widget/popup apis would be important for this to happen

Path 2: Make a thematic map at the Layer

The second way a user could make a thematic map is to stay inside the default Layer. Currently, this requires even more advanced VL syntax (ramps, etc.) and the biggest issue is that people are missing out and not able to take advantage of the built-in thinking as a tradeoff for more control with widgets and popups.

In this case, we could use the style class to bring in all the style-related parameters from the helpers and continue with the pattern where users could use the legend/widget/popup apis to add the other components to the map.

In essence, this would be a blend of the previous 2 examples:

Layer(
    'starbucks_points',
    style=size_continuous(
        'revenue',
        title='Revenue $',
        color='white',
        opacity='0.2',
        stroke_color='blue',
        size=[20, 80]
    ),
    legend=Legend(
        'size-continuous',
        title='Revenue',
        description='description',
        footer='footer'
    ),
    popup=Popup({
        'hover': [{
            'title': 'Address',
            'value': '$address'
        },{
            'title': 'Precision',
            'value': '$gc_status_rel'
        },{
            'title': 'Revenue',
            'value': '$revenue'
        }]
    }),
    widgets=[
        formula_widget(
        'count',
        title='Number of Stores',
        description='description'
    )]
)

Look forward to discussing these ideas together!

cc @elenatorro @Jesus89 @cmongut

[elenatorro]

You’re right, it also has some breaking changes. Let’s discuss if we keep them in the issue I mentioned once if finish the rest of the issues 👍 thanks!