167
$\begingroup$

Mathematica has a lot of undocumented or poorly documented options.

  1. How does one go about working out if there is an undocumented option that might solve a particular problem?
  2. How does one work out what the universe of possible values the option might take are? (This also applies to options whose existence is documented, but where the range of valid values isn't.)

As background, here is a collection of ones I and others have found so far:

Graphics

The Method option is an option for Graphics and related commands like BarChart. It is mentioned in the notes in the documentation and turns up in Options[Graphics] but is not listed as an option in the documentation with any examples. There are many sub-options, none of which are explicitly documented.

  • Method -> {"ShrinkWrap" -> True} removes whitespace that Mathematica adds as a tiny rim to each plot. (pointed out by Sjoerd)

  • Method -> {"GridLinesInFront" -> True} does what it says (see Brett Champion's answer to this question and this MathGroup thread). Dynamic GridLines using this option are present in much of the graphical Wolfram|Alpha output (See, e.g. the edited number line code).

  • Method -> {"AxesInFront" -> True} also does what it says. (see TomD's comment on Brett's answer)

  • Method -> {Refinement -> {ControlValue -> angle}} sets the angle that decides when two points in a plot are not further subdivided - default is 5\[Degree]. (see Yaro's answer here and the relevant page in Stan Wagon's book. Also, a Plot version comparison by Alexey)

  • The option "MessagesHead" is used to track the origin of calls to Plot, etc., made by dependent plot functions such as LogPlot, LogLinearPlot, and DateListLogPlot. This allows the correct options and messages to be passed to and from the general function. An example of its use can be seen in this question.

  • ImageSizeRaw option for various plotting and graphics functions is not documented, but turns out to be important for embedding CDFs into web pages.

  • PrivateFontOptions -> {"OperatorSubstitution" -> False}, as documented here, stops minus signs, parentheses and the like from being in Mathematica's special fonts rather than the selected text font.

  • s0rce discovered that the ScalingFunctions option works for line plots (ListPlot, Plot, etc). Possible values include "Reverse", "Log" "Log10" – the last of these being itself undocumented.

  • Not strictly a graphics function, but often used to create nice-looking ticks, FindDivisions has an undocumented Method option: for example, FindDivisions[{-1.8,8.9}, 6, Method -> "ExtendRange"] gives the encompassing divisions {-2, 0, 2, 4, 6, 8, 10}, as does Method -> Automatic; any other setting for Method gives the inner divisions: {0, 2, 4, 6, 8}.

  • You can control the amount a PieChart segment pops out of the chart when you click it using SetOptions[Charting'iSectorChart, {PopoutSpacing -> n}], where n is numeric. The default is 0.2; for fun, try a negative number. You can suppress this behaviour altogether using SetOptions[Charting'SectorChart, {Popout -> False}] (in both these examples, change the quote mark to a backquote).

  • For some Plot functions the setting for the PlotStyle option can be specified as a function as well as a list of graphics directives. The earliest reference for this undocumented feature is this answer by Simon Woods. Additional examples of this PlotStyle usage for Plot and ParametricPlot are: this, this, this, and this.

Panels

As noted in an earlier question, these options pop up in some graphics/panels, but are unrecognised when one uses them explicitly in Panel, Graphics or related structures:

  • LineColor
  • FrontFaceColor
  • BackFaceColor
  • GraphicsColor

Legends

There seem to be a lot of undocumented options here:

  • AssembleLegendContainer
  • BubbleScaleLegend
  • ColorGradientLegend
  • ContourLegend
  • CurveLegend
  • GridLegend
  • Legend
  • LegendContainer: SetOptions[Legending`GridLegend, Legending`LegendContainer -> Identity] removes the border from legends (thanks to Mr.Wizard)
  • LegendHeading
  • LegendImage
  • LegendItemLayout
  • LegendLayout
  • LegendPane
  • LegendPosition
  • LegendReap
  • Legends
  • LegendSize
  • LegendSow

Equation-solving and minimisation/optimisation

  • Evaluated -> False option of FindRoot (TomD in comments)

System options for evaluation

Per acl's answer below, SystemOptions[] reveals many hidden options using the following syntax. These can be set using SetSystemOptions[].

  • "PackedArrayOptions" /. SystemOptions[]
  • "CompileOptions" /. SystemOptions[]

Although this book by Nancy Blachman has been written for Version 2, it is still not a bad starting point: http://www.amazon.com/Mathematica-Quick-Reference-Version-Spiral/dp/0201628805

$\endgroup$
6
  • 5
    $\begingroup$ One that perhaps deserves mention is the Evaluated-> False option of FindRoot, known to me from a MathGroup discussion by Andrzej Kozlowski & szhorvat. See here. They consider the example FindRoot[NIntegrate[Exp[a x], {x, 0, 1}] == 2, {a, 1}, Evaluated -> False] $\endgroup$
    – user1066
    Aug 18, 2011 at 19:39
  • $\begingroup$ I see that I lost the Accept. I think that Simon Woods' method is valuable, but how would you use it to find something like Legending`LegendContainer or "MessagesHead"? I argue that Trace is still more powerful and applicable. $\endgroup$
    – Mr.Wizard
    May 19, 2012 at 7:38
  • 2
    $\begingroup$ @Mr.Wizard both would be fine answers but I thought Simon's was more straightforward for bulk investigation, and I can't mark multiple answers as accepted. Don't worry there will be some goodies along later. $\endgroup$
    – Verbeia
    May 20, 2012 at 7:51
  • $\begingroup$ @Verbeia I have asked Brett Chamption and received information that there is also "FrameInFront" option. comments to this Q&A. Not that useful as AxesInFront but you may want to add this to that list :) $\endgroup$
    – Kuba
    Sep 13, 2013 at 19:09
  • $\begingroup$ ScalingFunctions seem to stop working with ListPlot. $\endgroup$
    – Kuba
    Dec 19, 2013 at 8:20

6 Answers 6

66
$\begingroup$

One thing you can do is look for options which appear in a function's Options but do not have a ::usage message. Of course, some of the results actually are documented in the help, they just don't have a usage message. Here's a function to do it:

undoc[x_Symbol]:=Select[Options[x],!StringQ@MessageName[Evaluate@First@#,"usage"]&];
undoc[_] = {};

(* e.g. *)
undoc[Plot]
Out[3]= {Evaluated->Automatic,ImageSizeRaw->Automatic}

The following runs this function on all symbols in System context, and presents the results in a grid. Some functions (like Cell) have huge lists of options with no usage message, these ones I skip over (just printing out the function name) to save space.

Grid[Select[{#,undoc[Symbol[#]]}&/@Names["System`*"],
Last@#=!={}&&(Length@Last@#<10||Print@First@#)&],Frame->All]

enter image description here

$\endgroup$
40
$\begingroup$

1. Discovery may be aided by Trace and related tools.

2. Simple observation and experimentation. Simple does not imply easy.


As an example, to find the answer to "Can the frame border on a BarChart Legend be removed?", I used:

BarChart[{{1, 2, 3}}, ChartLegends -> {"A", "B", "C"}] // Trace // InputForm

InputForm was used so that details of Graphics objects could be viewed and searched as text.

In the long output that was produced, I first searched to see when Framed appeared, and then I began working backward to see what precipitated it. After some digging, backtracking, and a few dead ends I came across:

{Legending`LegendDump`container, Legending`LegendDump`position, 
  Legending`LegendDump`layout, Legending`LegendDump`appearance} = 
 OptionValue[
  Legending`GridLegend, {LegendAppearance -> Automatic, 
   Legending`LegendPosition -> 
    Automatic}, {Legending`LegendContainer, Legending`LegendPosition, 
   Legending`LegendLayout, LegendAppearance}]

I had observed or guessed, from my digging, that Legending`LegendDump`container related to the Framed component, and here was (one place) where its value was set. Experimentation proved that this option affected the desired object, at least in some cases:

SetOptions[Legending`GridLegend, Legending`LegendContainer -> "Nonsense"]

BarChart[{{1, 2, 3}}, ChartLegends -> {"A", "B", "C"}]

Seeing how this behaved, it was obvious to try Identity. Testing with several bar charts suggested that it was at least somewhat durable, therefore I posted it as an answer.

$\endgroup$
3
  • 1
    $\begingroup$ This is an interesting trick; can you give a short example of how one can find an undocumented option using Trace? I have found the ones I use either by being told by others or by looking at things like SystemOptions. $\endgroup$
    – acl
    Aug 17, 2011 at 2:36
  • $\begingroup$ In the edited version of the question, these responses relate to points (1) and (2). Sorry about that. $\endgroup$
    – Verbeia
    Aug 17, 2011 at 3:56
  • $\begingroup$ That is a useful observation. I had never noticed this kind of thing in the mass of Trace output. $\endgroup$
    – acl
    Aug 17, 2011 at 10:59
25
$\begingroup$

I find SetSystemOptions["PackedArrayOptions" -> {"UnpackMessage" -> True}] to be useful: it emits a message when a packed array is unpacked. This may happen automatically, sometimes slowing down things greatly. This is useful in situations like this or this. One way one would find out that such an option exists is "PackedArrayOptions" /. SystemOptions[].

In fact, SetSystemOptions[] shows up a number of interesting and undocumented options. For instance, "CompileOptions" /. SystemOptions[] gives a set of options for when things get compiled, whether or not to generate reports when something can't be compiled or parts of it call external definitions, whether to inline compiled functions called from within a compiled function, etc.

$\endgroup$
23
$\begingroup$

John Fultz posted an answer which had an undocumented option.

CellPrint[{
  Cell["Click to open the section", "Section", 
       System`WholeCellGroupOpener -> True],
  TextCell["Some text"]}]

This produces a section cell that if you click anywhere on it will open and close the whole section.

$\endgroup$
4
  • $\begingroup$ This is interesting, but I think you got the wrong question. Shouldn't it be here?: stackoverflow.com/questions/8461814/… $\endgroup$
    – Mr.Wizard
    Dec 14, 2011 at 6:56
  • $\begingroup$ @Mr.Wizard: Maybe, maybe not... This question is about undocumented options (it has been rephrased to make it into a question that wouldn't be closed - see the revisions), my question was about undocumented functions. Maybe we should revert the title to make it once again into one of the dreaded Big List questions. $\endgroup$
    – Simon
    Dec 14, 2011 at 7:18
  • 1
    $\begingroup$ This question is how to find undocumented options. Unless your answer can be distilled to "look for posts by John Fultz" then I do not believe it is valid. I would rather you edit the other post title to "undocumented Mathematica functionality" and post this there. $\endgroup$
    – Mr.Wizard
    Dec 14, 2011 at 7:50
  • $\begingroup$ @Mr.Wizard: I know what the question currently says - I was answering its original phrasing and intent. I wrote my question to complement this one - assuming that Verbia still had her original intent. I'm happy to move this answer and modify my question if other people think that is appropriate. $\endgroup$
    – Simon
    Dec 14, 2011 at 7:58
16
$\begingroup$

NIntegrate Method options

There are many Method settings to use in NIntegrate and many but not all of their suboptions are documented the tutorial on NIntegrate. Some of these may be found by

?NIntegrate`StrategiesDump`*Options

Mathematica graphics

Others may be found by

?NIntegrate`StrategiesDump`*Properties

Mathematica graphics

Note in the case shown, the options are the same as the Method options of PiecewiseExpand and

SystemOptions["PiecewiseOptions"]

(* {"PiecewiseOptions" -> {"BooleanResult" -> Automatic, 
     "ConditionSimplifier" -> Automatic, 
     "DirectExpansionCrossovers" -> {10, 7., False}, 
     "EliminateConditions" -> True, "ExpandSpecialPiecewise" -> True, 
     "FactorInequalities" -> True, "FullStrengthInference" -> False, 
     "OrderlessConditions" -> Automatic, "Parallel" -> Automatic, 
     "RefineConditions" -> True, "Simplification" -> True, 
     "StrictCalculus" -> Automatic, "ValueSimplifier" -> Automatic}} *)

Note also that giving a wrong option to NIntegrate methods yields the list of properties as an error message:

NIntegrate[x, {x, 0, 1}, Method -> {"InterpolationPointsSubdivision", "Foo" -> True}]

NIntegrate::moptxn: The option Foo of the method InterpolationPointsSubdivision is not one of {MaxSubregions, Method, SymbolicProcessing}. >>

$\endgroup$
6
$\begingroup$

Possibly the following file contains more options, though admittedly I have not spent much time looking for them. This is the file that contains the information used by SyntaxInformation

ToFileName[{$InstallationDirectory, "SystemFiles", "Kernel", 
      "TextResources", $Language}, "FunctionInformation.m"]

This file contains a lot of options, both "Symbol options" and "string options". Not all "kinds of options" are listed here, at least the "option" "OptionNames" of SyntaxInformation is not present here. The file also does not appear to contain nested options.

$\endgroup$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.