The package FilterOptions

Bernd Thaller
Institute for Mathematics
University of Graz

Source: Roman Maeder, Programming in Mathematica
Second Edition, Addison-Wesley 1991 (Third Edition, Addison-Wesley, 1996)

Mathematica Standard Packages

Listing

It is the main purpose of FilterOptions to choose from a given sequence of options a sub sequence fitting to a given Mathematica command. The package FilterOptions.m is one of Mathematica'a standard packages. The code by Roman Maeder is as follows.

BeginPackage["Utilities`FilterOptions`"]

FilterOptions::usage = "FilterOptions[symbol, options..] returns a sequence
	of those options that are valid options for symbol.
	FilterOptions[{opts..}, options..] filters out options with names opts."

Begin["`Private`"]

FilterOptions[ command_Symbol, options___ ] :=
	FilterOptions[ First /@ Options[command], options ]

FilterOptions[ opts_List, options___ ] :=
	Sequence @@ Select[ Flatten[{options}], MemberQ[opts, First[#]]& ]

End[ ]

Protect[ FilterOptions ]

EndPackage[ ]

The Mathematica command "Sequence"

Let us analyze what this package does. In Mathematica, options are usually given as a list of rules. Consider, for example,

Plot[Sin[x],{x,-Pi,Pi},Axes->{True,False}, Frame->True, PlotLabel->"Sine-Function"]

As an experienced Mathematica user you will notice that the options Axes->{True,False}, Frame->True, PlotLabel->"Sine-Function" are not really given as a list. The braces {} are missing. A list with missing braces is called a "Sequence" in Mathematica. Sequence is Mathematica's representation for the set of arguments of a function taking several arguments. The difference to List can be seen from the following example

A = Sequence[x,y,z]; B = List[x,y,z];

{a,A,b}

{a,B,b}

Analysis of the command FilterOptions

The command

FilterOptions[ opts_List, options___ ] :=
	Sequence @@ Select[ Flatten[{options}], MemberQ[opts, First[#]]& ]

takes a list of option names as the first argument. For example,

optionnames = {AspectRatio, Frame, PlotLabel, PrecisionGoal};

The pattern options___ matches zero or more arguments. Options are usually a sequence of rules. In our example,

optionsequence = Sequence[Axes->{True,False}, Frame->True, PlotLabel->"Sine-Function", AccuracyGoal->10]

FilterOptions[ optionnames,optionsequence ]

It returns just those options of the sequence, whose names are contained in the given list opts. How is this achieved? Consider first the command

Select[ {options}, MemberQ[optionnames, First[#]]& ]

{options} creates a list from the given sequence "options" by adding the braces. The command Select[list,test] picks out those elements from the list, for which test gives "True". Here the test is MemberQ[opts, First[#]]&. It is applied to each element of the list {options}. If it gives "True", that element is kept, otherwise it is deleted. Thus the second argument of Select must be a function that can be applied to each element of the list and evaluates either to True or to False. Let us consider an example

options = Sequence @@ Options[Plot]

(Here the operator @@ ("Apply") replaces the head List by the head Sequence).

Now we map (/@) the test-function to the list "{options}". (The command Map or /@ applies the function to each element in the list).

MemberQ[optionnames, First[#]]& /@ {options}

Select keeps only those elements of the list {options} for which this test gives True:

Select[{options}, MemberQ[optionnames, First[#]]&]

This is the filtered list of options. We finally apply Sequence in order to return a sequence of options suitable for input to Mathematica commands.

Sequence @@ Select[{options}, MemberQ[optionnames, First[#]]&]

Flattening the list {options} is done in case that the second argument "options" of FilterOptions is already given as a list. In that case {options} would be an expression of the form {{optionsequence}}. Flatten deletes the inner braces of the list.

Next, consider the command

FilterOptions[ command_Symbol, options___ ] :=
	FilterOptions[ First /@ Options[command], options ]

It just calles FilterOptions with the fist command being a list of option names. For example,

command = NIntegrate

Options[command]

First /@ Options[command]

Now, let us try this:

optionsequence

FilterOptions[NIntegrate, optionsequence]

Examples

Prevent shadowing:

Remove [FilterOptions]

Load the package:

<<Utilities`FilterOptions`

FilterOptions[Graphics,Options[Plot3D]]

options = Join[Options[Simplify], Options[Integrate], Options[Plot]]

FilterOptions[Integrate,options]