This repository contains the source code for PluginInterop, the Perseus plugin that provides the foundation for plugins developed in e.g. R and Python, and allows them to be executed from within the Perseus workflow.
The plugin is designed to work with other Perseus interop efforts such as:
Generic scripts do not have a dedicated button in the GUI. They are run via the generic activities such as Matrix -> Processing -> External -> Python => Matrix.
- Select the script file you want to run. Consult the documentation below on how to create such scripts.
- Provide additional parameters to the script. Parameters should be described in the documentation of the specific script you are running.
- Specify the location of the
Pythonexecutable. Perseus will try to automatically detect yourPythoninstallation (see Technical notes below). If not detected automatically, manually navigate to thepython.exeof yourPythoninstallation. The button should turn green to indicate success. If the button turns red, mouseover it to obtain more information. - Run the script.
Hybrid scripts have a dedicated button in the GUI. Refer to point 3. in the section on generic scripts for instructions.
PluginInterop proviedes two new approaches to plugin development for Perseus. We recommend everyone to get started with the generic approach which provides all functionality in the simplest way. Moving from the generic to the hybrid approach improves the user experience when using the plugin but requires basic knowledge of C# development.
Scripts written in R or Python can be run from within the Perseus workflow via generic activities, such as Matrix -> Processing -> External -> R => Matrix. In order to enable smooth communication between Perseus and R/Python it is highly recommended to make use of the PerseusR and perseuspy companion libraries. Visit their websites for instructions on how to adapt or write scripts, including a number of simple examples.
The advantage of the generic approach is the elimination of the need to write any C# code. Anyone knowledgable in Python or R can write plugins for Perseus. Due to its generic nature, this approach has some limitations. There will be no dedicated button in the GUI of Perseus. Additionally, parameters are passed to the plugin in an unstructured way, using command line parameters. If a dedicated GUI and structured parameter selection is required the hybrid approach described below is the way to go.
To specify the representation of the plugin in the GUI of Perseus, developers can extend the classes provided by PluginInterop. Interested developers can refer to PluginPHOTON implemented in PHOTON as a complete example of the hybrid approach.
For C# plugins, Perseus automatically generates a GUI for parameter selection. To leverage this functionality create a new class deriving from PluginInterop.MatrixProcessing and overwrite the default .AddParameters(...) function. For inspiration on how to create the desired parameters see perseus-plugins. The parameters selected by the user are written to an .xml file and its file path is passed to the script instead of the unstructured additional parameters used in the generic approach. In the same derived class were parameters are specified one can also specify the icon of the plugin, automatically load the script file from resources and even check for required package dependencies.
Check out the step-by-step tutorial on PluginTutorial and the associated bootcamp from the MaxQuant summer school.
Perseus will try to automatically detect your R or Python installation, by looking at the default installation directories and the %PATH% variable. Therefore, installations at non-standard locations can be detected, if added to the %PATH%. Adding programs to the %PATH% is different for different Windows versions, so please refer to online help for your specific Windows installation.
The Python installer has an option during the installation to automatically add it to the %PATH%.
Data is passed between Perseus and the external tool via the file system. Perseus will write all input files to the hard drive and will expect to find the output files at a specified location. The file formats of the input file will be equivalent to the established Perseus export functionality. Matrices will be written as a .txt tab-separated text file with annotation rows. Networks will be written in their folder format. Perseus will expect the ouputs of the scripts to have a vaild .txt or folder format.
When a script is executed Perseus will provide it with at least 2 command line arguments:
<additional arguments> inFile outFile
The exact nature of the <additional arguments> differs between the generic and the hybrid approach. In the generic approach, the additional arguments contain the unstructured command line parameters specified in the GUI. In the hybrid approach, the path to the parameters.xml file will be passed to the script.
The inFile contains the matrix in Perseus txt format. The output is expected to be written to outFile once the execution of the script finishes. The addtional arguments are specified in the GUI. More advanced scripts can have multiple input and output files.
If an external tool crashes (returns exit code 1) anything written to stdout and stderr will be reported as error message.
Check the examples.
Clone the repository and build it using Visual Studio.
Contributions are welcome!
PluginInterop is published under the MIT licence.