package documentation/"cookbook" about cmapplot

[nmpeterson]

I've generated an initial version of a pkgdown site for this package, using all code exactly as-is in master currently. Take a look: https://cmap-repos.github.io/cmapplot/

Looking at the list of functions on the Reference page, I think we'll definitely want to make sure we're only exporting the functions that we want to be public-facing, as opposed to helper functions that are just for package functionality. We aldo might want to give the example datasets a prefix like "data_" so that they all get grouped together. (Or maybe there's a way to avoid having datasets appear in the functions list. I don't know.)

Oh, and everyone (@gritzenthaler, @dlcomeaux, @sarahcmap, @MMenninger) should add their names to the DESCRIPTION file :)

[nmpeterson]

The README file just needs to be re-knit when someone gets access to Whitney. I tested it out -- see commit 4a5d3ae -- but I've reverted the change because I did it on my Mac so all of the images were updated to use Arial. Font sizes looked good, though.

[nmpeterson]

It "draws" the blank (which also gets saved, due to how knitr works) and exports the populated plot to PNG as expected, without displaying it automatically in the knitted document. I can send you my test code if you want to see exactly what I mean.

[nmpeterson]

I have created a (currently empty) branch called gh-pages that will be used to build a pkgdown site that will then be hosted on this repo's GitHub pages URL (i.e. https://cmap-repos.github.io/cmapplot). I'll be looking into exactly how to build that site soon, and expect that eventually much of the example code that is currently in readme.md (which is very long) can be moved to one or more pages of examples on the pkgdown site.

[dlcomeaux]

Thanks for doing this! One thing I noticed was that the font sizes do not seem to be working very well in the examples. I imagine that is a consequence of us modifying the font size to now be 14, but wanted to flag as something we'll have to adjust (do we do that in the readme?)

[nmpeterson]

If we want to include finalize_plot-rendered charts in our documentation, we'll have to be careful about how we do so. Rmarkdown doesn't seem to play nice with finalize_plot -- I'm not getting errors, but the final charts get cropped pretty violently.

However, if the Rmarkdown files call finalize_plot with mode="png" and specify the output location as the same folder as the rest of the documentation's auto-generated images, we can then use a regular markdown expression (outside of an R codeblock) to display that image in the exported documentation:

```{r eval=TRUE}
finalize_plot(testplot, mode="png", filename="./man/figures/README-TEST.png")
```

![](./man/figures/README-TEST.png)

[matthewstern]

The way markdown works, we'd ideally want to export it in mode="plot", right? That way it draws it directly into the knit html file?

It looks like the default image canvas is 5" high x 7" tall, but this can be changed:
http://zevross.com/blog/2017/06/19/tips-and-tricks-for-working-with-images-and-figures-in-r-markdown-documents/
https://sebastiansauer.github.io/figure_sizing_knitr/

A quick test on my machine reveals that any larger than 5x7 and I get cropping with the image anchored (strangely enough) to the bottom right corner of the available canvas. Any smaller than that and I get some of the gray canvas that gets drawn around the plot. But at 5x7 it seems to work decently. Strangely, though, an unusual amount of white space is placed between the code block and it's output:

[matthewstern]

• Item to consider/do: document cmapplot_globals enviro, including describing plot_constants. This would ideally involve placing the margins image in a documentation file.

[nmpeterson]

The way markdown works, we'd ideally want to export it in mode="plot", right? That way it draws it directly into the knit html file?

Correct.

It looks like the default image canvas is 5" high x 7" tall, but this can be changed:
http://zevross.com/blog/2017/06/19/tips-and-tricks-for-working-with-images-and-figures-in-r-markdown-documents/
https://sebastiansauer.github.io/figure_sizing_knitr/

A quick test on my machine reveals that any larger than 5x7 and I get cropping with the image anchored (strangely enough) to the bottom right corner of the available canvas. Any smaller than that and I get some of the gray canvas that gets drawn around the plot. But at 5x7 it seems to work decently. Strangely, though, an unusual amount of white space is placed between the code block and it's output

