Tutorial (Settings and Controls)

In the previous section of our tutorial we have just built a simple sampling widget. Let us now make this widget a bit more useful, by allowing a user to set the proportion of data instances to be retained in the sample. Say we want to design a widget that looks something like this:

What we added is an Options box, with a spin entry box to set the sample size, and a check box and button to commit (send out) any change we made in setting. If the check box with “Commit data on selection change” is checked, than any change in the sample size will make the widget send out the sampled dataset. If datasets are large (say of several thousands or more) instances, we may want to send out the sample data only after we are done setting the sample size, hence we left the commit check box unchecked and press “Commit” when we are ready for it.

This is a very simple interface, but there is something more to it. We want the settings (the sample size and the state of the commit button) to be saved. That is, any change we made, we want to save it so that the next time we open the widget the settings is there as we have left it

Widgets Settings

Luckily, since we use the base class OWBaseWidget, the settings will be handled just fine. We only need to tell which variables we want to use for persistent settings.

In our widget, we will use two settings variables, and we declare this in the widget class definition (after the inputs, outputs definitions).

class OWDataSamplerB(OWBaseWidget):
    name = "Data Sampler (B)"
    description = "Randomly selects a subset of instances from the dataset."
    icon = "icons/DataSamplerB.svg"
    priority = 20

    class Inputs:
        data = Input("Data", Orange.data.Table)

    class Outputs:
        sample = Output("Sampled Data", Orange.data.Table)

    proportion = settings.Setting(50)
    commitOnChange = settings.Setting(0)

All settings have to specify their default value. When a widget is created the widget’s members are already restored and ready to use in its __init__ method. The contents of the two variables (self.proportion and self.commitOnChange) will be saved upon closing our widget. In our widget, we won’t be setting these variables directly, but will instead use them in conjunction with GUI controls.

Controls and module gui

We will use the orangewidget.gui to create/define the gui. With this library, the GUI definition part of the options box is a bit dense but rather very short

        box = gui.widgetBox(self.controlArea, "Info")
        self.infoa = gui.widgetLabel(box, 'No data on input yet, waiting to get something.')
        self.infob = gui.widgetLabel(box, '')

        gui.separator(self.controlArea)
        self.optionsBox = gui.widgetBox(self.controlArea, "Options")
        gui.spin(self.optionsBox, self, 'proportion',
                 minv=10, maxv=90, step=10, label='Sample Size [%]:',
                 callback=[self.selection, self.checkCommit])
        gui.checkBox(self.optionsBox, self, 'commitOnChange',
                     'Commit data on selection change')
        gui.button(self.optionsBox, self, "Commit", callback=self.commit)
        self.optionsBox.setDisabled(True)

We are already familiar with the first part - the Info group box. To make widget nicer, we put a separator between this and Options box. After defining the option box, here is our first serious gui control: a orangewidget.gui.spin(). The first parameter specifies its parent widget/layout, in this case self.optionsBox (the resulting widget object will automatically append itself to the parent’s layout). The second (self) and third ('proportion') define the property binding for the spin box. I.e. any change in the spin box control will automatically be propagated to the self.proportions and vice versa - changing the value of self.proprotions in the widget code by assignment (e.g. self.proprotions = 30) will update the spin box’s state to match.

The rest of the spin box call gives some parameters for the control (minimum and maximum value and the step size), tells about the label which will be placed on the top, and tells it which functions to call when the value in the spin box is changed. We need the first callback to make a data sample and report in the Info box what is the size of the sample, and a second callback to check if we can send this data out. In orangewidget.gui, callbacks are either references to functions, or a list with references, just like in our case.

With all of the above, the parameters for the call of orangewidget.gui.checkBox() should be clear as well. Notice that this and a call to orangewidget.gui.spin() do not need a parameter which would tell the control the value for initialization: upon construction, both controls will be set to the value that is pertained in the associated setting variable.

