aitap / cmocean Goto Github PK

cmocean.html:

<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

This is documented in ?rmarkdown::html_document (which html_vignette inherits from) under the mathjax argument.

While this is currently not a problem and doesn't even break anything when browsing offline (we have no math in the vignette), I'd like to make sure that the vignette doesn't have any external dependencies.

I'm a big believer in vignettes, and I think it would be awesome to have one for this package. Again, some discussion from the email thread. Again, quoting @dankelley:

This is a tricky one, because I think CRAN may insist that it can rebuild vignettes, which means downloading data will be a problem. I am not really sure on the prebuilding aspect. I think that in past times, they wanted authors to create the completed vignette (often in .pdf format) but now they want to have authors provide Rmd files. The advantage of this Rmd method is that then CRAN (and users) will be less likely to run into documentation that is at odds with code. But I don’t think they will want large downloads, and the package may get rejected if a download fails.

Frankly, I think it would be fine to just show colourbars, like in the cmocean website. More beautiful real-world images might be pre-built and included as PNGs. But, to be honest, I would vote on sticking to just the colourbars, and I’d write text suggesting that people consult some of Kristen’s papers for details and more examples. I think all users would enjoy that reading that material.

I think just showing the colorbars is perfect for a start, but I also like the idea of including some real examples. Of course, for a package like this it makes sense to keep the dependencies minimal (ideally none).

What about including some small datasets with the package that could be used for the vignette? Maybe a text version of the levitus SST/SSS, a WOCE section, etc.

I'm just pulling from our email thread on discussions about this great new package, where @dankelley said:

An option that will likely be of least surprise to users would be to name as e.g. diff.colors().  I say this because a user who types

?colors

will see docs for several functions with names ending in ".colors", which means that many users will expect to see ".colors" at the end of functions of this variety.

My preferred way, however, would be to let the user type e.g.

library(cmocean)
image(..., col=cmocean("vorticity"))

to draw a vorticity image with the default version of the vorticity colormap, or maybe

image(..., col=cmocean("vorticity", 1))

for version 1, or

image(..., col=cmocean("vorticity", "2019-04-12"))

for the version on a certain date. The scheme for this is function-returning-function is in lines 2304:2315 of oce R/oce.R ("develop" branch).

The package viridis has some helper functions to allow the colour scale to be used effectively in ggplot2.

It would be great if this package would have some as well!

I just wrote one for the fill scale:

library(cmocean)
library(ggplot2)
library(tibble)

scale_fill_cmocean <- function(..., alpha = 1, begin = 0, end = 1,
                               direction = 1, discrete = FALSE,
                               option = "thermal") {
  if (discrete) {
    discrete_scale("fill", "cmocean", cmocean::cmocean(name = option, start = begin, end = end), ...)
  } else {
    scale_fill_gradientn(colours = cmocean::cmocean(name = option, start = begin, end = end)(n = 256), ...)
  }
}

dat <- tibble::tibble(a = 1:10, b = 11:20, c = stats::rnorm(10), d = sample(letters[1:3], 10, TRUE))

dat %>%
  ggplot(aes(x = a, y = b, fill = d)) +
  geom_raster() +
  scale_fill_cmocean(discrete = TRUE)

dat %>%
  ggplot(aes(x = a, y = b, fill = c)) +
  geom_raster() +
  scale_fill_cmocean()

^{Created on 2020-11-13 by the reprex package (v0.3.0)}

This works, but doesn't yet incorporate an alpha parameter yet.

As suggested by Clark Richards and Daniel Kelley in e-mail exchange, being able to request a particular version of palettes would be nice. One possible interface is

col <- switch(getOption("cmcolor-version", 1),
1=(values for version 1),
2=(values for version 2))

Future version of convert.r would need to loop over tags in matplotlib/cmocean and collect all versions of all palettes, then make a choice based on the user input, e.g. choose max(version[version <= user.version]).

Or something.