Dataset Plugins

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.

   1 import veusz.plugins as plugins
   2 
   3 class ShiftDatasetPlugin(plugins.DatasetPlugin):
   4     """Dataset plugin to shift a dataset."""
   5 
   6     # tuple of strings to build position on menu
   7     menu = ('Shift by constant',)
   8 
   9     # internal name for reusing plugin later
  10     name = 'ShiftConst'
  11 
  12     # string which appears in status bar
  13     description_short = 'Shift dataset by a constant'
  14     
  15     # string goes in dialog box
  16     description_full = ('Shift a dataset by a constant. '
  17                         'This text goes into the dialog box.')
  18     
  19     def __init__(self):
  20         """Define input fields for plugin."""
  21         self.fields = [
  22             plugins.FieldDataset('ds_in', 'Input dataset'),
  23             plugins.FieldFloat('value', 'Value', default=0.),
  24             plugins.FieldDataset('ds_out', 'Output dataset name'),
  25             ]
  26 
  27     def getDatasets(self, fields):
  28         """Returns single output dataset (self.dsout).
  29         This method should return a list of Dataset objects, which can include
  30         Dataset1D, Dataset2D and DatasetText
  31         """
  32 
  33         # raise DatasetPluginException if there are errors
  34         if fields['ds_out'] == '':
  35             raise plugins.DatasetPluginException('Invalid output dataset name')
  36 
  37         # make a new dataset with name in fields['ds_out']
  38         self.ds_out = plugins.Dataset1D(fields['ds_out'])
  39 
  40         # return list of datasets
  41         return [self.ds_out]
  42 
  43     def updateDatasets(self, fields, helper):
  44         """Do shifting of dataset.
  45         This function should *update* the dataset(s) returned by getDatasets
  46         """
  47 
  48         # get the input dataset - helper provides methods for getting other
  49         # datasets from Veusz
  50         ds_in = helper.getDataset(fields['ds_in'])
  51         # get the value to add
  52         v = fields['value']
  53 
  54         # just to be explicit
  55         newdata = ds_in.data + v
  56 
  57         # update output dataset with input dataset (plus value) and errorbars
  58         self.ds_out.update(data=newdata,
  59                            serr=ds_in.serr, perr=ds_in.perr, nerr=ds_in.nerr)
  60 
  61 # add plugin classes to this list to get used
  62 plugins.datasetpluginregistry.append(ShiftDatasetPlugin)

Writing plugin classes

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.

Class attributes

• 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__ method

__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 method

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 method

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.

DatasetPluginHelper

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

   1 class DatasetPluginHelper(object):
   2     """Helpers to get existing datasets for plugins."""
   3 
   4     # datasets1d: property to return list of names of existing 1D numeric datasets
   5     # datasets2d: property to return list of names of existing 2D numeric datasets
   6     # datasetstext: property to return list of names of existing text datasets
   7 
   8     def getDataset(self, name, dimensions=1):
   9         """Return numerical dataset object for name given.
  10         Please make sure that dataset data are not modified.
  11 
  12         name: name of dataset
  13         dimensions: number of dimensions dataset requires
  14 
  15         name not found: raise a DatasetPluginException
  16         dimensions not right: raise a DatasetPluginException
  17         """
  18 
  19     def getDatasets(self, names, dimensions=1):
  20         """Get a list of numerical datasets (of the dimension given)."""
  21 
  22     def getTextDataset(self, name):
  23         """Return a text dataset with name given.
  24         Do not modify this dataset.
  25 
  26         name not found: raise a DatasetPluginException
  27         """
  28 
  29     def evaluateExpression(self, expr, part='data'):
  30         """Return results of evaluating a 1D dataset expression.
  31         part is 'data', 'serr', 'perr' or 'nerr' - these are the
  32         dataset parts which are evaluated by the expression
  33         """

Command line interface

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.