Writing Plug-ins

A Shape-Link plug-in is a Python script with a class derived from shapelink.ShapeLinkPlugin and some additional meta data. Let’s have a look at this example plugin which prints the rolling mean of a few scalar features to stdout:

import shutil

import numpy as np

from shapelink import ShapeLinkPlugin

# We use the terminal width to make sure a line doesn't get cluttered
# with prints from a previous line.
TERMINAL_WIDTH = shutil.get_terminal_size((80, 20))[0]


class RollingMeansPlugin(ShapeLinkPlugin):
    """Displays a rolling mean of a few scalar features"""
    def __init__(self, *args, **kwargs):
        super(RollingMeansPlugin, self).__init__(*args, **kwargs)
        self.window_size = 100
        self.scalar_data = {}

    def after_register(self):
        print(" Preparing for transmission")
        for feat in self.reg_features.scalars:
            self.scalar_data[feat] = np.zeros(self.window_size) * np.nan

    def after_transmission(self):
        print("\n End of transmission\n")

    def choose_features(self):
        return list()

    def handle_event(self, event_data):
        """Handle a new event"""
        window_index = event_data.id % self.window_size
        for ii, feat in enumerate(self.reg_features.scalars):
            self.scalar_data[feat][window_index] = event_data.scalars[ii]
        # print the first three features to stdout
        msgs = [" Rolling means: "]
        num_prints = min(3, len(self.reg_features.scalars))
        for ii in range(num_prints):
            feat = self.reg_features.scalars[ii]
            msgs.append("{}: {:.3g}".format(feat,
                                            np.mean(self.scalar_data[feat])))
        line = "  ".join(msgs)
        if len(line) < TERMINAL_WIDTH:
            line += " " * (TERMINAL_WIDTH - len(line))
        print(line, end="\r", flush=True)

        return False


info = {
    "class": RollingMeansPlugin,
    "description": "Display the rolling mean of a few scalar features",
    "name": "Rolling Means",
    "version": "0.1.1",
}

The main action happens in the handle_event function. Your plugin must implement both this function and the choose_features function, which can be used to specify three lists of features (scalar, traces, images). The Verify Aspect Ratio plugin shows how to use the choose_features function. The two functions after_register and after_transmission can be used to set things up (e.g. creation of an additional output file) or to tear things down (e.g. closing that file). Use the __init__ function for defining additional class properties. The info dictionary is required so that the plugin can be run via the Command-line interface.