Bind Labels - Maple Help

Online Help

All Products    Maple    MapleSim

DataFrame/with

simplify syntax for referring to DataFrame columns

DataFrame/unwith

remove DataFrame columns from global namespace

 Calling Sequence with(DF) unwith(DF)

Parameters

 DF - a DataFrame object

Description

 • The with command, applied to a DataFrame object, makes columns of the DataFrame available as variables at the interactive level.
 • The unwith command undoes the effects of prior calls to with.
 • The with command is effective only at the top level, and intended primarily for interactive use.  Because with operates by using lexical scoping, it does not work inside the bodies of procedures, module definitions, or within statements.  See the Examples section below.
 • DataFrames are collections of named columns of data called DataSeries. They are explained in more detail on the DataFrame help page.
 • Only column labels that are symbols can be used as variables. Columns with labels that are not symbols (for example, indexed names or other algebraic expressions) are ignored by with.
 • When with is called with a DataFrame as its argument, it binds the column names of the DataFrame to the global namespace.  This makes the column names available to the interactive user at the top level of the Maple interaction loop.
 • The unwith command undoes the effects of prior calls to with. That is, when it is called with as its argument a DataFrame that was previously submitted to with, unwith unbinds the column names in the global namespace, any previous bindings of those names are restored.
 • The restart command clears the Maple internal memory, clearing any bindings made by with.
 • The with command is also used for making the exports of a package accessible in the global namespace. This use is explained on the with help page. This is different from using the command on a DataFrame object in several ways: the exports of a package are (typically) procedures, whereas the columns in a DataFrame for example, are not.

Examples

If you have defined a DataFrame df which has a column a, then to access that column (a DataSeries object), you must enter df[a].

 > $\mathrm{df}≔\mathrm{DataFrame}\left(⟨⟨1|2⟩,⟨3|4⟩⟩,\mathrm{columns}=\left[a,b\right]\right)$
 ${\mathrm{df}}{≔}\left[\begin{array}{ccc}{}& {a}& {b}\\ {1}& {1}& {2}\\ {2}& {3}& {4}\end{array}\right]$ (1)
 > $\mathrm{df2}≔\mathrm{DataFrame}\left(⟨⟨5|6⟩,⟨7|8⟩⟩,\mathrm{columns}=\left[a,c\right]\right)$
 ${\mathrm{df2}}{≔}\left[\begin{array}{ccc}{}& {a}& {c}\\ {1}& {5}& {6}\\ {2}& {7}& {8}\end{array}\right]$ (2)
 > $\mathrm{df}\left[a\right]$
 $\left[\begin{array}{cc}{1}& {1}\\ {2}& {3}\end{array}\right]$ (3)
 > $a$
 ${a}$ (4)

However, after using the with(df) command, you can use the column name a directly, without specifying the DataFrame to which the column belongs.

 > $\mathrm{with}\left(\mathrm{df}\right)$
 $\left[{a}{,}{b}\right]$ (5)
 > $a$
 $\left[\begin{array}{cc}{1}& {1}\\ {2}& {3}\end{array}\right]$ (6)
 > $\mathrm{unwith}\left(\mathrm{df}\right)$
 > $a$
 ${a}$ (7)

As illustrated in the previous example, a list of the column names bound to the top level is returned by with.

Sometimes a column name is identical to a top level name with a global meaning. Global names are still fully accessible.  To access the global name a after having bound a DataFrame that has a column named a, use the prefix form of the $:-$ operator, as in  $:-a$ .

For example, the variable a may be in use.

 > $a≔12.3$
 ${a}{≔}{12.3}$ (8)

After issuing a call to with(df), in which the name a occurs as a column label, the name a now refers to a column of data. The original variable is still available by using the syntax :-a.

 > $\mathrm{with}\left(\mathrm{df}\right)$
 $\left[{a}{,}{b}\right]$ (9)
 > $a$
 $\left[\begin{array}{cc}{1}& {1}\\ {2}& {3}\end{array}\right]$ (10)
 > $:-a$
 ${12.3}$ (11)

In addition, two or more DataFrames may have columns with some of the same names. In this case, if both are bound using with, only the most recently bound value will be available at the top level by using a single variable name. In the following example, that is df2.

 > $\mathrm{with}\left(\mathrm{df2}\right)$
 $\left[{a}{,}{c}\right]$ (12)
 > $a$
 $\left[\begin{array}{cc}{1}& {5}\\ {2}& {7}\end{array}\right]$ (13)

You can still refer to a column of any other DataFrame by naming the DataFrame it comes from, using syntax of the form df[':-a']. If you were to write just df[a], then the variable a would first evaluate to the corresponding column of df2, and df cannot infer which column is meant. This results in an error message. Using the syntax :-a makes sure that the global name a is used, not the column name from df2. In this case, that global name was assigned a value (namely, 12.3); we do not want :-a to evaluate to that value either: if it would, then df could still not infer which column is meant. In order to prevent :-a from evaluating, we use unevaluation quotes.

 > $\mathrm{df}\left[a\right]$
 > $\mathrm{df}\left[:-a\right]$
 > $\mathrm{df}\left[':-a'\right]$
 $\left[\begin{array}{cc}{1}& {1}\\ {2}& {3}\end{array}\right]$ (14)

Compatibility

 • The DataFrame/with and DataFrame/unwith commands were introduced in Maple 2016.
 • For more information on Maple 2016 changes, see Updates in Maple 2016.

 See Also