Plots.jl: Most plot types have no documentation

[aterenin]

Yesterday, I tried to remake the plots used in this paper of mine using Plots.jl.

To take an example, consider the contour plot in the appendix. This consists of a set of 6 plots arranged in a grid, with a contour plot in each one, and a line overlaid over it.

There is no documentation on contour. I have no idea how to remove the automatically generated legend from each subplot, nor how to change its colors to go from grey to white. The only option for contour that can be found by searching the documentation is fill - which is in fact not documented, but rather described in an example.

I tried to read the source code, but it is completely unclear where contour is even defined: I cannot find its definition by searching the Plots.jl repository, and Atom's hyperclick to view source takes me to a totally unrelated piece of code.

I apologize if this issue comes across as a bit abrasive, but I feel like I'm completely unable to use the large array of features this package offers because I have no way to determine how to invoke them. A Wickham-Wilkerson style Grammar of Graphics frontend interface would help, but fully documenting the available options and how to use them would help even more.

[joshday]

There is no documentation on contour

I searched for contour in the docs and immediately found http://docs.juliaplots.org/latest/examples/gr/#contours. A contour is just one of many series types. contour(args...) is equivalent to plot(args...; seriestype=:contour). Most keyword arguments are general and aren't tied to a seriestype.

I have no idea how to remove the automatically generated legend from each subplot

legend = false

nor how to change its colors to go from grey to white

http://docs.juliaplots.org/latest/colors/

color = :grays

I'm not saying all of this is easy to find (e.g. nothing shows up in the doc search for "color") or that the docs are complete, but there is a lot in there. If you have questions in the future, I'd encourage you to try the plotting channel in the julia slack. Firstly because answers typically come fast, and secondly because "needs more/better docs" issues already exist or are known. There isn't much to act on here.

[mkborregaard]

A Wickham-Wilkerson style Grammar of Graphics frontend interface would help, but fully documenting the available options and how to use them would help even more.

In general, reading through the documentation (rather than quickly searching it) is a preferred first step to try prior to stating that the docs don't exist, let alone suggesting changing the entire interface to the package :-)
Still, I'm curious why changing to GoG would be a big advantage in your opinion? Note that Plots follows the GoG spirit in separating input data (positional arguments) from plot/series type etc (keywords). It would be possible to implement a GoG interface, and there's even a stub package (GGPlots.jl) that shows how easy it would be - all it requires is for someone (like you?) to take ownership over implementing it fully.
Alternatively, you might want to check out Gadfly, which is a nice and solid plotting package for julia using GoG. Rumours of its death are exaggerated, as Sinatra said.

BTW I couldn't find the contour plots in the appendix. You make this kind of effort a lot easier if you upload the plot you want to replicate here directly, rather than expecting us to download your paper from Arxive and searching through it for an unspecified figure.

[aterenin]

Thanks very much! I want to emphasize that I very much did search the documentation, and was not able to find any of the above commands. This is the plot in question. Since contour is equivalent to plot(args...; seriestype=:contour), that is helpful, but what are the options I can give and what do they all mean? There is a list of them in the very bottom of an examples page, but this contains no information beyond the name of each argument and doesn't tell what are valid values for each one.

The reason I made this issue is that as a user, I shouldn't be asking online for help in order to make a plot - I should instead do that myself by reading the documentation. What would have helped immensely is if there was a page for contour that lists the options it has, like this page from ggplot - there is no analog in the documentation.

The reason I like GG-style interfaces is because the conceptual framework makes a lot of sense for creating the kind of data visualizations statisticians often use. In theory I'd love to contribute to GGPlots.jl but at present have too many other ongoing open source projects to add any others. I remember that Gadfly was abandoned last I looked at it, which was months ago - I didn't know development had started up again. It looks like they still don't support anything like geom_raster, so making the plot in question is impossible in Gadfly. And software-wise, it makes more sense to have a GG-style interface on top of a broad framework like Plots.jl than to have a whole separate package.

[mkborregaard]

There's a full list of all keyword attributes here: http://docs.juliaplots.org/latest/attributes/
All calls to plot accept those same attributes.

[mkborregaard]

Unfortunately I think that particular series type is not yet supported by Plots. I think you're not looking for a standard contour plot, but rather an "implicit plot" which in matplotlib can be plotted with the contour function, no? https://discourse.julialang.org/t/implicit-plot-with-plots/6585/8

[aterenin]

Ok, thanks. It is clear I somehow completely failed at finding any of that through reading the documentation. I'll try again. My apologies for wasting everyone's time. 😳

As a final comment, from a UI/UX point of view, it'd probably help to have hyperlinks to that list throughout the documentation, as well as to display it at least the same font size as the rest of the page, because it is very important. It'd be even better if there was a way to access it using Julia's ? syntax for opening documentation, but this is beyond the scope here.

[mkborregaard]

Doc PRs are really welcome if you have good ideas.

