line/rect annotations

[nicolaskruchten]

So with the new add_hline-style functions we're adding in #2558 it'll be really easy to add lines in various contexts. Now what about labelling those lines? Plotly.js doesn't currently have the ability to label shapes, and won't for a while, so users are stuck adding annotations. For a horizontal line, the user might want to add an annotation anchored to the left (right, middle) of the plot, above (below) the line, so 6 possible positions, say. For a rect the same would be true for the top and bottom of the rect (for 12 possible positions, say). How can we make this easier for users?

Should we add add_hline_annotation() which would accept annotation kwargs plus an extra relative_position arg that would be line "above middle" or something? Or should we shoehorn in a couple of extra kwargs in add_hline() itself like annotation=dict(...), annotation_position="above middle" ?

@nicholas-esterer @alexcjohnson @emmanuelle @jonmmease thoughts?

[nicolaskruchten]

OK so our conversation today yielded another few options:

@jonmmease suggested we go a bit deeper and add support for xref="x2 domain" to stuff like add_shapes() when not using row/col and xref="domain" when using them (and having the domain to paper multiplication happen under the hood). A natural outgrowth of that would be to push this logic down into Plotly.js itself and then we wouldn't "freeze" the numbers in the figure.

Another approach would be to leverage for_each_shape and document a pattern for adding annotations that way. This would be facilitated by a new field in the schema like uid or name or something for the shapes so we could target them precisely

[nicolaskruchten]

So just to clarify here, if we had xref='x domain', say, then to add an annotation near a line we would just use .add_annotation(row="all", col="all", xref="domain", x=0, y=<whatever>, ...) where ... needs to be turning off the arrow, setting the offset etc. I still think that .add_hline_annotation() is shorter, and an annotation kwarg to add_hline is even shorter. Starting to really lean towards the latter, without magic underscores for the annotation bit.

[nicolaskruchten]

OK, having thought about it some more, I'd like us to add the annotation argument to the four new functions and to support magic underscores for kwargs prefixed annotation_ (except for annotation_placement, which would be reserved for a string like "top left" (lines) or "inside bottom center" (rects).

So when this is done I should be able to do:

fig.add_hline(y=6, annotation=go.Annotation(text="hello"))
# verbose but this is the basic mechanism

fig.add_hline(y=6, annotation=dict(text="hello")) 
# converts to go.Annotation

fig.add_hline(y=6, annotation_text="hello") 
# magic underscores ... this will be the common case!

fig.add_hline(y=6, annotation_text="hello", annotation_position="bottom right") 
# default annotation_position TBD per function, proposals welcome

fig.add_hrect(y0=6, y1=7, annotation_text="hello", annotation_position="inside bottom right")
# rect will parse for "inside" and "outside" positions

fig.add_hline(y=6, annotation_text="hello", annotation_position="inside bottom right",
                        annotation_x=0.2)
# this should be allowed: magic underscores will overwrite annotation_position

[nicholas-esterer]

I didn't see that you had already come up with syntax for annotation_position. I thought about this a bit and thought there might be ambiguity for the corner positions, and thought about using compass position. But I'm open to translating the compass positions into more descriptive version like you have. Check out this code pen for what I have so far:
https://codepen.io/nicholas-esterer/pen/gOrqQRx?editors=0010
In any case this shows a mapping between annotation_position and the arguments to add_annotation (hover over the annotations to see more detail on this).

[nicolaskruchten]

I like the compass positions, but we already have attributes that use inside/outside (e.g. text on bars), bottom/middle/top (e.g. layout.legend.yanchor), and left/center/right (e.g. layout.legend.xanchor) so I think we'll want to stay consistent with those ideally. NB the distinction between middle and center ;)

[nicolaskruchten]

Note also that I don't think the annotation_position argument should impact the annotation orientation as it does in your codepen... the text orientation should remain as the default horizontal unless overridden by the user.

Finally, I also think that under every variant of annotation_position the annotation should remain within the plot: the user can move it out by playing with the anchor parameters if they like.

[nicholas-esterer]

I put orientation just to see how it would look because originally I wondered if I wouldn't have to change xanchor and yanchor if I change the orientation. But in the end I don't so it's left over from that.
Yes we can get rid of those outside the plot, I agree that 'ne' is just a variation on 'nne', but I wonder if some people would want the annotation to be next to the line, just off the plot (like I have for 'e' on the hline).
Let me make a similar plot but using the more descriptive names and you can let me know if it makes sense.

[nicolaskruchten]

I think the built-in positioning should all be in the plot, and then the user can use the full xanchor/x pattern to move them out.