Dataset plugins are introduced in Veusz 1.9 to allow the user to write simple Python code to manipulate or create datasets within Veusz. Like import plugins, the file containing the plugin is registered in Veusz in the preferences dialog box.

Dataset plugins, like dataset expressions, are run every time the document changes to maintain a link between input and output datasets. A plugin takes a number of input fields (like an ImportPlugin) and outputs one or more datasets. Registered plugin appears on the Data->Operations menu.

Veusz includes a number of plugins already. These include plugins for adding or multiplying constants to datasets, concatenating datasets, chopping data ranges from datasets, adding or multiplying datasets together, subtracting dataset, computing means of datasets or for computing the extreme ranges of a set of datasets.

Here is an example plugin for adding a constant to an existing 1D dataset. It does the same thing as the built-in add constant to dataset plugin. It has a lot of comments to make it easier to understand.

import veusz.plugins as plugins

class ShiftDatasetPlugin(plugins.DatasetPlugin):
    """Dataset plugin to shift a dataset."""

    # tuple of strings to build position on menu
    menu = ('Shift by constant',)

    # internal name for reusing plugin later
    name = 'ShiftConst'

    # string which appears in status bar
    description_short = 'Shift dataset by a constant'
    
    # string goes in dialog box
    description_full = ('Shift a dataset by a constant. '
                        'This text goes into the dialog box.')
    
    def __init__(self):
        """Define input fields for plugin."""
        self.fields = [
            plugins.FieldDataset('ds_in', 'Input dataset'),
            plugins.FieldFloat('value', 'Value', default=0.),
            plugins.FieldDataset('ds_out', 'Output dataset name'),
            ]

    def getDatasets(self, fields):
        """Returns single output dataset (self.dsout).
        This method should return a list of Dataset objects, which can include
        Dataset1D, Dataset2D and DatasetText
        """

        # raise DatasetPluginException if there are errors
        if fields['ds_out'] == '':
            raise plugins.DatasetPluginException('Invalid output dataset name')

        # make a new dataset with name in fields['ds_out']
        self.ds_out = plugins.Dataset1D(fields['ds_out'])

        # return list of datasets
        return [self.ds_out]

    def updateDatasets(self, fields, helper):
        """Do shifting of dataset.
        This function should *update* the dataset(s) returned by getDatasets
        """

        # get the input dataset - helper provides methods for getting other
        # datasets from Veusz
        ds_in = helper.getDataset(fields['ds_in'])
        # get the value to add
        v = fields['value']

        # just to be explicit
        newdata = ds_in.data + v

        # update output dataset with input dataset (plus value) and errorbars
        self.ds_out.update(data=newdata,
                           serr=ds_in.serr, perr=ds_in.perr, nerr=ds_in.nerr)

# add plugin classes to this list to get used
plugins.datasetpluginregistry.append(ShiftDatasetPlugin)

Plugins are classes which are derived from DatasetPlugin. Veusz will create instances of the class each time the plugin is used to create dataset(s). There are three methods which are required (see below), plus some class attributes need to be defined. getDatasets is separate from updateDatasets because Veusz needs to know dataset names in order to get the dependencies correct when updating.

• menu: tuple of strings to build up submenus and menu item, e.g. ('my sub menu', 'my plugin') or just ('my plugin',). Can contain unicode.
• name: unique name for plugin. Used in saved documents to recreate plugin datasets.
• description_short: description which appears in status bar when user is about to click on menu items. Can be unicode.
• description_full: description which appears in plugin's dialog box. This can be unicode and include \n for new lines.

__init__(self) should initialize self.fields to be a list of input fields, listed in PluginFields. These fields are presented to the user in the plugin dialog box. The values input are given to the plugin in getDatasets and updateDatasets.

getDatasets(self, fields) is a method to take the input values of the fields and return a list of datasets which the plugin will output.

• fields is a dict mapping input field names to user-entered values.
• The dataset types the plugin can return are listed in PluginDatasetTypes.
• This method should save these datasets in the instance to be updated each time the updateDatasets is called.
• It is normal to leave the datasets returned by getDatasets uninitialized.
• Veusz will call updateDatasets when they are used for the first time and on subsequent document changes. See below for details about the dataset objects which can be returned.
• Raise a DatasetPluginException('text') to notify the user about problems, including invalid input values in fields.

updateDatasets(self, fields, helper) is a method to update the dataset objects returned by getDatasets with new values as the document has been changed, or on the datasets' first use.

• fields is the same dict mapping input field names to user-entered values
• helper is a DatasetPluginHelper object which allows the plugin to get access to other datasets in the Veusz document (see below).
• Raise a DatasetPluginException('text') to inform the user there was a problem updating the datasets. The output datasets will be nulled. Errors will appear in the Veusz console unless the plugin has just been called from the dataset plugin dialog, in which case a message box will appear.

This object lets the plugin get other datasets from the document. Here are its methods:

class DatasetPluginHelper(object):
    """Helpers to get existing datasets for plugins."""

    # datasets1d: property to return list of names of existing 1D numeric datasets
    # datasets2d: property to return list of names of existing 2D numeric datasets
    # datasetstext: property to return list of names of existing text datasets

    def getDataset(self, name, dimensions=1):
        """Return numerical dataset object for name given.
        Please make sure that dataset data are not modified.

        name: name of dataset
        dimensions: number of dimensions dataset requires

        name not found: raise a DatasetPluginException
        dimensions not right: raise a DatasetPluginException
        """

    def getDatasets(self, names, dimensions=1):
        """Get a list of numerical datasets (of the dimension given)."""

    def getTextDataset(self, name):
        """Return a text dataset with name given.
        Do not modify this dataset.

        name not found: raise a DatasetPluginException
        """

    def evaluateExpression(self, expr, part='data'):
        """Return results of evaluating a 1D dataset expression.
        part is 'data', 'serr', 'perr' or 'nerr' - these are the
        dataset parts which are evaluated by the expression
        """

Plugins in saved documents are run using the DatasetPlugin function in the Veusz command line interface. This can be used by the user in the embedding interface, console window, etc. The usage is DatasetPlugin(pluginname, fields), where pluginname is the name of the plugin (the name class attribute in the plugin class) and fields is a dict mapping plugin parameter names to values.