That’s it. Notice though that we have, as a default, disabled all the controls in the Options box. This is because at the start of the widget, there is no data to sample from. But this also means that when process the input tokens, we should take care for enabling and disabling. The data processing and token sending part of our widget now is

    @Inputs.data
    def set_data(self, dataset):
        if dataset is not None:
            self.dataset = dataset
            self.infoa.setText('%d instances in input dataset' % len(dataset))
            self.optionsBox.setDisabled(False)
            self.selection()
        else:
            self.dataset = None
            self.sample = None
            self.optionsBox.setDisabled(False)
            self.infoa.setText('No data on input yet, waiting to get something.')
            self.infob.setText('')
        self.commit()

    def selection(self):
        if self.dataset is None:
            return

        n_selected = int(numpy.ceil(len(self.dataset) * self.proportion / 100.))
        indices = numpy.random.permutation(len(self.dataset))
        indices = indices[:n_selected]
        self.sample = self.dataset[indices]
        self.infob.setText('%d sampled instances' % len(self.sample))

    def commit(self):
        self.Outputs.sample.send(self.sample)

    def checkCommit(self):
        if self.commitOnChange:
            self.commit()

You can now also inspect the complete code of this widget. To distinguish it with a widget we have developed in the previous section, we have designed a special icon for it. If you wish to test this widget in the Orange Canvas, put its code in the orangedemo directory we have created for the previous widget and try it out using a schema with a File and Data Table widget.

Well-behaved widgets remember their settings - the state of their checkboxes and radio-buttons, the text in their line edits, the selections in their combo boxes and similar.

Persisting defaults

When a widget is removed, its settings are stored to be used as defaults for future instances of this widget.

Updated defaults are stored in user’s profile. It’s location depends on the operating system: (%APPDATA%Orange<version>widgets on windows, ~/Library/ApplicationSupport/orange/<version>/widgets on macOS, ~/.local/share/Orange/<version>/widgets on linux) Original default values can be restored by deleting files from this folder, by running Orange from command line with –clear-widget-settings option, or through Options/Reset Widget Settings menu action.

Schema-only settings

Some settings have defaults that should not change. For instance, when using a Paint Data widget, drawn points should be saved in a workflow, but a new widget should always start with a blank page - modified value should not be remembered.

This can be achieved by declaring a setting with a schema_only flag. Such setting is saved with a workflow, but its default value never changes.

Context dependent settings

Context dependent settings are settings which depend on the widget’s input. For instance, the scatter plot widget contains settings that specify the attributes for x and y axis, and the settings that define the color, shape and size of the examples in the graph.

An even more complicated case is the widget for data selection with which one can select the examples based on values of certain attributes. Before applying the saved settings, these widgets needs to check their compliance with the domain of the actual data set. To be truly useful, context dependent settings needs to save a setting configuration for each particular dataset used. That is, when given a particular dataset, it has to select the saved settings that is applicable and matches best currently used dataset.

Saving, loading and matching contexts is taken care of by context handlers. Currently, there are only two classes of context handlers implemented. The first one is the abstract ContextHandler and the second one is DomainContextHandler in which the context is defined by the dataset domain and where the settings contain attribute names. The latter should cover most of your needs, while for more complicated widgets you will need to derive a new classes from it. There may even be some cases in which the context is not defined by the domain, in which case the ContextHandler will be used as a base for your new handler.

Contexts need to be declared, opened and closed. Opening and closing usually takes place (in the opposite order) in the function that handles the data signal. This is how it looks in the scatter plot (the code is somewhat simplified for clarity).

@Input.data
def set_data(self, data):
    self.closeContext()
    self.data = data
    self.graph.setData(data)

    self.initAttrValues()

    if data is not None:
        self.openContext(data.domain)

    self.updateGraph()
    self.sendSelections()

In general, the function should go like this:

• Do any clean-up you need, but without clearing any of the settings that need to be saved. Scatter plot needs none.

• Call self.closeContext(); this ensures that all the context dependent settings (e.g. attribute names from the list boxes) are remembered.

