Guides for beta release

[makella]

Update 22 May: Pending work

• 1-getting-started
• 2-syntax-basics
• 3-expressions
• 4-interpolation
• 5-style-by-geometry
• 6-animations
• 7-interactivity

---

@IagoLast @Jesus89 @arianaescobar

Before we write a specific guide about "how to work with colors", I think there are some other basic things that we should cover that will build up to a better understanding of how to do advanced operations not just with color, but everything.

Side note: some of the functionality with color is still being investigated and things like hsv($category,1,1) aren't going to produce good cartographic results read more here so I don't think it is something we want to highlight right now.

Also, in the Examples section of the doc, I just realized that not until the interactivity section do we have examples of doing symbol sizes. And I don't think we have one about using custom color schemes.

My thought with the first few guides is to really highlight interpolation, expressions, and animations since those are the things that are so new and powerful for thematic mapping.

If we can take people through the process of making a map through each of the higher level topics, that will get us in good shape for all of the questions that I have already been (and we all will soon) start to get!

I've put some ideas below... please let me know what sounds like a good idea.

• Interpolation

  • Ramp vs. blend
    • I think this currently is/will become a point of confusion so a guide walking through one or two use cases would be good.
  • How we interpolate color
    • color (accepted formats)
    • all interpolations using ramp() are done in CIELab
    • using CARTOColors
    • defining custom colors
  • How we interpolate symbol size
    • zoom()
    • blend
  • Multi-scale symbology
    • Interpolation of symbol size based on a zoom range
      https://cartodb.github.io/carto-vl/examples/editor/index.html#eyJhIjoidHhfMDEyNV9jb3B5X2NvcHkiLCJiIjoiIiwiYyI6ImNhcnRvZ2wiLCJkIjoiaHR0cHM6Ly97dXNlcn0uY2FydG8uY29tIiwiZSI6IndpZHRoOiBibGVuZCgyLCAxNiwgbGluZWFyKHpvb20oKSwgMl4xMiwgMl4xNikpXG5jb2xvcjogcmdiYSgyNTUsMCwwLDEpIiwiZiI6eyJsbmciOjIuMTU4Nzk4MTI1NDcwODY2NiwibGF0Ijo0MS4zODQ5NzgzNzcyMjcyNH0sImciOjEzLjUyNjQ0MjEzNDM1OTI5NiwiaCI6IkRhcmtNYXR0ZXIifQ==
    • Interpolation of color based on a zoom range
      https://cartodb.github.io/carto-vl/examples/editor/index.html#eyJhIjoidHhfMDEyNV9jb3B5X2NvcHkiLCJiIjoiIiwiYyI6ImNhcnRvZ2wiLCJkIjoiaHR0cHM6Ly97dXNlcn0uY2FydG8uY29tIiwiZSI6IndpZHRoOiAwLjAwNCp6b29tKClcbmNvbG9yOiByYW1wKGxpbmVhcih6b29tKCksIDJeMTAsIDJeMTQpLCBbcmVkLHllbGxvd10pXG5zdHJva2VDb2xvcjogIzAwMFxuc3Ryb2tlV2lkdGg6IDEiLCJmIjp7ImxuZyI6Mi4xNTYzMzkwMDAzMzQwMTQ2LCJsYXQiOjQxLjQyMjEzNjE5NTAzMjU4fSwiZyI6MTAuOTAwNDI3OTQxMTM5Mzk1LCJoIjoiRGFya01hdHRlciJ9

• Data-driven styling

  • Expressions
    • sqrt, $attribute, sqrt($attribute),.....etc.....
  • cluster, global, viewport
    • what are they, when to use them
    • for example: getting min/max values for ramping size or color based on a numeric attribute ramp(linear($amount,clusterMIN($amount),clusterMAX($amount)),bluyl)

