Advanced Topic: Basing New Packages on the Standard Mathematica Packages
There is a standard sequence of Mathematica commands that is typically used to set up the contexts in a package. These commands set the values of $Context and $ContextPath so that the new symbols which are introduced are created in the appropriate contexts.
The standard sequence of context control commands in a package.
When you write a package that uses symbols provided by one of the standard packages, you need to be aware of auxiliary packages automatically loaded via a multiargument BeginPackage. A few directories have a Common subdirectory for auxiliary packages containing shared symbols. For example, the package Statistics`ConfidenceIntervals` automatically loads Statistics`Common`PopulationsCommon` using the BeginPackage function.
Specifying interdependence of packages using BeginPackage.
$ContextPath is a global variable that gives a list of contexts to search in trying to find a symbol.
In[1]:= $ContextPath
Out[1]=
This loads the standard package Statistics`ConfidenceIntervals`.
In[2]:= <<Statistics`ConfidenceIntervals`
The context for the auxiliary package PopulationsCommon was automatically added to $ContextPath when the package ConfidenceIntervals was loaded.
In[3]:= $ContextPath
Out[3]=
You can request all symbols from the Statistics`Common`PopulationsCommon` context.
In[4]:= Names["Statistics`Common`PopulationsCommon`*"]
Out[4]=
You can determine the context of a particular symbol by applying the Context function or by locating the symbol in the index of this book.
In[5]:= {Context[MeanCI], Context[KnownVariance]}
Out[5]=
Here is the confidence interval for the mean of the data set {1., 0., 1.}, where the default option setting KnownVariance > None specifies that the population variance is to be estimated from the data.
In[6]:= MeanCI[{1., 0., 1.}]
Out[6]=
Here is the confidence interval for the mean of the data when the population variance is known to be , a machineprecision number. Both symbols MeanCI and KnownVariance are recognized because their contexts are on $ContextPath.
In[7]:= MeanCI[{1., 0., 1.}, KnownVariance > 1.]
Out[7]=
When loading a standard package into a session, there is no need to be concerned about the existence of an auxiliary package, or the specific contexts of the symbols introduced by the load. However, if you would like to use BeginPackage to base a package of your own on symbols from a standard package, then the contexts of the symbols are important. Consider the example packages myPackage1.m and myPackage2.m.
BeginPackage["myPackage1`", "Statistics`ConfidenceIntervals`"]
myMeanCI::usage = "myMeanCI[list] gives my value for MeanCI."
Begin["`Private`"]
myMeanCI[list_] := MeanCI[list, KnownVariance > 1.]
End[ ]
EndPackage[ ]
The sample package myPackage1.m.
In the first example package myPackage1.m, the BeginPackage statement calls Needs on the standard package ConfidenceIntervals. The function myMeanCI is defined in terms of the package symbols MeanCI and KnownVariance. You probably won't want to create a package solely for the sake of hardwiring an option value for a function, but this example illustrates the general situation of using symbols defined in other packages in your own package definitions.
This loads the package.
In[1]:= <<myPackage1`
This applies the package function myMeanCI to the data set.
In[2]:= myMeanCI[{1., 0., 1.}]
Out[2]=
Unfortunately, since the auxiliary package was not specified in BeginPackage, the symbol KnownVariance in the definition for myMeanCI has context myPackage1`Private` rather than context Statistics`Common`PopulationsCommon`. The context myPackage1`Private` is not on $ContextPath after the package is loaded, so the option setting myPackage1`Private`KnownVariance > 1. is not recognized and the default KnownVariance > None is used. Rather than the interval obtained using the option setting KnownVariance > 1., myMeanCI gives the same confidence interval as the default MeanCI.
This example shows that when you want to use symbols from the standard packages in your own package, you should determine the specific context for each symbol you need, and include those contexts in the BeginPackage statement of your package. The second example package does just that.
BeginPackage["myPackage2`", "Statistics`ConfidenceIntervals`",
"Statistics`Common`PopulationsCommon`"]
myMeanCI::usage = "myMeanCI[list] gives my value for MeanCI."
Begin["`Private`"]
myMeanCI[list_] := MeanCI[list, KnownVariance > 1.]
End[ ]
EndPackage[ ]
The sample package myPackage2.m.
In the second example package myPackage2.m, the BeginPackage statement calls Needs on both the ConfidenceIntervals package and the auxiliary package PopulationsCommon. This is necessary for Mathematica to correctly interpret all the standard package symbols used in the myPackage2.m.
This loads the package.
In[1]:= <<myPackage2`
Now myMeanCI implements KnownVariance > 1. as desired.
In[2]:= myMeanCI[{1., 0., 1.}]
Out[2]=
Auxiliary packages are usually employed to allow two or more packages to share symbols without shadowing. Symbol shadowing can be useful when it warns you that two symbols with the same name, but different purposes, occur in your session. However, in the case of standard packages from a single subdirectory (such as Statistics), the packages are meant to work together and shadowing is undesirable.
In this book, symbols introduced by an auxiliary package are documented both with the standard packages that load the auxiliary package and in a separate section devoted to the auxiliary package.
