add annotations guide

[g3o2]

Following this vega-lite related issue as well as #749 , I wonder whether it would make sense adding a more general annotations guide in the same fashion as the axes or legends guides, allowing to place a text annotation anywhere in the visualisation. Examples of annotations are title, subtitle, source, explanations within the graph, etc.

Placement could happen in a similar fashion than legends (top, right, bottom, left, etc. , (x, y) values in encoding block, or even scale dependent x and y values). An array could contain several annotation objects, each one specified and placed on its own.

text marks can currently be used for that purpose but their use as annotations is not obvious to everyone. When there are many annotations, the use of text mark & co. will remain the way to go. Maybe a good short run solution would be to provide a quick tutorial or example on how annotations can already be implemented.

The advantages of annotations as a guide over annotations as a text mark instance are:

• more intuitive use for single instance annotations outside of the plot (e.g. title) and their better visibility in the spec, thus improving the documentation of the latter;
• no need for extra data, scale, filter transform, etc. definitions to render a single piece of text;

[Fil]

Yes. Please take a look at the fantastic work on annotations by @susielu
http://d3-annotation.susielu.com/

[jheer]

Great feature request. Not sure yet if/when we will get to it, but I agree this could be a very nice addition!

[domoritz]

CC @starry97

[kanitw]

vega/vega-lite#4055 also ask for subtitle in VL. :)

[bmschmidt]

+1. I suspect it's pretty common to want to include 'subtitle' and 'caption' elements (to use the ggplot2 terms) for explanation and attribution, respectively. Here's another request for subtitles in the altair repo I found searching for this: vega/altair#987.

An annotation grammar would be great, too. But--if you don't mind a maybe uninformed reaction!--other software has led me to think of annotations (which adhere to data inside the plot) and labels (on the margins of the full chart) as distinct, and I'm surprised to see them combined into one feature here. I can't see why subtitles should be 'annotations' in Vega-Lite when--for instance--axis labels are not. Such a general grammar for annotations could be interesting, especially in faceted plots; but I hate to see the capacity to provide basic attribution for data be blocked by something so much more sophisticated. Even the ability to create multiple title elements using the current grammar for a single title would help.

Thanks for your good work.

[kanitw]

But--if you don't mind a maybe uninformed reaction!--other software has led me to think of annotations (which adhere to data inside the plot) and labels (on the margins of the full chart) as distinct, and I'm surprised to see them combined into one feature here.

That's simply a feature request, not an official plan. :) If we were to add all/some of these, I think subtitle / caption should be separate from more generic annotations too.

[jheer]

I agree that subtitle / caption should be separate. As a starting point, we could consider the design of subtitle specification, perhaps as an extension of the existing title directive.

[g3o2]

The reason I initially put them together was the grammar of graphics as described in the "literature". Plus, there is a certain fuzziness to all the jargon. Anyhow, theory doesn't always translate 1:1 into practice.

[groodlooker]

I just wanted to point out that when using vega-embed, the susielu d3 annotations work quite well with vega if you use SVG as the renderer. If you don't mind blending the two, I'd recommend going that route for anyone else looking to incorporate annotations for the time being!

[kanitw]

For subtitle and caption, I wonder if we could just extend the title directive to support multiple entries (that are stacked). With the orient and style support that we already have, we can easily re-use this mechanism for caption / subtitle / "source" lines.

(We may want to rename it / provide different syntactic sugar though.)

[aaronbarzilai]

Related, I'm interested in chart subtitle as well (or at least wrapping title to two lines). I tried a few different tags, is there a way to force a line break in the title string to simulate a subtitle or second line of a title for now?

[domoritz]

There is some related work in vega/vega-lite#3401 and #1708.

[vorbei]

+1 for 'annotation' channel, it's like the 'tooltip' channel but always visible. I've been doing this manually for repeating encoding same x,y to text marks to do this, but still misses guide lines and other supports. It's a such a needed feature.

[armsp]

@groodlooker could you please please elaborate and give some example of what you are talking about. Even I think that being able to add Annotations like the website by @susielu would be great. Since I am new to this I don't understand how you were able to use d3 annotations in vega/vega-lite with Vega Embed.

[kcomplexes]

@vorbei Do you have any examples of how you have been doing this manually?

Has there been any progress on annotations? is it waiting on vega/vega-lite#3401, or does it need to be done separately?

[tbenst]

I’m not sure if designing syntax is the holdup here or not, so thought I’d point to ggplot2’s seemingly sensible syntax: https://ggplot2.tidyverse.org/reference/annotate.html