mapContour() should compensate for longitude cut points

[dankelley]

This came up in #2217. Maybe mapContour() ought to compensate for the cut point of longitude, i.e. whether data go from 0 to 360 or from -180 to 180. It might be a bit tricky, though, because we might also have to consider the view used in the present projection ... the case of #2217 is thus a sample case, but fixing it as @richardsc has done there might not be a general fix.

[dankelley]

I'm not sure of an easy way to make it compensate. The problem is that (at present) the hidden variable that defines the projection that was set up with mapPlot() does not store the range of data, or a user-supplied limit to the plot, or a possible x0 component of the projection specification. These three things might be needed to know the system (0 to 360 or -180 to 180) being used, the view that is active (including the par("usr") result). And there might be other aspects as well.

The other thing is that this code is really quite old and fairly complicated, and I worry that a change might cause problems for some use-cases that I am not imagining right now. All this argues against making mapContour() alter its behaviour in this respect. (The other thing is that this function is probably over a decade old, and this may be the first time in years -- perhaps ever -- that we have had a bug report on it.)

Given all of this, my decision is to document the need to be careful. So, tomorrow, I am likely to add the following to the docs. I'll mention the first block in the docs for the longitude parameter, but since it is quite long, I'll have the main part in the "Details" section, probably. (I need to do it and see how it looks.)

The second part would be a numbered example. If the examples are not already numbered, then I'll do that, and set X appropriately.

So this is just a heads-up. Most likely, when I read the text below, I'll want to reword for clarity and brevity. (Obviously, I'm writing roxygen2 here.)

#' Importantly, the `longitude` system must match that
#' used in the [mapPlot()] call that created the plot to which
#' contours are to be added.  Otherwise, contours can have spurious
#' lines that run from one side of the plot to the other. See Example
#' X.

#' # Example X: deal with z(lon,lat) defined with longitude expressed
#' # in the 0 to 360 system. This solution was suggested by Clark
#' # Richards at the discussion of issue 2217 on the oce github website.
#' #
#' # Create base plot for a dataset with -180 < longitude < 180.
#' data(coastlineWorld)
#' mapPlot(coastlineWorld)
#' #
#' # Assume that z(lon, lat) has 0 < lon < 360.
#' shiftLeft <- lon > 180
#' lonNew <- lon + 180
#' zNew <- rbind(z[shiftLeft, ], z[!shiftLeft, ])
#' mapContour(lonNew, lat, zNew)

[dankelley]

Commit 829b0bf of the "develop" branch handles this by improving on the documentation, as shown in the two snapshots below. I will check the remote builds in about an hour, and if they have not failed, I will close this issue and ask the reporter of issue #2217 to consider whether that issue has been addressed.

---

[dankelley]

The remote checks worked, so I am closing this issue now. My next step is to put a comment at #2217, noting this.