Guidelines to develop Ion Reporter™ Software plugins

A short description for the plugin can be included after the plugin class declaration as shown in the line 4 in the code sample. If you do not include a short description, you will receive a warning message.

The version attribute is mandatory in the plugin script. Define the version in the plugin as given in line 5 in the code example.

The Python class that inherits from the IonPlugin base class should call the main as shown in the sample code in lines 9 and 10.

MyIonPlugin.py 

1 #!/usr/bin/env python
 2 from ion.plugin import *
 3 class MyIonPlugin(IonPlugin):
 4     '''This is a sample plugin'''
 5     version = '5.4.0.1'
 6     def launch(self):
 7         print "This is a python-based plugin
 8
 9 if __name__ == "__main__":
10     PluginCLI()

The above mentioned class is considered as a wrapper class to the plugin script. This above class is used for the IR plugin framework to validate. We would recommend developer to maintain this format and write another class called MyIonPlugin_plugin.py which contains all the main processing. Calling <plugin_name>_plugin.py from <plugin_name>.py is recommended way of structuring.

Example <plugin_name>.py which acts as a wrapper class and which in-turn calls <plugin_name>_plugin.py:

At the time of plugin run, Plugin is provided with the startplugin.json and barcodes.json in its running directory which allows the plugin to access these json files as if they are available in their current working directory.

In the code above, lines 18 and 19 show the way how to access these files.

More information on these json files are provided in the sections below.

Naming convention for the plugin zip

  • IR plugin framework has some validations against how the zip file should be named.
  • After compressing the plugin contents into the zip, the zip name should be given as <plugin_name>_<version>.zip.

  • For example: From the above code snippet, the plugin zip file name should look like MyIonPlugin_5.4.0.1.zip.

How to create the plugin zip

  1. Create a folder with pluginname_version.

  2. Keep the files/folders in it.

  3. Below are the files that every plugin should contain for IR to validate it.

    • Instance_ir.html

      • This html file is used by plugin framework to show the plugin configuration page in the plugins tab at the analysis launch time.

      • This html file should contain the parameters that should be configured at the time of launching the plugin.

      • User can modify/configure parameters during workflow creation/analysis launch. When user clicks on the configure icon then it shows instance_ir.html which get the default parameters from database and user can modify those. Please refer the instance_ir.html in ampliSeqRNA plugin for more info.

    • Parameters.json

      • Plugin framework expects the file called parameters.json in the plugin zip.

      • At the time of installation, plugin framework will save the default values required for the plugin in the database. These default values for those keys to be given in parameters.json.

      • At run time, IR will display plugin's instance_ir.html to configure plugin parameters at the analysis launch time. Once configured, plugin framework will provide these values for the plugin usage under key called "pluginconfig" in the startplugin json file. The startplugin.json file is provided under the plugin results directory. The results directory can be accessed through the environment variable called "RUNINFO_RESULTS_DIR".

      • The parameters.json file should contain all the keys and default values for all these keys. These keys in this file should match the parameters to be configured using instance_ir.html.

      • The parameters.json file should be specific to plugin. ampliSeqRNA plugin parameters.json is different from RNAseq plugin parameters.json.

      • Please refer the default paramaters.json file for more information.

    • MyIonPlugin.py file

      • The MyIonPlugin.py file name should be the same name as the ZIP file name (MyIonPlugin_5.4.0.1.zip), but with no version in it.

      • This python class should implement IonPlugin base class provided by the plugin framework.

      • This IonPlugin base class expects the plugin to have mandatory attribute version, have a method called PluginCLI() method inside __main__, and also to have a method definition for launch(self).

    • Sample contents in ampliSeqRNA plugin:

  4. Select the folder and create the ZIP file by right-clicking.

Plugin APIs

Plugin APIs are used to fetch/update the plugin parameters. These APIs are part of instance_ir.html; refer to instance_ir.html for more info.

Following are the available APIs:

  • To get the reference genome:

    • URL: /plugin-api/v1/referencegenome

  • To fetch the already saved parameters:

    • URL: '/plugin-api/v1/results?pluginId=' + <<PLUGINID>>+ '&workflowId=' + <<WORKFLOWID>>

  • To fetch the target region's based on reference genome:

    • /plugin-api/v1/targetRegions?genome= <<REFERENCE-GENOME>>

  • T

    o fetch the target region's based on reference genome and target region:

    • URL: /plugin-api/v1/targetRegions?genome=<<REF-GENOME>> &targetRegion= <<TARGET-REGION_NAME>>

Validation

After the plugin is finalized, it needs to be compressed into the ZIP file. The Imbalance file name should be the same name given to the file <plugin_name>.py. Ion Reporter™ Software validates this ZIP file to check whether this plugin has valid version attributes and whether this plugin has implemented IonPlugin class.

