add info_scale documentation

[LittleBeannie]

No description provided.

[nanxstats]

It is an anti-pattern to define info_scale = c(0, 1, 2) and have the logic below:

info_scale <- if (methods::missingArg(info_scale)) {
  2
} else {
  match.arg(as.character(info_scale), choices = 0:2)
}

because you are trying to change the actual default to 2 from the percepted default 0 in convention.

If you want to use 2 as the default, then the best way is to define info_scale = c("2", "0", "1") and do this in the function body

info_scale <- match.arg(info_scale)

Please take a look at https://design.tidyverse.org/def-enum.html and update the argument definition and logic.

[LittleBeannie]

It is an anti-pattern to define info_scale = c(0, 1, 2) and have the logic below:

info_scale <- if (methods::missingArg(info_scale)) {
  2
} else {
  match.arg(as.character(info_scale), choices = 0:2)
}

because you are trying to change the actual default to 2 from the percepted default 0 in convention.

If you want to use 2 as the default, then the best way is to define info_scale = c("2", "0", "1") and do this in the function body

info_scale <- match.arg(info_scale)

Please take a look at https://design.tidyverse.org/def-enum.html and update the argument definition and logic.

Thanks for the suggestion! Just correct in the following commit.

[nanxstats]

OK. I think we are getting close.

First, the canonical use of match.arg() is to match values in a character vector, not a numeric vector. Second, the list is not long, so there is no need to use choices.

To me, this would be ideal:

function (info_scale = c("2", "0", "1")) {
    info_scale <- match.arg(info_scale)
}

The options are indeed character strings instead of numeric values --- although they look like numeric.

The long-term solution is to have better names for these options, instead of using "0", "1", "2", if that makes sense.

[LittleBeannie]

although they look like nu

Thanks for the suggestion! If we have function (info_scale = c("2", "0", "1")) {info_scale <- match.arg(info_scale)}, do user input info_scale = 1 or info_scale = "1"? The latter might not be straightforward since it quotes a numerical number...

[nanxstats]

Thanks for the suggestion! If we have function (info_scale = c("2", "0", "1")) {info_scale <- match.arg(info_scale)}, do user input info_scale = 1 or info_scale = "1"? The latter might not be straightforward since it quotes a numerical number...

Good thinking, but just because something is shorter or easier to type doesn't always mean it's better: it needs to be correct first. Feeling unnatural to quote them is merely a symptom. The root cause is that these options should be named in words instead of numbers. To address this now, I can propose to rename the options as:

c("combined_variance", "null_variance", "alternative_variance")

Any thoughts?

[nanxstats]

Now everything builds, let's merge this.

The check errors are all fixed. They were simply due to some info_scale == conditions still using 0, 1, 2 on RHS. The error messages were misleading.

A quick note on the enumerated option names we agreed:

"h0_h1_info", "h0_info", "h1_info" correspond to the original options 2, 0, 1.

function (info_scale = c("h0_h1_info", "h0_info", "h1_info")) {
  info_scale <- match.arg(info_scale)
  ...
}