Unclear option in an ado file of a user-written routine

[Dario Maimone Ansaldo Patti]

Dear All,

I am looking at the following chunck of the ado file of the user written routine utest:

*** Module UTEST ***
* Change log
* 7.17.14 Version 1.1: Option prefix to handle multiple equations
* 2.22.16 Version 1.2: Fixed bug with trivial failure to reject H0
* 1.25.19 Version 1.3: Converted to rclass, return main results

program define utest, rclass
version 9

syntax varlist(min=2 max=2 numeric) [, MInimum(real -.12345) MAximum(real .12345) Quadratic Inverse Fieller Level(cilevel) PREfix(string)]
tokenize `varlist'
local var1="`1'"
local var2="`2'"

if "`prefix'"!="" & substr("`prefix'",-1,.)!=":" {
  local prefix "`prefix':"
  }

local df=e(df_r)

if `df'==. {
  
  local df=e(N) 
  }

mat beta=e(b)
mat covar=e(V)

mat b1=beta[1,"`prefix'`var1'"]
local  b1=b1[1,1]

mat b2=beta[1,"`prefix'`var2'"]
local  b2=b2[1,1]

mat s11=covar["`prefix'`var1'","`prefix'`var1'"]
mat s12=covar["`prefix'`var1'","`prefix'`var2'"]
mat s22=covar["`prefix'`var2'","`prefix'`var2'"]

local s11=s11[1,1]
local s12=s12[1,1]
local s22=s22[1,1]

qui su `var1'
if `minimum'==-.12345 {
  local x_min=r(min)
  }
  else {
    local x_min=`minimum'
  }

if `maximum'==.12345 {
  local x_max=r(max)
  }
  else {
    local x_max=`maximum'
  }

The code is not completed, but I used only the part that I need to explain my question.

The first line

syntax varlist(min=2 max=2 numeric) [, MInimum(real -.12345) MAximum(real .12345) Quadratic Inverse Fieller Level(cilevel) PREfix(string)]

is almost clear. My doubt is about the options minimum and maximum. Which is the meaning of the number 0.12345? Is this just a conventional number? I am asking this because later on I read:

if `minimum'==-.12345 {
  local x_min=r(min)
  }
  else {
    local x_min=`minimum'
  }

if `maximum'==.12345 {
  local x_max=r(max)
  }
  else {
    local x_max=`maximum'
  }

where `var1' is just the first variable in the varlist. Now this part of the code tells me that the if `minimum'=-.12345 then the local x_min will be equal to r(min). Otherwise x_min=`minimum', which is the value specified in the option "minimum". Now the default of the test implemented by utest is to set x_min=r(min). So, eventually it is totally unclear to me why minimum/maximum come out with (real 0.12345). Is there any esplanation that can help me to understand?

Thanks in advance and I apologize if my question is not entirely clear

[Jean-Claude Arbaut]

It's a default value in case the user does not add the option when calling -utest-.

Either you write "MInimum(real)" and the option is required, or you write "MInimum(real -.12345)" with a default value. The default value may be any other number. I guess this one was chosen because it's assumed it will never happen. Note that the default value can't be a missing.

With a numlist option the "default" is an empty macro, which seems less error-prone. Here it would be written "MInimum(numlist max=1)".

In this command, when the option is missing, the macro has the value -.12345, and the program then sets the value of x_min to the minimum found in the data (r(min) is computed by -su- here).

See also the documentation of -syntax-: https://www.stata.com/help.cgi?synta...nal_real_value

[Clyde Schechter]

The syntax specifies that the options minimum and maximum are optional. (They appear inside of straight brackets [].) So the 0.12345 is just a placeholder value for Stata to fill in if either or both are not specified in the calling command. Then at the later point in the code, Stata just recognizes that 0.12345 as being a proxy for "unspecified" and therefore uses the minimum and maximum values of `var1' instead.

It's generally not a good idea to use "magic numbers" like this. Suppose somebody actually wanted 0.12345 to be the actual minimum or maximum: unless that also happened to be the max or min of `var1' the program would give incorrect output. Unfortunately, the -syntax- command does not accept Stata's missing values as the defaults for unspecified numeric options, so programmers are forced into this practice in this circumstance. Even so, I think it is better to pick a magic number that is almost guaranteed never to be the actual value somebody has in mind. For example, `c(maxdouble)' or something like that. (Actually, for options describing a maximum and minimum, as here, the use of `c(mindouble)' for the default maximum and `c(maxdouble)' for the default minimum would be optimal because it would be an error for the user to intentionally specify those values anyway.

Added: Crossed with #2.

[Dario Maimone Ansaldo Patti]

Thanks Clyde Schechter and Jean-Claude Arbaut. The point raised by Clyde is quite right and interesting, since the max or min could occur at that value. It might be too risky to use that value. Anyway, thanks again for your prompt help.