The first thing you might want to do is run the swat.describe_option with no arguments. This prints out a description of all of the available options. Printing the description of all options can be rather lengthy. Only a portion is displayed here:
In [76]: swat.describe_option()
cas.dataset.auto_castable : boolean
Should a column of CASTable objects be automatically
created if a CASLib and CAS table name are columns in the data?
NOTE: This applies to all except the 'tuples' format.
[default: True] [currently: True]
cas.dataset.bygroup_as_index : boolean
If True, any by group columns are set as the DataFrame index.
[default: True] [currently: True]
cas.dataset.bygroup_collision_suffix : string
Suffix to use on the By group column name when a By group column
is also included as a data column.
[default: _by] [currently: _by]
... truncated ...
As you can see, the option information is formatted very much like options in Pandas. The description includes the full name of the option, the expected values or data type, a short description of the option, the default value, and the current value.
Since we have already used the cas.exception_on_severity option, let’s look at its description using describe_option, as follows:
In [77]: swat.describe_option('cas.exception_on_severity')
cas.exception_on_severity : int or None
Indicates the CAS action severity level at which an exception
should be raised. None means that no exception should be raised.
1 would raise exceptions on warnings. 2 would raise exceptions
on errors.
[default: None] [currently: None]
As you can see from the description, by default, this option is set to None, which means that exceptions are never thrown. The current value is 2, for exceptions on errors. We can also get the current value of the option by using swat.get_option as follows:
In [78]: print(swat.get_option('cas.exception_on_severity'))
Out[78]: None
Setting options is done using the swat.set_option function. This function accepts parameters in multiple forms. The most explicit way to set an option is to pass in the name of the option as a string followed by the value of the option in the next argument. We have seen this already when we set the cas.exception_on_severity option.
In [79]: swat.set_option('cas.exception_on_severity', 2)
Another form of setting options works only if the last segment of the option name (for example, exception_on_severity for cas.exception_on_severity) is unique among all of the options. If so, then you can use that name as a keyword argument to swat.set_option. The following code is equivalent to the last example:
In [80]: swat.set_option(exception_on_severity=2)
In either of the forms, it is possible to set multiple options with one call to swat.set_option. In the first form, you simply continue to add option names and values as consecutive arguments. In the second form, you add additional keyword arguments. Also, you can mix both. The only caveat is that if you mix them, you must put the positional arguments first just like with any Python function.
In [81]: swat.set_option('cas.dataset.index_name', 'Variable',
....: 'cas.dataset.format', 'dataframe',
....: exception_on_severity=2,
....: print_messages=False)
The next function, swat.reset_option, resets options back to their default value:
In [82]: swat.reset_option('cas.exception_on_severity')
In [83]: print(swat.get_option('cas.exception_on_severity'))
None
Note that we used the print function in the preceding code since IPython does not display a None value as a result. Nonetheless, you can see that the value of cas.exception_on_severity was set back to the default of None.
Just as with swat.describe_option, you can specify multiple names of options to reset. In addition, executing swat.reset_option with no arguments resets all of the option values back to their default values.
The final option function is swat.option_context. Again, this works just like its counterpart in Pandas. It enables you to specify option settings for a particular context in Python using the with statement. For example, if we wanted to turn on CAS action tracing for a block of code, the swat.option_context in conjunction with the Python with statement sets up an environment where the options are set at the beginning of the context and are reset back to their previous values at the end of the context. Let’s see this in action using the cas.trace_actions option:
In [84]: swat.reset_option('trace_actions')
In [85]: swat.get_option('trace_actions')
Out[85]: False
In [86]: with swat.option_context('cas.trace_actions', True):
....: print(swat.get_option('cas.trace_actions'))
....:
True
In [87]: swat.get_option('cas.trace_actions')
Out[87]: False
As you can see in the preceding example, cas.trace_actions was False before the with context was run. The cas.trace_actions was True when it was inside the with context, and afterward, it went back to False. The swat.option_context arguments work the same way as swat.set_option. So you can specify as many options for the context as you prefer, and they can even be nested in multiple with contexts.
Partial Option Name Matches
As we have seen with swat.set_option and swat.option_context, you can use keyword arguments if the last segment of the option name is unique among all the
