need palette improvements

[dankelley]

First, a note -- this carries on a bit from some discussion in issue #427 and #407 although it is separate enough to be in its own category.

The newly written function colorize() is meant to address issue #427 but also as a possible replacement for makePalette(). Arguably, the new code could get folded into the existing makePalette(), but I prefer the new name because it seems closer to the actual action.

Argument for the new name: I think makePalette() could be taken to mean "draw the palette", which it does not do. So the name was not good to start with. Furthermore, the new colorize() does more than just palette calculations, because it can return colours for points in a scatterplot and of course that could be created without drawing a palette.

There are some things remaining to do, but this function may be ready for "alpha" testing.

QUESTIONS:

1. Is the name colorize() ok?
2. If this gets working well enough, can makePalette() be deleted?
3. What are opinions on an idea I have, that newly minted functions that are likely to change would get a name like colorizeAlpha(), to be changed to colorizeBeta() after some time (perhaps a time signaled in the docs) and then to just colorize(). My idea with this is that the alpha function could be left for a few months (really, any time) to keep from disrupting the work of early adopters.

[richardsc]

See answers in thread at issue #427, however, I will point out that I don't think the proposed functionality for makePalette() (i.e. issue #407) has really been hashed out yet.

[richardsc]

A few thoughts:

• I still don't understand intimately what the intended functionality of the fix (currently colorize())will be for imagep() plots, in terms of how to specify both the color scheme, the breaks, and the desired zlim for the plot. Doesn't imagep() do all this through it's args already?
• I also don't really understand the difference between the colors and palette args. Why should there be two different ways of getting colors?
• I also don't understand what breaksPerLevel does. Doesn't a "break" correspond to a "level"? I tested it with one of the examples, and it didn't seem to make any change.

[richardsc]

Another thought.

On the topic of folding the makePalette() functionality into colorize(), I thought that a way of mapping a color scheme to a specific set of values could be pretty useful. The "GMT" and "globe" plots which are examples in colorize are good examples, in that I could see where one might want to have z limits that aren't symmetrical around 0, but still have the coastline colored appropriately (white to green transition).

This is perhaps a bit different from the basic implementation of colorize() that will happen in the short term, but I didn't want to make another issue in this early stage.

[dankelley]

1. colorize can do two things: (a) figure out colours for a set of values, and (b) figure out colours for a palette or image. The breaks and col return values for colorize can match up to the input args for drawPalette() or for imagep(), and the zcol return value matches up to col for plot(). So, in cases of using a scatterplot with a colorer, colorize will ensure that colours match up.
2. originally I had the ability to recognize a character string in colors but then I relized that that would be making it do double-duty, which is confusing. I decided to make a whole new arg called palette. For now, palette can only name one of 3 existing palettes, but I can extend it to take user-create palettes.
3. breaksPerLevel is borrowed from makePalette(), and the idea there is that to permit either quantized colours (just one colour for 0 to 100m elevation maybe) or blending colours smoothly. Possibly I've not coded this in correctly yet.

I think we're on the same wavelength here, and probably the colorize() manpage isn't clear enough.

PS. I'm losing track a bit on the comments, but to reply to another -- yes, the idea is that a palette will be accepted by imagep() directly, for users who don't want to save the result from colorize() and use its breaks and col values for the existing imagep() arguments.

[richardsc]

Ok, I think I see what you mean by colors vs palette ... the colors arg refers to a function that returns a vector of colors based on the internals of the function (e.g. of the oceColorsX variety), where palette refers to a new thing, inspired by the GMT palettes, which specifically map colors to a value (e.g. level 0 is always "white").

I see that from looking at the code, and the palette2breakscolor() function, which defines the new palettes.

I was confused because "colors" and "palettes" are terms that we tend to use interchangeable, whereas the proposed functionality distinguishes them. I.e. a "color" has to be mapped to values whereas a "palette" has the mapping implicit?

[dankelley]

Yes, a palette connects breaks an colours. The word "colormap" might be better. I think that's what GMT calls it and maybe matlab too.

Actually, come to think of it, I find "colormap" a much better word. It implies a mapping between colour and something. A "palette" is a place from which to draw colours (in an artist's sense).

I could see an argument for drawPalette() to get a synonym drawColormap(). Of course I wouldn't want to destroy the old meaning because it's been in existence a long time, and it cannot be that bad since it's been in use for a long time.

Going offline for a few hours.

[dankelley]

Hm. Now I'm thinking colormap() would be a good name for a function that creates what I have above been calling a "palette" (but which I think I'd prefer to call a "colormap"). It should be able to create them based on GMT files but also based on a user interface yet to be decided but perhaps something like

colormap(x, color, GMT)

where GMT could be a local file in GMT format or something on the web (R is happy to take a URL for a filename), for one method of doing it, and for a second method, x and color would be vectors e.g. x=c(-1, 0, 1) and color=c("blue","white","red") would give a palette blending from blue to white to red.

[richardsc]

I also like the name colormap, actually. One downside is it's the same as a function in matlab which is similar, but behaves fundamentally differently because of the way matlab does plotting. Thus, it might be confusing for users switching. On the other hand, would it be more confusing than a whole new set of functions?

[dankelley]

I think I'll write colormap() tomorrow, with also args for missing colours, etc as GMT.

Although this has been two-steps-forward-one-step-back, progress is being made, and I like the idea of making things more robust for users so they don't have to spend as much time thinking about setting up breaks and col.

[richardsc]

Does this mean that colorize() is going the way of the dodo, replaced by colormap()?

[dankelley]

I was thinking more that colorize(..., palette, ...) would become colorize(..., colormap, ...) and that the newly-renamed argument could be a known named colormap (like the GMT ones) or one from this new function colormap. Like maybe

c <- colorize(z, colormap="GMT_ocean")

or

c <- colorize(z, colormap=colormap(c(-1, 0, 1), c("blue", "white", "red"))

and so forth, after which the c can be used directly in Oce things like imagep() and drawPalette(), and the relevant components of c can be used by non-oce things like

plot(.., col=c$zcol)

I know this is confusing!

The idea I am trying to do is to employ a unix approach of subdividing tasks in such a way that they can be used for different purposes. For example, it would be possible to add a bunch of more args to colorize() to set up a user colormap, but functions with a lot of args are hard to understand (and code).

[dankelley]

Fixed in develop