public-health-bioinformatics / irida-plugin-micall-lite

Human RNA virus genotyping

IRIDA MiCall-Lite Pipeline Plugin

Genotype viral samples by iterative realignment against reference sequences.

Derived from the MiCall pipeline from the BC Centre for Excellence in HIV/AIDS Research, and MiCall-Lite from Dr. Art Poon at Western University

Table of Contents

• IRIDA MiCall-Lite Pipeline Plugin
• Installation
  • Installing to IRIDA
  • Installing Galaxy Dependencies
• Usage
  • Monitoring Pipeline Status
  • Analysis Results
  • Metadata Table
• Building/Packaging
  • Installing IRIDA to local Maven repository
  • Building the plugin
• Dependencies

Installation

Installing to IRIDA

Please download the provided irida-plugin-micall-lite-[version].jar from the [releases][] page and copy to your /etc/irida/plugins directory. Now you may start IRIDA and you should see the pipeline appear in your list of pipelines.

Note: This plugin requires you to be running IRIDA version >= 19.01. Please see the IRIDA documentation for more details.

Installing Galaxy Dependencies

In order to use this pipeline, you will also have to install several Galaxy tools within your Galaxy instance. These can be found at:

Name	Version	Owner	Metadata Revision	Galaxy Toolshed Link
micall_lite	0.1rc5+galaxy0	public-health-bioinformatics	4 (2020-02-28)	micall_lite-4:27d61a7f82f1
fastp	0.19.5+galaxy1	iuc	8 (2019-05-28)	fastp-8:1d8fe9bc4cb0

Setting up your MiCall-Lite projects.json File

MiCall-Lite requires a projects.json file that defines specific genomic regions and sequences to align against.

An example projects.json file is available on the MiCall-Lite GitHub Repo

The file is structured as follows:

{
  "projects": {
    "ERCC": {
      "max_variants": 0,
      "description": "External RNA Controls Consortium reference; https://doi.org/10.1186/1471-2164-6-150",
      "regions": [
        {
          "coordinate_region": "ERCC-00002",
          "seed_region_names": [
            "ERCC-00002-seed"
          ]
        },
        ...
        "HCV": {
              "max_variants": 0,
              "description": "Hepatitis C virus, coding regions",
              "regions": [
                {
                  "coordinate_region": "HCV1A-H77-Core",
                  "seed_region_names": [
                    "HCV-1a",
                    "HCV-1c",
                    "HCV-1e",
                    "HCV-1g"
                  ]
                },
        ...
        "HIV": {
              "max_variants": 0,
              "description": "Human immunodeficiency virus type 1, coding regions",
              "regions": [
                {
                  "coordinate_region": "GP41",
                  "seed_region_names": [
                    "HIV1B-env-seed"
                  ]
                },
        ...
        },
    "regions": {
        "ERCC-00002": {
          "is_nucleotide": false,
          "reference": [
            "PDYFHFRPSCSQYTGVGIQTVG*SWFY*ARLAYEHYGQ*FLEE*VPRKKRTFGFQSCTVALNSDR",
            "SQKNEI*AYGRSEWHKACSVSWHKIPCLDVIHVSGNCLVMRLFPGVRAAGICCKEGR*VRPTSLP",
            "PFSLLGPVSQFSEVPPYAEDHLKRASSLFVVRRLLVWRRIARIINCAVRAASEEVCCGFALTAGR",
            "RHNDSDSVSGDLHMFAAYFRWALASFRSQNRAIIPVLIYWTRNVGPSVVRIPRRLRAVYTLLSND",
            "CTTCDHLIQNYQSSSPRSGLVRTAAFARVCGL*LFSLDGLAHIWLTRRIVAIHRFARQSVLVGVR",
            "PRDSWLNGRTTRQPVLAFYP*KKKKKKK"
          ],
          "seed_group": null
        },
        ...
    }
}

Preparing the 'micall_lite_projects_files' Tool Data Table in Galaxy

This workflow requires that the MiCall-Lite projects.json files described above are made available via a Galaxy Tool Data Table called micall_lite_projects_files. We recommend that the galaxy administrator use the data_manager_manual tool to manage that data table.

Building/Packaging

Building and packaging this code is accomplished using Apache Maven. However, you will first need to install IRIDA to your local Maven repository. The version of IRIDA you install will have to correspond to the version found in the irida.version.compiletime property in the pom.xml file of this project. Right now, this is IRIDA version 19.01.3.

Installing IRIDA to local Maven repository

To install IRIDA to your local Maven repository please do the following:

1. Clone the IRIDA project

git clone https://github.com/phac-nml/irida.git
cd irida

2. Checkout appropriate version of IRIDA

git checkout 19.01.3

3. Install IRIDA to local repository

mvn clean install -DskipTests

Building the plugin

Once you've installed IRIDA as a dependency, you can proceed to building this plugin. Please run the following commands:

cd irida-plugin-example

mvn clean package

Once complete, you should end up with a file target/irida-plugin-micall-lite-<version>.jar which can be installed as a plugin to IRIDA.

If you have previously setup IRIDA before you may copy this JAR file to /etc/irida/plugins and restart IRIDA. The plugin should now show up in the Analyses > Pipelines section of IRIDA.

You should be able to run a pipeline with this plugin and get analysis results.

Dependencies

The following dependencies are required in order to make use of this plugin.

• IRIDA >= 0.23.0
• Java >= 1.8 and Maven (for building)

6. Distribute

Once you've successfully built your plugin, you can distribute the JAR file to other IRIDA users to install in their instances.

irida-plugin-micall-lite's Issues

Trim adapters

Add fastp upstream of micall_lite to trim adapter sequence from input files.

IRIDA plugin system update required to be compatible with IRIDA 21.01

IRIDA's 21.01 version will include an update to the plugin system to version 1.1.0. All analysis pipeline pugins must implement the changes below to be compatible with IRIDA 21.01 and future versions. Changes for plugin developers are summarized below. This IRIDA version is expected to be released at the end of January 2021.

Background

IRIDA underwent some changes to how metadata is stored in its database for the 21.01 release. This change will help improve performance of IRIDA's metadata system, make metadata easier to manage in IRIDA's codebase, and fix some issues we found with how our previous structure worked with Hibernate. A writeup about this change can be found at https://github.com/phac-nml/irida/blob/development/doc/administrator/upgrades/index.md#sample-metadata-audit-record-updates. Because of this change, anywhere that metadata is accessed or written in IRIDA needed some minor changes. This includes analysis plugins that implement AnalysisSampleUpdater which has prompted this plugin system version update.

What you have to do

What this means for IRIDA plugin developers is that a change must be implemented in your plugin before IRIDA's 21.01 release in order for your plugins to work with the new version. Any plugin with an AnalysisSampleUpdater implementation will need changes to match the new structure. While we like keeping backwards compatibility, unfortunately it was not possible in this case. Updated plugins will work with 21.01 forward, but will not work with preivous versions.

We've written documentation on how you can update your plugin and the reasons for this change at https://github.com/phac-nml/irida/blob/development/doc/administrator/upgrades/index.md#plugin-version-updates. It gives a step-by-step guide on how to update most plugins. In many cases the update will require changing only 3 lines of code and generating a new release of your plugin.

If you don't update your plugin IRIDA will still successfully start but a message will be displayed in the logs that your plugin will be disabled:

29 Dec. 2020 11:20:21,827  WARN org.pf4j.AbstractPluginManager:754 - Plugin '[email protected]' requires a minimum system version of 1.0.0, and you have 1.1.0
29 Dec. 2020 11:20:21,827  WARN org.pf4j.AbstractPluginManager:851 - Plugin '/etc/irida/plugins/example-plugin-0.1.0.jar' is invalid and it will be disabled
29 Dec. 2020 11:20:21,828  INFO org.pf4j.AbstractPluginManager:801 - Plugin '[email protected]' resolved

Analysis results will still be available, but the pipeline cannot be launched.

We recommend you make this change to your plugin prior to the 21.01 release. You can do this by checking out the development version of IRIDA and basing your changes on that codebase.

What if my plugin does not implement AnalysisSampleUpdater

If your plugin does not implement a AnalysisSampleUpdater you will still need to compile a new version of your plugin against the new IRIDA version. Since the pipeline system verison has increased, all plugins will need to be compiled against the new IRIDA version.

For any questions about these changes, you can contact the IRIDA development team using one of the options at https://github.com/phac-nml/irida#contact-the-irida-team.

Allow users to select custom MiCall-Lite `projects.json` files

The MiCall-Lite tool loads reference sequences via a projects.json file. See:

https://github.com/PoonLab/MiCall-Lite/blob/master/micall/projects.json

In order to supply this to the IRIDA pipeline, they will need to be made available via a Galaxy 'Tool Data Table', then loaded as an IRIDA 'Dynamic Source' parameter.

Cannot find workflowInputId for input label sequence_reads_paired

Pipeline fails with message:

Jan 07 15:03:45 sabin.bccdc-phl.ca server[64451]: 07 Jan 2020 15:03:45,945 ERROR ca.corefacility.bioinformatics.irida.service.analysis.execution.AnalysisExecutionServiceAspect:65 - Error occured for submission: AnalysisSubmission [id=8815, name=micall-lite_20200107_SAMN11126635, submitter=dfornika, workflowId=aedd73c0-2f2a-4cb4-8f65-d6420526c119, analysisState=SUBMITTING, analysisCleanedState=NOT_CLEANED] changing to state ERROR
Jan 07 15:03:45 sabin.bccdc-phl.ca server[64451]: ca.corefacility.bioinformatics.irida.exceptions.WorkflowException: Cannot find workflowInputId for input label sequence_reads_paired
Jan 07 15:03:45 sabin.bccdc-phl.ca server[64451]: at ca.corefacility.bioinformatics.irida.pipeline.upload.galaxy.GalaxyWorkflowService.getWorkflowInputId(GalaxyWorkflowService.java:88)
...