• Animations

  • syntax
    • what is filter and why we use that
    • animation syntax and settings (linear($date,time('xxxxx'),time('xxxx'),10,fade(1,1))
  • map example of animating drought readings for each week between January 1, 2018 - April 23,2018
    • https://cartodb.github.io/carto-vl/examples/editor/index.html#eyJhIjoidXNkbV9hbGxfMjAxOCIsImIiOiIiLCJjIjoiY2FydG9nbCIsImQiOiJodHRwczovL3t1c2VyfS5jYXJ0by5jb20iLCJlIjoiY29sb3I6IG9wYWNpdHkocmFtcChidWNrZXRzKCRkbSwwLDEsMiwzLDQpLHBpbmt5bCksYmxlbmQoMC43LDAuOSxsaW5lYXIoJGRtLDAsMykpKVxuZmlsdGVyOiB0b3JxdWUobGluZWFyKCRkYXRlLHRpbWUoJzIwMTgtMDEtMDFUMDA6MDA6MDBaJyksdGltZSgnMjAxOC0wNC0yNFQwMDowMDowMFonKSksMTcsZmFkZSgyLDIpKSIsImYiOnsibG5nIjotOTMuODQ0MDI1NTI1MDgxNjMsImxhdCI6NDMuMjc3MDY0MTc2OTQ4OX0sImciOjMuNjA0NDY3NDIwNTIxMjkyLCJoIjoiVm95YWdlciJ9

[IagoLast]

@makella maybe we you can reuse something from here

[makella]

@IagoLast yes, definitely. Thanks for bringing to my attention.

@arianaescobar and I talked through this and below are the topics and general outline of what we think would be most beneficial for our Alpha release guides (keep in mind with all guides, we can link to specific examples and/or reference sections of the VL dev center).

Each guide should produce something tangible so the person following has a final result of the guide in their hands.

We can discuss and distribute topics at our Monday meeting.

The basics

• Quickstart Guide

  • The VERY basics of getting started with VL.
    • Setting up the .html file,
    • choosing a basemap, setting up the zoom/extent, etc.
    • adding a layer from CARTO,
    • simple styling of the layer
    • publishing
  • GOAL: by the time someone is done with this guide, they should have a basic map up and running and know how to share it with their mom! :)

• The basics of syntax

  • Writing styles in String vs. Javascript
    • what, why, best practices
  • The very basics of our styling syntax
    • Styling properties (color, width, etc.)
    • Other properties (filter, order, etc.)
    • Variables how to define and use
  • GOAL: by the time someone is done with this guide, they should feel comfortable with the syntax and understand the available properties

Expressions and Interpolation

Now that people are familiar with the basics of syntax, we can start introducing more complexity with going through interpolation and expressions.

• Introduction to Expressions

  • What are expressions?
  • Why use them?
  • One or two examples using expressions for different purposes (sqrt, cluster, viewport, global)
  • GOAL: by the time someone is done with the guide, they will understand how to use expressions.

• Introduction to Interpolation

  • What is interpolation?
  • Why use it?
  • What interpolations do we support / examples of the most common ones people will use
    • symbol size (blend, linear)
    • color (ramp, linear, custom colors, CARTOColors, )
    • zoom()
  • How to use expressions + interpolation (linear($value,clusterMIN($value),clusterMAX($value)))
  • GOAL: by the time someone is done with this lesson, they will understand what interpolation is, the kinds of interpolation we support, and the properties they can interpolate.

Style by size and/or color broken down by geometry type

Once we have introduced the "guts" (quickstart, syntax, expressions, interpolation) we can start applying the concepts to each geometry and map type. This is where people will look to know how to make maps that they are familiar making with Builder like choropleth, proportional symbol, categories, etc.

Since all geometry types don't support all operations (for example, we still have to implement quantiles for lines and polygons), this will be a good place to say "coming soon" and a reference for people to know what map types they can make with their selected geometry type.

• Styling points: Color and Size

  • Very similar to what we have started here but much cleaner and more refined
  • GOAL: by the time someone is done with this guide, they will know how to make basic point maps using either numeric or category attributes

• Styling lines: Color and Size

  • Similar to what we have for the Styling Points guide
  • GOAL: by the time someone is done with theis guide, they will know how to make basic line maps using either numeric or category attributes

• Styling polygons: Color

  • Similar to what we have for the Styling Points and Styling Lines guides
  • For features that aren't available for polygons (quantiles, etc. we can put in a placeholder saying "coming soon" or something similar
  • GOAL: by the time someone is done with theis guide, they will know how to make basic polygon maps using either numeric or category attributes

Animations