• Initialize the widget state and set the controls to some defaults as if there were no context retrieving mechanism. Scatter plot does it by calling self.initAttrValues() which assigns the first two attributes to the x and y axis and the class attribute to the color. At this phase, you shouldn’t call any functions that depend on the settings, such as drawing the graph.

• Call self.openContext(data.domain) (more about the arguments later). This will search for a suitable context and assign the controls new values if one is found. If there is no saved context that can be used, a new context is created and filled with the default values that were assigned at the previous point.

• Finally, adjust the widget according to the retrieved controls. Scatter plot now plots the graph by calling self.updateGraph().

When opening the context, we provide the arguments on which the context depends. In case of DomainContextHandler, which scatter plot uses, we can give it a Orange.data.Domain. Whether a saved context can be reused is judged upon the presence of attributes in the domain.

If the widget is constructed appropriately (that is, if it strictly uses orangewidget.gui controls instead of the Qt’s), no other administration is needed to switch the context.

Except for declaring the context settings, that is. Scatter plot has this in its class definition

settingsHandler = DomainContextHandler()
attr_x = ContextSetting("")
attr_y = ContextSetting("")

auto_send_selection = Setting(True)
toolbar_selection = Setting(0)
color_settings = Setting(None)
selected_schema_index = Setting(0)

settingsHandler = DomainContextHandler() declares that Scatter plot uses DomainContextHandler. The attr_x and attr_y are declared as ContextSetting.

Migrations

At the beginning of this section of the tutorial, we created a widget with a setting called proportion, which contains a value between 0 and 100. But imagine that for some reason, we are not satisfied with the value any more and decide that the setting should hold a value between 0 and 1.

We update the setting’s default value, modify the appropriate code and we are done. That is, until someone that has already used the old version of the widget open the new one and the widget crashes. Remember, when the widget is opened, it has the same settings that were used the last time.

Is there anything we can do, as settings are replaced with saved before the __init__ function is called? There is! Migrations to the rescue.

Widget has a special attribute called settings_version. All widgets start with a settings_version of 1. When incompatible changes are done to the widget’s settings, its settings_version should be increased. But increasing the version by it self does not solve our problems. While the widget now knows that it uses different settings, the old ones are still broken and need to be updated before they can be used with the new widget. This can be accomplished by reimplementing widget’s methods migrate_settings (for ordinary settings) and migrate_context (for context settings). Both method are called with the old object and the version of the settings stored with it.

If we bumped settings_version from 1 to 2 when we did the above mentioned change, our migrate_settings method would look like this:

def migrate_settings(settings, version):
   if version < 2:
     if "proportion" in settings:
        settings["proportion"] = settings["proportion"] / 100

Your migration rules can be simple or complex, but try to avoid simply forgetting the values, as settings are also used in saved workflows. Imagine opening a complex workflow you have designed a year ago with the new version of Orange and finding out that all the settings are back to default. Not fun!

Warning

If you change the format of an existing setting in a backwards-incompatible way, you will also want to change the name of that setting. Otherwise, older versions of Orange won’t be able to load workflows with the new setting format.

There are two helper functions you can use. Orange.widget.settings.rename_settings(settings, old_name, new_name) does the obvious operation on settings, which can be either a dictionary or a context, thus it can be called from migrate_settings or migrate_context.

Another common operation may be upgrading your widget from storing variable names (as str) to storing variables (instances of classes derived from Variable). In a typical scenario, this happens when combo boxes are upgraded to using models. Function Orange.widget.settings.migrate_str_to_variable(settings, names=None) makes the necessary changes to the settings listed in names. names can be a list of setting names, a single string or None. In the latter case, all settings that may refer to variables (that is two-elements tuples consisting of a string and an int) are migrated.

What about situations in which some context settings become inapplicable due to some changes in the widget? For instance, a widget that used to accept any kind of variables is modified so that it requires a numeric variable? Context with categorical variables will match and be reused … and crash the widget. In these (rare) cases, migrate_context must raise exception Orange.widget.settings.IncompatibleContext and the context will be removed.

So take some time, write the migrations and do not forget to bump the settings_version when you do breaking changes.