Below are the validations performed during the plugin installation:

  1. Plugin ZIP file should have the at least one python file.

  2. Valid python file should import the ion.plugin package.

  3. Valid python file should have class name.

  4. Valid python file should have version attribute.

  5. pluginname_version is used to check the uniqueness. So newly installed plugin should not have the plugin name and version, which is already installed.

  6. Plugin ZIP file should have parameters.json inside it with default values otherwise plugin will not generate the proper result.

HTML's for visualization

After the plugin analysis is launched and successful, for the developer to view the plugin results using IR visualization:

  • Plugin should generate <plugin_name>.html and <any_name>_block.html (optional) files in the plugin output folder. path: <analysis_root_dir>/outputs/TsPluginActor-00/<Plugin_name>/

  • If the _block.html is generated then IR software would show the results in a block like frame as a mini view.

  • The frame will have a button called "View Summary" that contains the link to open <plugin_name>.html file in a new tab.

Plugin results

For the plugin developer to view the results in the backend, the results are available at the following path: <analysis_root_dir>/outputs/TsPluginActor-00/<Plugin_name>/

Download logs

For the plugin developer to view the plugin logs in the backend, the logs are available at the following path: <analysis_root_dir> /log/TsPluginActor-00/ <Plugin_name>/

If the <plugin_name>.log file is generated, user can download logs. Ion Reporter™ Software would show the "Download Log" in a block header.

Scratch directory

  • For the plugin developer to save any intermediate generated files from that plugin for re-use in subsequent plugin runs, these could be saved in pluginScratch directory.

  • Developer should be able to access the environment variable called TSP_PLUGIN_SCRATCH and can create a folder under this scratch directory with your plugin name <plugin_name> to save the results.

Sample and Environment details

At run time, the developer is provided with two JSON files, startplugin.json and barcodes.json, in the plugin results directory.

The developer can access these JSON files in the MyIonPlugin.py script in the barcodes.json file.

  • The barcodes.json file contains the sample information that has been selected at the analysis launch time.

  • The barcodes.json file is mainly used to read the bam_file_path, target_regions_file_path, genome_reference_name, genome_reference_file_path, and barcode_name.

  • Below is an example barcodes.json file generated by the plugin framework: 

{
  "bc1" : {
    "genome_urlpath" : "",
    "nucleotide_type" : "",
    "control_sequence_type" : "",
    "barcode_name" : "bc1",
    "sample_id" : "",
    "barcode_type" : "",
    "barcode_annotation" : "",
    "sample" : "SampleCustom",
    "reference_fullpath" : "/data/IR/data/.reference/hg19/hg19.fasta",
    "target_region_filepath" : "",
    "reference" : "hg19",
    "filtered" : "",
    "barcode_sequence" : "",
    "hotspot_filepath" : "",
    "barcode_index" : "",
    "bam_file" : "1_1_IonXpress_009_rawlib.bam",
    "barcode_adapter" : "",
    "barcode_description" : "",
    "bam_filepath" : "/data/IR/data/IR_Org/data/IRU_Uploads/20170306_02_12_48/v1/new_ocp_rna/1_1_IonXpress_009_rawlib.bam",
    "aligned" : "",
    "control_type" : "",
    "read_count" : ""
  }
}

  • If the sample being used in the analysis was uploaded through the IonReporterUploader plugin, then the barcodes json might contain more information, for example the "read_count", "barcode_adapter", "nucleotide_type", "barcode_sequence", etc.

    .

  • Below is the sample barcodes json if the sample is uploaded through IonReporterUploader plugin: 

{
  "IonXpress_005" : {
    "read_count" : 1836237,
    "sse_filepath" : "",
    "reference" : "hg19",
    "genome_urlpath" : "",
    "barcode_adapter" : "GAT",
    "sample" : "Dw2-4hr",
    "sample_id" : "",
    "barcode_type" : "",
    "hotspot_filepath" : "",
    "barcode_description" : "",
    "control_type" : "",
    "target_region_filepath" : "",
    "control_sequence_type" : "",
    "bam_filepath" : "/data/IR/data/IR_Org/data/IRU_Uploads/2017-3-20_11_10_49/v1/Dw2-4hr_RNA_v1/IonXpress_005_rawlib.bam",
    "filtered" : false,
    "barcode_index" : 5,
    "bam_file" : "IonXpress_005_rawlib.bam",
    "aligned" : true,
    "barcode_name" : "IonXpress_005",
    "barcode_annotation" : "",
    "nucleotide_type" : "RNA",
    "barcode_sequence" : "CAGAAGGAAC",
    "reference_fullpath" : "/data/IR/data/.reference/hg19/hg19.fasta"
  }
}