• Introduction to Animations
  • syntax
    • why do we use filter for animations?
    • interpolation of a date field (linear($date, time(' '), time(' '))
    • what are each of the properties (duration, fade how do they interact with each other?)
    • when would you have a high x fade and a low y and vice versa
  • how to use opacity with animations (different than using opacity on features and serves a different purpose)

Interactivity

• Introduction to Interactivity
  • kinds of interactivity (popup, hover, style, etc.)
  • using variables (that we introduced in basic syntax)
  • where to define in application

[makella]

And a higher level topic that will be good to know for all of us making guides and talking with people, if someone says to you "I want to make a map with VL" do you point them to the styling editor or directly to the examples page?

The examples use the string API, is that how we want to write the guides as well?

Also, when the syntax starts getting long how do we want to familiarize people with writing?

• For example:

width: blend(1,
            blend(10, 50*linear($amount,viewportMIN($amount),viewportMAX($amount)), linear(zoom(), 2^14, 
            2^16)),
            linear(zoom(), 2^13, 2^14)
) 
color: rgba(255,255,255,0.2)
strokeColor: ramp(top($category,5),vivid)
strokeWidth: 1 

What are our best practices for using variables?

[arianaescobar]

Puuuuurrrfect outline @makella thank you so much!! ✨

if someone says to you "I want to make a map with VL" do you point them to the styling editor or directly to the examples page?

I'd say https://carto.com/developers/carto-vl/ and let them surf it all. I wouldn't share the styling editor externally until we improve its UI a bit 🙈

The examples use the string API, is that how we want to write the guides as well?

Prolly not a question for me but I'd say that sharing both methods would be the ideal scenario.

[makella]

Google doc

Let's do all the draft guides in the sub-folder Beta Guides:
https://drive.google.com/drive/folders/1WOxbhpyooUCnntjXxah_hIvy73WJcPHZ?usp=sharing

Once you have a guide ready for review, please tag one or two people to read through!

Guide assignments

@IagoLast once you have the Quickstart Guide and @Jesus89 once you have the Syntax guide, the rest of us can make sure to follow the syntax/structure as you both have described in those (i.e. variables, etc.).

The number before each topic, indicates its ordering in the guides and progressive concept building. The doc for that guide with the outline above is available in the link below each topic.

@IagoLast

1: Quickstart Guide
https://docs.google.com/document/d/1ObAVHjifx5kyrwtwE-r8HqAoRmN5objIV86asKHqRVA/edit?usp=sharing
7: Introduction to Interactivity
https://docs.google.com/document/d/1xULcsP8pw739bujz8GhTDA4_rMLQNdYwuct6abqprGE/edit?usp=sharing

@Jesus89

2: Introduction to Syntax
https://docs.google.com/document/d/1dWaJ0SFPgkB22R1oE9LkacES7baBAJ0ihZYafbiD0eM/edit?usp=sharing
3: Introduction to Expressions
https://docs.google.com/document/d/1y1v8idhDDBFjviiCt_cHQEqCyMVdMFPBObJ5ZWa9NLs/edit?usp=sharing

@davidmanzanares

4: Introduction to Interpolation
https://docs.google.com/document/d/1U2Tl4QBRm-aCkUajbaz39eMlSgIyhDOq22HRnQhfPvY/edit?usp=sharing

@makella

5: Introduction to Styling by Geometry (point, line, and poly)
https://docs.google.com/document/d/17GHCtedI2fx70XVh35gP9ewWKyRcpRttp3QdGS0B8Q4/edit?usp=sharing

@jgoizueta

6: Introduction to Animations
https://docs.google.com/document/d/1pshLnfpOexEMNTAx3Mr37T_4wUue1oCKU2XYgUiqNC8/edit?usp=sharing

cc @rochoa @arianaescobar

[makella]

Also, if you want to swap topics, go for it! Just update us here.

[davidmanzanares]

Hmu... I'm seeing many times that I want to explain something in more detail or talk in general about some advanced uses cases or topics. Could we have some "Advanced" sections inlined inside the guides?

For example, it is important to talk about the CieLAB interpolation we have or about why you should use the square root when you are making a bubble map. But, at the same time, they are advanced topics.

I imagine some inline sections with a label marking it as advanced like this:

• Interpolation Guide
• Introduction
• Use cases
  • Mapping an input variable to different colors or point sizes
  • bla bla bla
  • Advanced section: Why you should use sqrt
    • Advanced bla bla bla
  • bla bla bla (regular)

And so on

What do you think? @makella @arianaescobar

[arianaescobar]

That we should definitely have that content somewhere, maybe there, maybe in separate guides, but not right now. For now, let's keep it simple, in the basics, and let's not dive any deeper.

[makella]

@davidmanzanares feel free to make your Introduction to Interpolation guide about the topics that you think are good to introduce.

We have some of the sqrt, etc. topics in the Introduction to Expressions guide that @Jesus89 is working on -- more than the "why" it is introducing expressions with examples of some of the most common ones that people will use. THere is an outline in there and you can add ideas if something is missing. Actually, feel free to do that for any of them!

For mapping input variables to different colors and sizes, I am working on styling geometry (point, line, polygons) guide which should cover that.

We will talk about the "why" but these guides are also just to introduce some of the high level, important topics (expressions, interpolation, animation, and interactivity) so we can build off of them for the next set of guides that will be more advanced without having to explain everything again.

[arianaescobar]

Let me know if I can help with this somehow!