I was getting the same odd spacing in my tests.

[nmpeterson]

Initial pkgdown configuration has been done in #61.

Potential improvements:

• Add a really flashy sample plot back to README.Rmd to show off the package's capabilities on the main page, since all of the existing examples got split out into vignettes/articles.
• Add more vignettes, and/or refine the two that currently exist (vignettes/plots.Rmd is sort of a cookbook containing a bunch of example plots using the sample datasets in the package, and vignettes/colors.Rmd contains information about the color palettes/gradients).
• Currently, finalize_plot is not used in either vignette, and geom_recessions and integer_breaks have not been used in the cookbook. I think finalize_plot warrants its own vignette.
• Everything was generated on my Mac, so all the text is currently Arial.

[matthewstern]

@nmpeterson it occurred to me after our meeting this morning that it might be worth trying running as.ggplot() on the object returned by finalize_plot(mode = "object") and see if that prints any better in the markdown file. I have no idea if there is a discrepancy in how the stitching process handles ggplot objects vs grid objects.

[nmpeterson]

I think the bbplot cookbook is a really excellent inspiration for what the theme_cmap() and finalize_plot() vignettes could look like.

[nmpeterson]

FYI @matthewstern the reason there is a big gap between code and plot when we knit with finalize_plot() is that for some reason two images are being knit. First, a totally blank/white plot, followed by the actual rendered plot in a separate image.

❓❓❓

---

Edit: I'll also note that knitting a file with finalize_plot(mode="png") also outputs the blank plot. Do you and @dlcomeaux know why/where the function is generating this intermediate plot?

[matthewstern]

Good find @nmpeterson. When you say mode="png" outputs a blank plot, do you mean it saves two plots, or draws a blank one saves a populated one?

I have a few thoughts about this, I'll take a look this morning.

[matthewstern]

@nmpeterson: I think I have a lead on this.

Line 468 of finalize_plot runs grid::grid.newpage(). This creates a new plot, so that the arrows in the plot window can be used to toggle back and forth between plots. When I use the little broom to "erase all plots", and then run finalize, I get two plots-- if I use the back arrow, I can go find a blank plot. But, if I comment that line out, I only get a single plot.

It's strange that grid.newpage() would push two outputs--it should not. It doesn't on it's own--if you erase all plots then run grid.newpage() only, it only creates a single plot (the back arrow is not available).

It appears that a other things in the grid package can activate an inactive current drawing device, which apparently creates a new plot if no current plot exists. In our case, it looks like the convertunit function on line 215 (and probably many other functions in between line 215 and and 468) does this.

The challenge is dealing with it:

• In a situation where the user has previous plots, the "plot" device is already active. In this case, grid.newpage is important, so that the user can go back to view their previous plot if they want.
• However, in a situation where the device is not already active, convertunit activates it and then grid.newpage creates a second output. This has the meaningless impact of creating a blank plot "behind" the finished plot in interactive R, but the not desired impact of creating a published blank plot in knit files.

Is it possible to skip grid.newpage if R is knitting? Skip it if the current device is empty? One option I am confident will work is to place grid.newpage before line 215 in the script, but the negative consequence here is that it blanks out the current contents of the plot window even if finalize_plot is not on mode="plot", which is not ideal.

[matthewstern]

Note that in looking through this I found a view very small tweaks to make in finalize. They are now in a PR #63.

[matthewstern]

This would probably work: place if "plot" %in% mode { grid::grid.newpage() } near the beginning of finalize, and remove line 468.

EDIT: Yes, I believe this solved it. This change is now implemented in #63. @nmpeterson, let me know if knitting from the branch finalize_tweaks solves your problem.

[nmpeterson]

Awesome, this appears to have fixed the issue for knitting both modes, plot and PNG!