MAJIQ-CLIN

A novel tool for the identification of Mendelian disease-causing splicing variants from RNA-seq data

MAJIQ-CLIN is a Snakemake pipeline to detect alternative splicing aberrations in a given patient’s RNA-Seq sample compared to a cohort of controls. The core analysis runtime is based on Majiq-v3

Note: If you have any questions regarding the usage of MAJIQ-Clin, or errors to report, please post a message to the active user group at https://groups.google.com/g/majiq_voila and mark your question with the label “Majiq-CLIN”

Installation

MAJIQ-CLIN requires Python 3.12.

We recommend using a virtual environment for package version consistency, as below:

python3.12 -m venv env

Then activate the environment with:

source env/bin/activate

We then need to install MAJIQ V3, which is a dependency of Majiq-CLIN. Please follow the usual instructions to register and install the license file for Majiq-V3 found here: https://majiq.biociphers.org/app_download/

Finally, we install Majiq-CLIN itself:

git clone ssh://git@bitbucket.org/biociphers/majiq-clin.git
cd majiq-clin
pip install .

(we clone instead of directly installing, as the cloned repository acts as a base structure for the rest of the usage/configuration of CLIN.

Configuration

Majiq-CLIN requires a number of files set up in a structure to define the inputs and run type for the pipeline. The following figure shows the required files in brief:

../_images/CLIN_outline_figure.png

MAJIQ-CLIN takes as input the following files:

  • Annotation in GFF3 format (ex. GRCh38).

  • RNA-Seq files in BAM format (ex. aligned using STAR or other tool). These need to be sorted and indexed using SAMTools before being input to CLIN. (Similar to Majiq-v3, for disk and compute efficiency, you may provide v3 processed .sj files, instead of .bam files here. All that is needed is to name the column ‘sj’ instead of ‘bam’ in the TSV files listed next)

  • TSV files listing your RNA-Seq data, one for each group (ex. “cases” and “controls”). These should have at least a ‘prefix’ and ‘bam’ or ‘sj’ column.

  • A properly-configured YML config file (shown below with examples):

base-sg: # output path to base annotated splicegraph file

annotation: # annotation in GFF3 format

protein-coding: "resources/protein-coding.txt"

known-disease: "resources/murdock-omim.txt"

controls-alpha: # Specify two-sided quantiles over controls population (alpha / 2, 1 - alpha / 2) that can be used for evaluating outliers. (As array - 0.0 to 1.0).

controls-min-experiments: 1 # Min number of samples in controls allowed to have a variant for it to count as a pLSV

case-min-experiments: 0.75 # Thresholds per controls group. If < 1, the fraction of experiments in a group that must pass individual filters for a feature to be accepted. If greater, an absolute number. (Default: 0.75)

build-simplify-flags: "--simplify" #Flags passed directly to `majiq-build update` to specify how the splicegraph will be simplified on the basis of coverage/inclusion

nonconfounding: [] # List of variables (found in `groups` tables) that should be included in modeling steps as nonconfounding variable (excluding intercept term). (As array).

confounding: [] # List of variables (found in `build-groups` tables) that should be included in modeling steps as confounding variable (excluding intercept term). (As array).

unknown-confounders: # List number of unknown confounders to test.
  - 0
  - 1
  - 5

groups: # Define each group of interest.

  demo: resources/demo.tsv

analyses: # Define each analysis you want to run.

  demo:

    cases:

      - demo

    leave-one-out-controls: true # true or false depending on whether we want to run leave-one-out controls. If an external control is also added, CLIN will include the leave-one-out controls with the external controls.

    external-controls: (formatted same as cases). Group names to be used as controls, excluding the current case group. This is used for defining build and coverage modeling. Requires at least one item if `leave-one-out-controls` is false.

    external-compare: Specify groups (excluding leave-one-out-controls) to compare
      quantifications against. Do not specify comparisons including cases themselves (this is done by
      leave-one-out-controls). This is a list of lists.

    alpha: 0.1 # Specify two-sided quantiles over controls population and over case
      posterior (alpha / 2, 1 - alpha / 2) to use for evaluating outliers.
      Must be a single number between 0 and 1, or an object specifying
      one number each as the value for keys "case" and "controls".
      The alpha value used with controls must be an element of `controls-alpha`.

Traditionally, each of the groups of samples as TSV files are placed in the ‘resources’ directory below majiq_clin, and each potential configuration yml file is placed into the ‘config’ directory.

Running

After installing MAJIQ-CLIN and configuring your config file, test that your setup is configured correctly with a dryrun:

snakemake -n

You can then run your analysis by running:

snakemake --rerun-incomplete --configfile=config/config.yml --cores n

Where config.yml is the config file and n is the number of cores you would like to use.

This should produce results in the /results folder. Note the folders: - outliers: all genes output. These include gene-level results for all genes (.genes.tsv), splicing event, and splicing event connection results (.events.tsv and .ec.tsv). - outliers_gene_summary: summaries of outliers of different types detected in different datasets. - plot: plots showing the results in outliers_gene_summary.

Visualization

Visualization uses an updated version of VOILA able to highlight differences between patients and controls as specially colored junctions in the voila splicegraph.

To run the visualization, run:

python clin-visualize.py

You will be prompted with questions to choose the analysis and case you would like to visualize, and then voila will automatically be run locally.

Citation

The paper describing MAJIQ-CLIN algorithm is available at https://doi.org/10.1016/j.gim.2026.102628