About Plugins

What is a ChRIS Plugin?

The term "ChRIS app" and "ChRIS plugin" are used interchangably. ChRIS plugins are data processing modules. In most cases it would simply process data from an input directory and save results to an output directory.

      data        ┌───────────────────┐       results
    /incoming ───►│ ChRIS 'DS' plugin ├───► /outgoing
                  └───────────────────┘

Ordinary "input → output" type plugins are known as data synthesis or "DS" plugins. The other kind of plugin is feed synthesis or "FS", which spawn data without existing input. FS plugins are typically used to fetch data from other services such as a PACS database.

    ┌───────────────────┐
    │ ChRIS 'FS' plugin ├───► /outgoing
    └───────────────────┘

The first plugin of a pipeline would always be a single FS plugin followed by a chain (a DAG) of DS plugins. Subsequent DS plugins process data produced by their ancestor.

  ┌──────────────┐  ┌─►/outputdir    ┌─────────────┐  ┌─►/outputdir    ┌─────────────┐  ┌─►/outputdir
  │  'FS' plugin ├──┘      |     ┌──►│ 'DS' plugin1├──┘      |     ┌──►│ 'DS' plugin2├──┘
  └──────────────┘     /inputdir─┘   └─────────────┘     /inputdir─┘   └─────────────┘

These programs are run in remote environments — hence they are non-interactive and do not have graphical user interfaces. Run conditions are all specified before the start of execution, either via command line arguments, an HTTP request to the backend, or by selecting options in the ChRIS web user interface.

Plugin Definition

Anything can be a plugin! It must cohere to this standard command-line interface, or provide a wrapper script which coerces arguments to match this pattern.

# 'DS' plugin
app [OPTIONS...] /inputdir /outputdir
# 'FS' plugin
app [OPTIONS...] /outputdir

Arguments

Optional flags either come in the form of --flag for boolean values, or --flag value for string data type.

Options may not be repeated. For python argparse-based or ChrisApp-based ChRIS plugins, nargs may not be used.

These paradigms are unsupported:

• -vvv or -v -v -v

• --option 1 --option 2 --option 3

Consider alternate approaches like

• -v 3

• --option 1,2,3 (which can be parsed using options.option.split(',')

JSON Description

Plugins are described to the backend by a JSON schema.

{
  "type": "ds",
  "parameters": [
    {
      "name": "age",
      "type": "float",
      "optional": false,
      "flag": "--age",
      "short_flag": "-a",
      "action": "store",
      "help": "gestational age estimate in weeks",
      "default": null,
      "ui_exposed": true
    },
    {
      "name": "side",
      "type": "str",
      "optional": true,
      "flag": "--side",
      "short_flag": "-s",
      "action": "store",
      "help": "brain hemisphere [left, right]",
      "default": "left",
      "ui_exposed": true
    }
  ],
  "icon": "https://raw.githubusercontent.com/FNNDSC/pl-dne/master/icon.png",
  "authors": "Jennings Zhang <Jennings.Zhang@childrens.harvard.edu>",
  "title": "Surface extraction",
  "category": "MRI",
  "description": "Extract surfaces (.obj) from pre-segmented fetal brain MRI volume (.mnc) using marching-cubes and surface_fit",
  "documentation": "https://github.com/FNNDSC/pl-dne/wiki",
  "license": "Opensource (MIT)",
  "version": "1.0",
  "selfpath": "/usr/local/bin",
  "selfexec": "extract_surface",
  "execshell": "python3",
  "max_number_of_workers": 1,
  "min_number_of_workers": 1,
  "max_memory_limit": "",
  "min_memory_limit": "",
  "max_cpu_limit": "",
  "min_cpu_limit": "",
  "max_gpu_limit": 0,
  "min_gpu_limit": 0
}

Internally, the description of a plugin (its authors, license, parameters, resource limits) is termed as "plugin meta."

A plugin representation JSON can be automatically generated for Python scripts using an argparse-like definition by extending the ChrisApp superclass.

Tip	Ready to get started? Head over to our quickstart guide for Python ChRIS apps.