How to specify and use nested options for a function?

Question

I want to write a function that takes options that are nested. For example, suppose the function has one main option, "method" which can take two values, "a" and "b". Also, when method is "a", it can take one sub-option, "depth", whereas, when the method is "b", the sub-option that can be specified is "totTime".

Basically, the options and suboptions that make sense are

method->"a", depth->5 or method->"b", totTime->10

One should not, for example, use the combination method->"a", and totTime->10.

One way to deal with this is

In[53]:= Options[f] = {method -> "a", depth -> 5, totTime -> 10}

Out[53]= {method -> "a", depth -> 5, totTime -> 10}

f[x_, OptionsPattern[]] :=
 Module[
  {},
  If[OptionValue[method] == "a", {x, OptionValue[method], 
    OptionValue[depth]}, 
   {x, OptionValue[method], OptionValue[totTime]}
   ]
  ]

We get proper output, despite "wrong" input

In[59]:= f[2, method -> "b", depth -> 6]

Out[59]= {2, "b", 10}

In[60]:= f[2, method -> "a", totTime -> 2]

Out[60]= {2, "a", 5}

However, the above set of options that the user specifies in the input to the function do not make sense as the sub-option, depth is not related to method "b". How can one make sure that the user does not enter nonsensical combinations of options and sub-options, without relying solely on the documentation.

I am looking for a method that works even if there are a ton of options and sub-options. That is, Ideally, I do not want to write a huge number of warnings saying that different combinations do not make sense. Someway to nudge the user toward proper input (e.g., sublists) would be useful.

Answer 1

You can do this by moving method from an option to a parameter and explicitly listing the options in OptionsPattern. With this approach Options is not used.

ClearAll[f]

f[x_, method : "a", OptionsPattern[{depth -> 5}]] := 
 {x, method, OptionValue[depth]}

f[x_, method : "b", OptionsPattern[{totTime -> 10}]] := 
 {x, method, OptionValue[totTime]}

This creates two definitions on the symbol f that will match to the named method pattern in the parameter list. You can add additional options to OptionsPattern.

f[2, "a", depth -> 2]
(* {2, "a", 2} *)

f[2, "a", totTime -> 2]
OptionValue::nodef: Unknown option totTime for {depth->5}. >>
(* {2, "a", 5} *)

f[2, "b", totTime -> 2]
(* {2, "b", 2} *)

f[2, "b", depth -> 2]
OptionValue::nodef: Unknown option depth for {totTime->10}. >>
(* {2, "b", 10} *)

An error is thrown when an incorrect option is supplied for a particular method. However, f still returns a result in these cases. I'm not certain on how to get the function to abort when there is an error in its OptionsPattern match.* In any case the error will prompt the user to look at the parameters.

If there is a lot of shared code between the two methods then I would suggest a private function to hold this code that both versions of f can call separate from the option specific bits.

Hope this helps.

---

* That can be done, a bit baroquely, like this:

ClearAll[f]

f[x_, method : "a", OptionsPattern[{depth -> 5}]] :=
 With[{body =
   Check[
     {x, method, OptionValue[depth]},
     $Failed,
         OptionValue::nodef
       ]
      }, body /; body =!= $Failed
 ]

f[x_, method : "b", OptionsPattern[{totTime -> 10}]] :=
 With[{body =
   Check[
     {x, method, OptionValue[totTime]},
     $Failed,
         OptionValue::nodef
       ]
      }, body /; body =!= $Failed
 ]

Or more cleanly using the undocumented functionality of Fail and RuleCondition:

ClearAll[f]

f[x_, method : "a", OptionsPattern[{depth -> 5}]] :=
 Check[
   {x, method, OptionValue[depth]},
   Fail,
   OptionValue::nodef
 ] // RuleCondition


f[x_, method : "b", OptionsPattern[{totTime -> 10}]] :=
 Check[
   {x, method, OptionValue[totTime]},
   Fail,
   OptionValue::nodef
 ] // RuleCondition

Test:

f[2, "b", depth -> 2]

OptionValue::nodef: Unknown option depth for {totTime->10}. >>

f[2, "b", depth -> 2]

Answer 2

Many built-in functions use a Method option, and suboptions are given within that option, nested, rather than flat as in your examples. The value of Method is extracted and processed, e.g. with Charting`ConstructMethod and Charting`parseMethod, then used as needed. I suggest that you do something similar. Simplistically:

Options[f] = {method -> {"a", depth -> 5}};

f[x_, OptionsPattern[]] :=
 Module[{mv = OptionValue[method]},
  Check[
   Switch[First @ mv,
    "a", OptionValue[Rest @ mv, depth],
    "b", OptionValue[Rest @ mv, totTime]
   ],
   $Failed,
   OptionValue::optnf
  ]
 ]

Now:

f[2, method -> {"a", depth -> 6}]
f[2, method -> {"b", totTime -> 2}]

6

2

f[2, method -> {"b", depth -> 6}]
f[2, method -> {"a", totTime -> 2}]

OptionValue::optnf: Option name totTime not found in defaults for {depth->6}. >>

$Failed

OptionValue::optnf: Option name depth not found in defaults for {totTime->2}. >>

$Failed

This still does not warn when superfluous options are given:

f[2, method -> {"a", depth -> 6, totTime -> 2}]

6

If that is needed various checks could be made. In this case since only one sub-option is expected I would merely check if there are two or more. In a more complicated case I would keep a list of valid sub-options for each method, then use FilterRules to extract only these, then check to see if the length of those extracted rules matches the length of the input list.