👨‍💻For BioMate Developer

This document describes how to package a BioMate plugin

Introduction to input file types

In BioMate, files are mainly categorized into six types. We would like to acknowledge the Hiplot open-source project, as the tool-type files from Hiplot are used here as a reference, which also facilitates the future integration of Hiplot’s open-source tools.

1. Metadata file: The metadata file is primarily used to describe the basic information of the tool, including the tool name, and so on.

2. UI file (ui.json): Defines the Notebook plugin page. By specifying the components included in the plugin, the system reads the JSON and renders them onto the plugin page.

3. Configurable parameters file (input.json): Defines configurable plotting parameters or general parameters for visualization tools. The configuration parameters in the code must read the default settings provided in this file.

4. Code file (plot.R): This can be either a Python or an R file. By defining the code file, the configurations specified by the user on the plugin page are executed through the code to produce output results.

5. Example image: Each plugin includes an example image to help users understand the functionality and effects of the plugin.

6. Example data: Provides sample data for the plugin to help users test its functionality.

Description and examples of input files

Metadata File

metadata file: Primarily used to describe the basic information of the tool.

636B

meta.json

Open

meta.json file: Currently, the following fields require attention.

1. name：represents the current tool name.

2. sample_img ：reads the image parameter from this field as the example image.

3. sample_data_file：reads the parameter from this field as the example data.

4. output_img：reads the parameter from this field as the Notebook output image.

5. main：main code file to run.

6. run：execution command.

UI File

For the UI definition of the interactive page, the field parameters in the JSON file correspond to the tool page parameters as follows:

• data：rawdata

• columns：data parameters

• General：general parameters

• Plotsetting: plotting parameters

Example:

2KB

ui.json

Open

Input parameter file

Used to specify the configurable input parameters of the tool. The input parameters columns, general, and plotsetting correspond to the columns, general, and plotsetting parameters in the UI page. An example file is shown below:

568B

input.json

Open

Code file

Core executable file: In BioMate, the core executable file of a tool relies on the input parameter file for configuration. All parameters used in the tool must be defined in the input parameter file to ensure their configurability. Here, the Venn diagram tool code is provided as an example.

6KB

venndiagram.r

Open

Example image

Each tool requires an example image, primarily displayed on the left side of the tool interface. For instance, the Venn diagram tool provides the following example image.

Demo data

Each tool must include example data. Example data helps users test tool parameters when inserting the tool into a Notebook and generate visualizations based on it. The example data may vary between tools and can be provided in txt or csv format. You can customize it by editing the data reading logic in the core code. The following is the example data used in the Venn diagram tool.

2KB

testData.csv

Open

How to test whether the code runs correctly in a Notebook

1. Complete the implementation of the core code and the input parameter file (refer to the example code above).

   1. The code must specify a configuration file (input.json) and read fields from it as input parameters. For example, the title field in input.json can be passed to the venn.diagram function as config$general$title.

input.json

使用venndiagram绘制韦恩图代码

Parameters used in the code and the corresponding data files that need to be read.

1. Prepare the test data (refer to the example data mentioned earlier).

2. Upload the files to the Notebook storage directory, as shown in the figure below.

1. Run the code blow

Rscript volcanoPlot.r plot --config input.json --output output.jpg

Integration testing of visualization tools with BioMate

Prerequisite：

1. For local installation, refer to the official JupyterLab documentation https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html

2. If your code contains R code, make sure that an R environment is installed locally.

3. The bio_mate JupyterLab extension has been installed and can be set up by executing the installation command in the JupyterLab command line. pip install -i https://test.pypi.org/simple/ bio-mate==0.1.0

1. Copy the visualization tool folder to be tested into the bio_mate/plot-defs directory and rename it to myplot, as shown in the figure below:

The location of the bio_mate folder can be obtained as shown in the figure below, or you can directly locate the plot-defs folder by running the following command:

find / -name plot-defs

1. Restart the IPython kernel and refresh the browser to allow bio_mate to initialize the myplot module.

1. Execute the following statement in the Notebook to trigger the rendering of the myplot module and verify whether each parameter is rendered correctly.

1. Click the Generate button to create the visualization and verify that it is generated correctly. You can click View Execution Log for further troubleshooting. Try modifying the parameter values and generate again to check whether the adjustments take effect.

2. Once all the above steps have been successfully debugged, the integration with Bio-Mate is complete. 🎉