Export guide_axis() and consider improvements

[hadley]

Currently we have no equivalent to guide_legend() for axes (there is an non-exported guide_axis() but it draws the axes rather than describing their parameters). We should have an exported guide object to make it possible to have new types of axes.

The build in guide_axes() also needs to gain better tools for handling long labels:

• Should haveangle parameter which handles all related theme settings
• Should optionally trim overlapping labels by starting and either end and bisecting inwards (cf check.overlap = TRUE in grid.text()
• Should be able to draw multiple lines of labels, alternating the position to avoid overlaps

And generally look at what vega-lite does for other ideas of useful parameters.

[paleolimbot]

I spent about a day and a half on this, and wanted to leave a few things here for when I pick it back up again. So far I've:

• Refactored guide_axis() to draw_axis(), since that's what the current version actually does (creates a grob)
• Created a guide_axis() implementation that mimics guide_legend() and changed draw_axis() to create a guide, train it, then draw it.
• Rewrote the grob creation code so that it might be easier to add features to (in a way that doesn't cause any dopplegangers to change)

https://github.com/paleolimbot/ggplot2/blob/0267a0aa48863b119f8288f95eac6fe87d89d95f/R/guides-axis.r#L125-L256

I still have to (provided all agree this is a good idea)

• Refactor scale and guide code to treat position guides like other guides so they can be specified within scale_x_*(), scale_y_*(), sec_axis(), and guides()
• Refactor Coord code to use guides the guides specified in scale_x_*(), scale_y_*(), sec_axis(), and guides() instead of using draw_axis()
• Collect input on what (if any) improvements should go in guide_axis(), or if they should go in some other guide function (guide_axis_fancy(), or the like)

For reference, the vega-lite axis label documentation, which includes an option in inward-align labels on the end.

[clauswilke]

Would this be an opportunity to move the entire guide system to ggproto? It's the one remaining major part of ggplot2 that doesn't use ggproto, and it's a bit of a mess and difficult to extend by external package developers.

[hadley]

I think it's probably worth making that a separate issue.

[clauswilke]

Sure, I opened a separate issue (#3329). My main reason for bringing it up here is that I think it would be good to get both changes into the same ggplot2 release, so that we don't create even more downstream dependencies that need to be broken if we ever refactor the guide system.

[hadley]

Agreed.

[paleolimbot]

I've gotten this to work two ways now, and I would be grateful for some opinions on how best to go about things moving forward.

Getting guide specifications from the position Scales to Coord$render_axis_(h|v)() is not trivial. Both versions I have working use the Layout to coordinate panel guides, which (like the other guides) are resolved and trained at draw time (i.e., ggplot_gtable()). The Coord is responsible for generating a set of guides that it will receive in Coord$render_axis_(h|v)(), much like it does with panel_params.

I've gotten to versions to work (i.e., pass CMD check with no visual changes), one of which "injects" the panel guides into panel_params$guides in Layout$render() ( master...paleolimbot:issue-3322-guide-axis-panel-params ), and the other of which adds a panel_guides argument to Coord$render_axis_(h|v)() and Facet$draw_panels() ( master...paleolimbot:issue-3322-guide-axis-layout ). The first one I think is way better since it doesn't result in breaking any extensions of Facets or Coords.

It might be possible to avoid any changes outside CoordCartesian (as well as some other guide code) if the guides were generated at build time, but then they wouldn't have access to the same things that the other guides do (layers, default mapping, global guides list).

[paleolimbot]

I suppose I'm curious whether having the Layout coordinate panel guides is appropriate, whether the internal changes in the other guide code that was required to make this work are likely to have effects in other places, and whether or not it would be more prudent to clean up the guide code first (#3329).