WRT using Julia's ? syntax that only supports looking up functions. That can be done for e.g. contour, which is called as a function, and we've just added the capability to do that by writing a docstring before each call to @shorthands (https://github.com/JuliaPlots/RecipesBase.jl/pull/34) so it's just a question of writing those docstrings.

But that can't be used to lookup keywords, qua the julia doc system. Instead, we offer a plotattr function, e.g.:

julia> plotattr(:Series)
Defined Series attributes are:
arrow, bar_edges, bar_position, bar_width, bins, contours, fill_z, fillalpha, fillcolor, fillrange, group, hover, label, levels, line_z, linealpha, linecolor, linestyle, linewidth, marker_z, markeralpha, markercolor, markershape, markersize, markerstrokealpha, markerstrokecolor, markerstrokestyle, markerstrokewidth, match_dimensions, normalize, orientation, primary, quiver, ribbon, series_annotations, seriesalpha, seriescolor, seriestype, smooth, stride, subplot, weights, x, xerror, y, yerror, z

julia> plotattr("color")  #note the differing use of Symbols and Strings here
seriescolor {Color Type}
c, color, colour, seriescolors

The base color for this series.  `:auto` (the default) will select a color from the subplot's `color_palette`, based on the order it was added to the subplot
Series attribute,  default: auto

which gives all the information from that table directly at the console.

[deszoeke]

I had the same issue not finding what I needed in the documentation, so this post and the responses are very helpful. Tables of attributes are more likely to be searched and skimmed, than pored over and remembered. It's dry reading, but important when you need it. I didn't appreciate that the tables in the docs are scrollable.

I read that a contour is a "seriestype" in Plots, but calling a contour a series is a bit of a neologism. I didn't look hard enough in series attributes to find attributes specifically for the contour plot.

A few examples of common plot types that link back to the tables of relevant attributes would give inexperienced users another way to triangulate the attributes they're interested in.

[mkborregaard]

Is that not what's found in the examples in the docs? Just to understand what you mean.

[deszoeke]

I had trouble finding the examples. The animated examples on the Intro page are eye candy but way to complicated to be useful for making plots for research or publication.

Examples belong to backends, apparently. Perhaps there could be examples or links to the examples on the backend pages, as relevant, at the end of each section.

The present GitHub pulldown menu navigation format makes navigating the Docs difficult. I actually didn't know the dropdown Ξ was the main navigation for the Docs for a while this morning. Now I've found it. It would be helpful to have a site map or table of contents where the reader can see the hierarchy of all the headings and subheadings in one glance, rather than having them in paging pulldowns, where you can only see one level at once. The subheadings within each section at the right are easy to read.

I think the Docs changed last night. How very responsive! The headings of the scrollable (e.g. attributes) reference tables should not scroll.

On Apr 17, 2018, at 1:18 PM, Michael Krabbe Borregaard [e-mail] wrote:

Is that not what's found in the examples in the docs? Just to understand what you mean.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub https://github.com/JuliaPlots/Plots.jl/issues/1339#issuecomment-382128159, or mute the thread https://github.com/notifications/unsubscribe-auth/AMnHc7tnc8RX_fWbjuC1Lqh4_g3Hezo4ks5tpk38gaJpZM4RTUhd.

[mkborregaard]

What webbrowser are you on? To me the docs look like this:

which is easy to navigate, and very easy to find the examples.

[deszoeke]

Indeed. On Safari the left navigation column doesn’t show up if my browser window is too narrow. It has to be at least 875 (retina) pixels across, and 1220 for larger comfortably sized fonts. This is not terribly practical for using as a reference manual with other windows (REPL, editor, plots) open. But now that I know it’s there, I won't have this problem anymore.

Links from keyword attributes in the reference tables to examples and vice versa would still be helpful.

On Apr 18, 2018, at 1:30 PM, Michael Krabbe Borregaard [e-mail] wrote:

What webbrowser are you on? To me the docs look like this:
https://user-images.githubusercontent.com/8429802/38956519-1b2b72a8-4358-11e8-8600-21ff4bfc52c2.png
which is easy to navigate, and very easy to find the examples.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub https://github.com/JuliaPlots/Plots.jl/issues/1339#issuecomment-382519379, or mute the thread https://github.com/notifications/unsubscribe-auth/AMnHc5gz7D4_VoJ-3kGvQNeVYCIrpzg2ks5tp6KDgaJpZM4RTUhd.

[aterenin]

I ended up giving up on Plots.jl and switching back to ggplot using Julia/R bindings via RCall, which are much much nicer than I would have ever expected, and have found this to be much cleaner and better suited to my workflow. If you're a former R user who just wants a grammar of graphics interface in Julia, it's likely to work quite well for you.

I wrote up my experience and posted it to my blog here: http://avt.im/blog/2018/03/23/R-packages-ggplot-in-julia

A warning: that post does contain my fairly unfiltered thoughts on why Plots.jl and any framework with a similar API is just not for me. I don't want to insult anyone's hard work, and am sure the package will work well for other people - but for those not wishing to read critical thoughts about their work, be forewarned.

[mkborregaard]

Thanks for the warning, I'll avoid reading it.
If you do want a GoG interface to plotting in Julia, http://gadflyjl.org/stable/ is really nice.

[mkborregaard]

Joke aside, I just had a look. I see you've tried Gadfly. From reading it it is actually not 100% clear to me what the problem is.
But here's one thing - we've actually talked about creating a GoG interface to Plots - it should be fairly easy, and there's already a (slightly dated) proof-of-concept here: https://github.com/JuliaPlots/GGPlots.jl

All it needs is someone enthusiastic about the Grammar of Graphics to take it and do it. Those very enthusiastic about GoG, unfortunately but naturally, tend to not become involved with Plots, which is really the problem. But that someone could count on getting good help from the org, I think.

[aterenin]

I'm really really hoping the state eventually moves to a GoG interface on top of Plots.jl rather than maintaining two separate packages, because this is much more sensible.

I've thought about working to contribute such an interface, but unfortunately I don't have the time capacity now, though that may change in the future. If anyone else is interested or an effort begins and someone sees this, please do get in touch.

[mkborregaard]

Please be in touch if you do find you can put the time to it at some point! Given the widespread use of Plots and GoG (though not together), it could be a project with a really high community-benefit-to-work ratio :-)