docs should note limits for SA, CT, and p

[dankelley]

This stems from #54 (comment) I'll do it on the weekend.

[dankelley]

It looks like I never did this, despite my "on the weekend" comment.

[dankelley]

I'm returning to this old issue. Frankly, I forgot about it. I am not 100% sure what ought to be said, to be honest. Below is the gsw_infunnel code in the Matlab version file Toolbox/library/gsw_infunnel.m, and it is not something that can be easily stated in e.g. the docs for the SA and CT parameters to the various functions. Note that the Matlab online docs don't list limits on SA and CT, and I think that's for the same reason: it's kind of complicated.

I feel that maybe I ought to add an in_funnel function to GSW-R, and then in the templates that generate the docs for SA etc, reference can be made, perhaps by changing

#' @param SA Absolute Salinity [ g/kg ]

to

#' @param SA Absolute Salinity [ g/kg ].  Use `gsw_infunnel()` to test for the validity of the calculation.

Although I'm not sure this will always apply. Perhaps some things can be calculated even if the data do not fit in this "funnel".

I need to do some more reading, anyway, so the docs can refer to a specific section of a specific document.

I'm sorry I didn't catch this in the recent CRAN submission. But changes can be made, in preparation for a new submission, perhaps 6 months from now. (I do not see this as a high priority because the goal of GSW-R is to provide an interface to GSW calculations, not to replace the detailed and extensive scientific background to those calculations.)

Matlab code

in_funnel = ones(size(SA));

in_funnel(p > 8000 |...
    SA < 0 |...
    SA > 42 |...
    (p < 500 & CT < gsw_CT_freezing(SA,p)) |...
    (p >= 500 & p < 6500 & SA < p*5e-3 - 2.5) |...
    (p > 500 & p < 6500 & CT > (31.66666666666667 - p*3.333333333333334e-3)) | ...
    (p >= 500 & CT < gsw_CT_freezing(SA,500)) |...
    (p >= 6500 & SA < 30) |...
    (p >= 6500 & CT > 10.0)) = 0;

in_funnel(isnan(SA) | isnan(CT) | isnan(p)) = NaN;

[dankelley]

The docs https://www.teos-10.org/pubs/gsw/html/gsw_infunnel.html say

Note. The term "funnel" describes the range of SA, CT and p over which
  the error in the fit of the computationally-efficient
  expression for specific volume in terms of SA, CT and p was calculated
  (IOC et al., 2010; McDougall et al., 2003; Roquet et al., 2015).

so I should not be referring to this for in the overall templates for SA, CT and p. And if it goes as an additional template with the Description section, I'll need to make a decision about the list of functions to which it applies. For sure, we have gsw_rho() but some thought is merited for the others.

But I come now to the main philosophy of GSW-R, which is to expose users to the TEOS-10 algorithms, not to try to replace the extensive, detailed, well-vetted and peer-reviewed publications in the TEOS-10 literature.

Based on the above, my decision at the moment is simply to add an gsw_infunnel() function, and to leave documentation for the other 154 functions in GSW-R as-is. Do you object to this, @richardsc?

[dankelley]

@richardsc I went ahead and coded gsw_infunnel() into "develop" commit 1ababc1. If you have time, perhaps you can take a look at the code (it's at the end of R/gsw.R) to see if I've transliterated correctly from Matlab to R.

Please note that I've put the Matlab code in as comments, for now, but I'll remove them later if you think I've translated it correctly.

The reason I need a check is that I typed the code instead of doing a copy/edit operation. (Typing it was a chance for me to examine what it was doing, but actually on my first attempt I missed a term!)

No big rush, since this issue has been open for 10 months, but on the other hand it would be great if I could close it later this week so we will be all-clear on gsw issues.

Thanks!!

[dankelley]

I am closing this issue now, because (a) I think it has been handled, and (b) it's been nearly a year since any comments were made.