The startplugin.json file

At the analysis launch time, in the user interface, the user could configure his/her own plugin according to their requirements. These configured parameters will be provided in the startplugin.json file under the key called "pluginconfig".

For example, if the user has selected the reference as hg19 in the plugin user interface (instance_ir.html using plugin APIs to get the values from IR DB (see below plugin APIs section for more information), then these values would be provided to the plugin in the startplugin.json file as below: 

"pluginconfig" : {
 "reference" : "/data/IR/data/.reference/hg19/hg19.fasta"
 }

Therefore, the plugin developer could read the above path to access the reference file that has been selected in the user interface.

The startplugin.json file contains some Ion Reporter™ Software and plugin metadata, such as plugin_dir (plugin zip contents), results_dir (where plugin output should be written).

If the sample being used in Ion Reporter™ Software was uploaded using IonReporterUploader plugin in Torrent Suite™ Software, then the startplugin.json file will contain extra metadata, such as chipType, library, barcodeName, system_type and so on. Given the example startplugin.json as below, if the sample has been uploaded using the IonReporterUploader plugin: 

 {
  "expmeta" : {
    "sample" : "HBR",
    "runid" : "QRIBT",
    "run_name" : "R_2016_08_05_13_17_55_user_S5-00111-181-LifeLab_DW_08052016_B",
    "run_flows" : 500,
    "output_file_name_stem" : "R_2016_08_05_13_17_55_user_S5-00111-181-LifeLab_DW_08052016_B_Auto_user_S5-00111-181-LifeLab_DW_08052016_B_30836",
    "run_date" : "2016-08-05T20:19:39Z",
    "chiptype" : "530",
    "flowOrder" : "TACGTACGTCTGAGCATCGATCGATGTACAGC",
    "barcodeId" : "IonXpress",
    "analysis_date" : "2016-08-05",
    "chipBarcode" : "DBCD02486",
    "project" : "LifeLab",
    "instrument" : "S5-00111",
    "results_name" : "Auto_user_S5-00111-181-LifeLab_DW_08052016_B_30836",
    "notes" : ""
  },
  "pluginconfig" : {
    "reference" : "/data/IR/data/.reference/hg19/hg19.fasta",
    "genome" : "hg19"
  },
  "runinfo" : {
    "testfrag_key" : "ATCG",
    "url_root" : "",
    "chipType" : "530",
    "library" : "hg19",
    "sigproc_dir" : "",
    "pluginresult" : 881041,
    "api_url" : "",
    "barcodeId" : "IonXpress",
    "results_dir" : "/data/IR/data/IR_Org/ion.reporter@lifetech.com/Dw2-4hr_RNA_v1/Dw2-4hr_RNA_v1_20170321131007199/outputs/TsPluginActor-00/RNASeqAnalysis",
    "platform" : "s5",
    "pk" : 61178,
    "alignment_dir" : "",
    "api_key" : "",
    "basecaller_dir" : "",
    "net_location" : "",
    "username" : "",
    "library_key" : "TCAG",
    "systemType" : "S5",
    "plugin_name" : "RNASeqAnalysis",
    "tmap_version" : "",
    "report_root_dir" : "/data/IR/data/IR_Org/ion.reporter@lifetech.com/Dw2-4hr_RNA_v1/Dw2-4hr_RNA_v1_20170321131007199",
    "chipDescription" : "530",
    "plugin_dir" : "/share/apps/IR/ionreporter54/apps/IR_Org/RNASeqAnalysis",
    "raw_data_dir" : "",
    "analysis_dir" : "/data/IR/data/IR_Org/ion.reporter@lifetech.com/Dw2-4hr_RNA_v1/Dw2-4hr_RNA_v1_20170321131007199"
  },
  "plan" : {
    "planName" : "LifeLab_DW_08052016_B",
    "username" : "",
    "sequencekitname" : "Ion S5 Sequencing Kit",
    "librarykitname" : "Ion AmpliSeq RNA Library Kit",
    "sampleGrouping" : null,
    "sseBedFile" : "",
    "barcodeId" : "IonXpress",
    "controlSequencekitname" : "",
    "regionfile" : "",
    "runMode" : "single",
    "bedfile" : "",
    "templatingKitName" : "Ion Chef S530 V1",
    "samplePrepKitName" : "",
    "runType" : "AMPS_RNA",
    "runTypeDescription" : "AmpliSeq RNA",
    "reverse_primer" : "",
    "threePrimeAdapter" : "ATCACCGACTGCCCATAGAGAGGCTGAGAC",
    "sampleTubeLabel" : ""
  }
}
Related Topics
Parent topic: Programming guidelines for Ion Reporter™ Software plugins