Skip to main content

programming - Is using undocumented functionality a Bad Idea™?


Mathematica has a lot of very useful undocumented features. For example a hash table, a built-in list of compilable functions, additional options to CurrentValue, {"Raw", n} histogram bin specification, etc...


A natural question that arises is: Why is this functionality undocumented? Is it because the feature is under development? Or because the syntax has not been finalized and may be changed? Something else?


Also: Is using this functionality safe in the sense that it will not cause problems when a new version is released?



Answer



The two main arguments against using undocumented functions are:




  1. Your code might not work as expected in future versions;

  2. Your code might not work as you intended in the current version, because you only have a partial understanding of a function or option that is undocumented.


In the case of Mathematica, though, there is no guarantee that even documented functions will remain unchanged in future versions.



The two main arguments for using undocumented functions are:



  1. Oftentimes they presage the permanent inclusion of that functionality in a future version. For example, ScalingFunctions is only documented for charting functions like BarChart, but it has been shown to work also for ListPlot and Plot (but not DateListPlot). I predict that they will get around to completing (and documenting) this functionality in a future version. (EDIT: In fact, that's exactly what happened in 10.4, even though the online version of the documentation doesn't make it clear that this is new.)

  2. The functionality might be documented, but not completely documented. For example, some option values (say PlotRegion) are documented as applying to "graphics functions", without specifying which ones. So the functionality is there, and might well remain stable for several versions.



Mathematica is a complex system with an enormous array of possibilities for the use and abuse of its rich functionality. Even with the massive documentation that exists, there are bound to be some undocumented or incompletely documented functions. Undocumented functions (and options) need to used with some care, but given the usefulness of some of the functionality they offer, it might well be worth the risk.


Comments

Post a Comment

Popular posts from this blog

plotting - How to draw lines between specified dots on ListPlot?

I would like to create a plot where I have unconnected dots and some connected. So far, I have figured out how to draw the dots. My code is the following: ListPlot[{{1, 1}, {2, 2}, {3, 3}, {4, 4}, {1, 4}, {2, 5}, {3, 6}, {4, 7}, {1, 7}, {2, 8}, {3, 9}, {4, 10}, {1, 10}, {2, 11}, {3, 12}, {4,13}, {2.5, 7}}, Ticks -> {{1, 2, 3, 4}, None}, AxesStyle -> Thin, TicksStyle -> Directive[Black, Bold, 12], Mesh -> Full] I have thought using ListLinePlot command, but I don't know how to specify to the command to draw only selected lines between the dots. Do have any suggestions/hints on how to do that? Thank you. Answer One possibility would be to use Epilog with Line : ListPlot[ {{1, 1}, {2, 2}, {3, 3}, {4, 4}, {1, 4}, {2, 5}, {3, 6}, {4, 7}, {1, 7}, {2, 8}, {3, 9}, {4, 10}, {1, 10}, {2, 11}, {3, 12}, {4, 13}, {2.5, 7}}, Ticks -> {{1, 2, 3, 4}, None}, AxesStyle -> Thin, TicksStyle -> Directive[Black, Bold, 12], Mesh -> Full, Epilog -> { Line[ ...
Post a Comment
Read more

dynamic - How can I make a clickable ArrayPlot that returns input?

I would like to create a dynamic ArrayPlot so that the rectangles, when clicked, provide the input. Can I use ArrayPlot for this? Or is there something else I should have to use? Answer ArrayPlot is much more than just a simple array like Grid : it represents a ranged 2D dataset, and its visualization can be finetuned by options like DataReversed and DataRange . These features make it quite complicated to reproduce the same layout and order with Grid . Here I offer AnnotatedArrayPlot which comes in handy when your dataset is more than just a flat 2D array. The dynamic interface allows highlighting individual cells and possibly interacting with them. AnnotatedArrayPlot works the same way as ArrayPlot and accepts the same options plus Enabled , HighlightCoordinates , HighlightStyle and HighlightElementFunction . data = {{Missing["HasSomeMoreData"], GrayLevel[ 1], {RGBColor[0, 1, 1], RGBColor[0, 0, 1], GrayLevel[1]}, RGBColor[0, 1, 0]}, {GrayLevel[0], GrayLevel...
Post a Comment
Read more

Is there a way to do conditional matrix loop using 'continue'

I have the following: n = 3; m = 5; ww = RandomReal[{0, 0.1}, {n, n}]; uu = RandomReal[{0, 1}, {m, n}]; pp = RandomReal[{0, 1}, {n, n}]; ss = RandomInteger[{0, 5}, {m, n}]; Grid[{{"ww", "uu", "pp", "ss"}, {ww // TableForm, uu // TableForm, pp // TableForm, ss // TableForm}}, Spacings -> {5, 2}, Dividers -> All] where I would like to look at every element of matrix ss and produce a matrix tt , with zeroes at the locations in ss which have zeroes, and in all other positions do the following: tt = (-1/Subscript[ww, m]) Log[(1 - uu)/(Subscript[pp, m - 1])], where Subscript[ww, m] is the value at index of ww matrix and where Subscript[pp, m - 1] is the value at index-1 of pp matrix. So for example if the first value ever read from matrix ss happens to be 2, then value taken from matrix ww would be from the row 2, but from pp would be from row 1. Also how to tell difference between a 0 as a valid value from within the matrix elemen...
Post a Comment
Read more