Calling MOSuite from the CLI • MOSuite

MOSuite includes an executable file called mosuite. Any user-facing function in the MOSuite R package can be called with mosuite [function] from the unix CLI. Function arguments are passed in via a JSON file. In addition to arguments used by the function, the JSON file can contain the following keys:

moo_input_rds - file path to an existing MultiOmicsDataset object in RDS format. This is required if the MOSuite function has moo as an argument (most user-facing functions do).
moo_output_rds - file path to write the result to.

Run mosuite --help to see the full CLI usage:

Usage: mosuite [function] [--json=path/to/args.json]

[function] should be the name of a function exported from MOSuite.
[--json] should specify the path to a JSON file with arguments accepted by that function. The equals sign (=) is required to separate --json from the path.

Additionally, the JSON file can contain the following keys:
  - moo_input_rds: file path to an existing MultiOmicsDataset object in RDS format. This is required if `method` has `moo` as an argument.
  - moo_output_rds: file path to write the result to.

Use `mosuite [function] --help` for more information about the associated function.

Main functions:
  mosuite create_multiOmicDataSet_from_files
  mosuite filter_counts
  mosuite clean_raw_counts
  mosuite normalize_counts
  mosuite batch_correct_counts
  mosuite diff_counts
  mosuite filter_diff

Installing the MOSuite CLI

Docker Container

We provide a docker container with the MOSuite R package and CLI installed as of v0.2.0 and later. https://hub.docker.com/r/nciccbr/mosuite

Running this container with docker or singularity is the recommend way to run MOSuite in pipelines and HPC environments.

singularity exec docker://nciccbr/mosuite:v0.2.0 bash mosuite --help
singularity exec docker://nciccbr/mosuite:v0.2.0 bash \
  R -s -e 'cat("MOSuite version:", installed.packages()["MOSuite",][["Version"]])'

Installation on a personal computer

After installing the R package, you can use system.file() to locate the mosuite executable file with R:

# remotes::install_github("CCBR/MOSuite", dependencies = TRUE)
system.file("exec", "mosuite", package = "MOSuite")
#> [1] "/home/runner/work/_temp/Library/MOSuite/exec/mosuite"

You should add this executable to your PATH environment variable.

export PATH="$PATH:/path/to/exec/mosuite"

If you’re using the MOSuite docker container, it is already included in the path.

Example end-to-end script

You can create a shell script to run the full MOSuite pipeline. This script assumes you have a directory json_args/ with JSON files to set each function’s arguments.

#!/usr/bin/env sh
set -euo pipefail

# set MOSuite options for plots
export MOO_SAVE_PLOTS=TRUE
export MOO_PLOTS_DIR=./figures
mkdir -p $MOO_PLOTS_DIR

# add mosuite executable to the path
mosuite=$(R -s -e "cat(system.file('exec','mosuite', package='MOSuite'))")
export PATH="$PATH:$(dirname $mosuite)"

mosuite create_multiOmicDataSet_from_files --json=json_args/args_create.json
mosuite clean_raw_counts --json=json_args/args_clean.json
mosuite filter_counts --json=json_args/args_filter.json
mosuite normalize_counts --json=json_args/args_norm.json
mosuite diff_counts --json=json_args/args_diff.json
mosuite filter_diff --json=json_args/args_diff_filter.json

The example script and accompanying JSON files are included in the package data. You can copy them to your working directory with R:

# copy the example script
file.copy(system.file("extdata", "example_script.sh", package = "MOSuite"), to = "./")
# copy the JSON files
file.copy(system.file("extdata", "json_args", package = "MOSuite"), to = "./", recursive = TRUE)

Then run the script from the CLI:

bash ./example_script.sh

The final multiOmicDataSet will be in moo.rds and figures from each step will be in ./figures/.

Writing JSON files

Create a JSON file with arguments for create_multiOmicDataSet_from_files(). You can use R code as below or write it by hand.

j <- list(
  feature_counts_filepath = system.file("extdata", "RSEM.genes.expected_count.all_samples.txt.gz", package = "MOSuite"),
  sample_meta_filepath = system.file("extdata", "sample_metadata.tsv.gz", package = "MOSuite"),
  moo_output_rds = "moo.rds"
)
jsonlite::write_json(j, "args_1.json")

In a unix shell, call create_multiOmicDataSet_from_files() and specify the path to the JSON file:

mosuite create_multiOmicDataSet_from_files --json=args_1.json

This is equivalent to running the following R code:

library(MOSuite)
moo <- create_multiOmicDataSet_from_files(
  feature_counts_filepath = system.file(
    "extdata",
    "RSEM.genes.expected_count.all_samples.txt.gz",
    package = "MOSuite"
  ),
  sample_meta_filepath = system.file("extdata", "sample_metadata.tsv.gz", package = "MOSuite")
)
#> Rows: 58929 Columns: 6
#> ── Column specification ────────────────────────────────────────────────────────
#> Delimiter: "\t"
#> chr (2): gene_id, GeneName
#> dbl (4): KO_S3, KO_S4, WT_S1, WT_S2
#> 
#> ℹ Use `spec()` to retrieve the full column specification for this data.
#> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
#> Rows: 4 Columns: 2
#> ── Column specification ────────────────────────────────────────────────────────
#> Delimiter: "\t"
#> chr (2): sample_id, condition
#> 
#> ℹ Use `spec()` to retrieve the full column specification for this data.
#> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
readr::write_rds(moo, "moo.rds")

You can use the moo object you just created as input to other MOSuite functions.

Create a JSON file of arguments for clean_raw_counts() with R (or write it by hand):

j <- list(
  moo_input_rds = "moo.rds",
  moo_output_rds = "moo.rds",
  save_plots = TRUE
)
jsonlite::write_json(j, "args_2.json")

Then run clean_raw_counts():

mosuite clean_raw_counts --json=args_2.json

Results are saved to moo.rds. Overwriting the same moo file is recommended to save disk space, as the multiOmicDataset object saves intermediate results within its data structure.