Minimal interface for seamlessly using omixer-rpm in R

- contains the main function rpm for module generation, and other
utility functions for working with a module database

.gitignore

@@ -0,0 +1,5 @@
+.project
+.settings
+.RData
+omixerRpm_*.tar.gz 
+*.Rout

CONTRIBUTING.md

@@ -0,0 +1,6 @@
+# General guidelines:
+
+1. Add and document a test case (in test/runitModules.R)
+2. Implement the function until the test suite has no errors or failures. Please use `make test` to run the test suite
+3. Document the function
+4. Commit the changes

DESCRIPTION

@@ -0,0 +1,9 @@
+Package: omixerRpm
+Type: Package
+Title: Metabolic module profiling of microbiome samples
+Version: 0.2.1
+Date: 2018-11-07
+Author: Youssef Darzi
+Maintainer: Youssef Darzi<[email protected]>
+Description: An R interface to the omixer-rpm for metabolic module profiling of microbiome samples
+License: GNU General Public License v3.0. The bundled omixer-rpm.jar is licensed under an Academic Non-commercial Software License Agreement, https://github.com/raeslab/omixer-rpm/blob/master/LICENSE

Makefile

@@ -0,0 +1,18 @@
+OMIXER_RPM_JAR=https://github.com/raeslab/omixer-rpm/releases/download/1.0/omixer-rpm-1.0.jar
+
+build: clean
+	R CMD build .
+
+devbuild: clean
+	wget -O inst/java/omixer-rpm.jar $(OMIXER_RPM_JAR)
+	R CMD build .
+
+clean:
+	rm -f omixerRpm_*.tar.gz TestMain.Rout
+
+install: build
+	sudo R CMD INSTALL --byte-compile omixerRpm_*.tar.gz
+
+testSuite:
+	R CMD BATCH test/TestMain.R
+	grep "^Number of" TestMain.Rout

NAMESPACE

@@ -0,0 +1 @@
+exportPattern("^[[:alpha:]]+")

R/ModuleDB.R

@@ -0,0 +1,81 @@
+ModuleDB <- setClass(
+        # Set the name for the class
+        "ModuleDB",
+
+        # Define the slots
+        slots = c(
+                directory = "character",
+                modules = "character",
+				hierarchy = "data.frame",
+				module.names = "data.frame",
+				hierarchy.file = "character",
+				module.names.file = "character"
+                ),
+
+        # Set the default values for the slots. (optional)
+        prototype = list(
+				directory = ".",
+				modules = "module.list",
+				hierarchy.file = "hierarchy.tsv",
+				module.names.file = "module.names"
+                ),
+
+        # Make a function that can test to see if the data is consistent.
+        # This is not called if you have an initialize function defined!
+        validity = function(object) {
+			# Could validate by checking files exist
+                return(TRUE)
+        }
+)
+
+# create a method to get the name fo a given module
+setGeneric(name="getNames",
+		def=function(theObject, x){
+			standardGeneric("getNames")
+		}
+)
+
+setMethod(f = "getNames",
+		signature = "ModuleDB",
+		definition = function(theObject, x) {
+			if(nrow(theObject@module.names) == 0) {
+				theObject@module.names <- read.table(
+						file.path(theObject@directory, theObject@module.names.file),
+						row.names=1,
+						sep="\t",
+						header=F, 
+						as.is=T)
+			}
+			idx <- which(rownames(theObject@module.names) == x)
+			if(length(idx) > 0 ){
+				return(theObject@module.names[idx,1])
+			}
+			return(NA)
+		}
+)
+
+
+setGeneric(name="getHierarchy",
+		def=function(theObject, x, level){
+			standardGeneric("getHierarchy")
+		}
+)
+
+setMethod(f="getHierarchy",
+		signature="ModuleDB",
+		definition=function(theObject, x, level){
+			if(nrow(theObject@hierarchy) == 0) {
+				theObject@hierarchy <- read.table(
+						file.path(theObject@directory, theObject@hierarchy.file),
+						row.names=1,
+						sep="\t",
+						header=F, 
+						as.is=T)
+			}
+			idx <- which(rownames(theObject@hierarchy) == x)
+			if(length(idx) > 0 ){
+				return(theObject@hierarchy[idx, level])	
+			}
+			return(NA)
+		}
+)

R/Modules.R

@@ -0,0 +1,29 @@
+Modules <- setClass(
+        # Set the name for the class
+        "Modules",
+
+        # Define the slots
+        slots = c(
+                coverage = "data.frame",
+                abundance = "data.frame",
+				annotation = "data.frame"
+                ),
+
+        # Set the default values for the slots. (optional)
+        prototype = list(
+				coverage = NULL,
+				abundance = NULL,
+				annotation = NULL
+                ),
+
+        # Make a function that can test to see if the data is consistent.
+        # This is not called if you have an initialize function defined!
+        validity = function(object) {
+                if(!is.null(object@coverage) && !is.null(object@abundance)) {
+                    if(!all(dim(object@coverage) == dim(object@abundance))){
+						return("Abundance and Coverage matrices are not of equal length")	
+					}
+                }
+                return(TRUE)
+        }
+)

R/loadDefaultDB.R

@@ -0,0 +1,6 @@
+loadDefaultDB <- function() {
+	gmms.db.path <- system.file("extdata", package = "omixerRpm")
+	gmms.db <- ModuleDB(directory = gmms.db.path, modules = "GMMs.v1.07.txt")
+	print("Loaded GMMs.v1.07.txt")
+	gmms.db
+}

R/rpm.R

@@ -0,0 +1,65 @@
+# x is a dataframe or a valid file path
+# Add the Description of modules as a data object
+rpm <- function(x, minimum.coverage=-1, score.estimator="median", annotation = 1, module.db = NULL, threads = 1) {
+	# link to the GMMs executable and DB
+	rpm.exec <- system.file("java", "omixer-rpm.jar", package = "omixerRpm")
+	if(is.null(module.db)) {
+		module.db.path <- system.file("extdata", package = "omixerRpm")
+		module.db <- ModuleDB(directory = module.db.path, modules = "GMMs.v1.07.txt")
+	}
+
+	# Prepare output directories
+	out.dir <- tempfile()
+	dir.create(out.dir)
+
+	# Is x a file or a data.frame
+	if(!is.character(x)) {
+		# write samples for processing with the GMMs
+		in.dir <- tempfile()
+		dir.create(in.dir)
+		input <- file.path(in.dir, "input.tsv")
+		write.table(x, input, col.names=T, row.names=F, quote=F, sep="\t")		
+	} else {
+		input <- x
+	}
+
+	# Run the module mapping 
+	command <- paste("java -jar", rpm.exec, 
+			"-c" , minimum.coverage,
+			"-s", score.estimator,
+			"-d", file.path(module.db@directory, module.db@modules),
+			"-i", input,
+			"-o", out.dir,
+			"-a", annotation,
+			"-t", threads,
+			"-e", 2) 
+	#cat(command)
+	# try-catch
+	system(command)
+	abundance <- read.table(file.path(out.dir, "modules.tsv"), sep="\t", header=TRUE)
+	coverage <- read.table(file.path(out.dir, "modules-coverage.tsv"), sep="\t", header=TRUE)
+
+	annotation.df <- NULL
+
+	if (annotation == 1){
+		# ortohology only 
+		abundance.colnames <- colnames(abundance)
+		annotation.df <- as.data.frame(abundance[, 1])
+		abundance <- as.data.frame(abundance[, -c(1)])
+		coverage <- as.data.frame(coverage[, -c(1)])
+		colnames(annotation.df) <- abundance.colnames[1]
+		colnames(abundance) <- abundance.colnames[2:length(abundance.colnames)]
+		colnames(coverage) <- abundance.colnames[2:length(abundance.colnames)]
+	} else if (annotation == 2) {
+		# orthology and taxonomy
+		abundance.colnames <- colnames(abundance)
+		annotation.df <- as.data.frame(abundance[, c(1, 2)])
+		abundance <- as.data.frame(abundance[, -c(1, 2)])
+		coverage <- as.data.frame(coverage[, -c(1, 2)])
+		colnames(annotation.df) <- abundance.colnames[1:2]
+		colnames(abundance) <- abundance.colnames[3:length(abundance.colnames)]
+		colnames(coverage) <- abundance.colnames[3:length(abundance.colnames)]
+	}
+
+	Modules(abundance=abundance, coverage=coverage, annotation=annotation.df) 
+}

README.md

@@ -0,0 +1,14 @@
+# omixer-rpmR
+An R interface to [omixer-rpm](https://github.com/raeslab/omixer-rpm), the tool for metabolic module profiling of microbiome samples
+
+#### Dependencies 
+R and Java8
+
+#### Installation
+Download the latest release from [the release page](https://github.com/omixer/omixer-rpmR/releases), then install as follows after replacing x.y.z by the correct version 
+
+<code>R CMD INSTALL omixeRpm_x.y.z.tar.gz</code>
+
+#### License
+GNU General Public License v3.0. 
+The bundled omixer-rpm.jar is licensed under an [Academic Non-commercial Software License Agreement](https://github.com/raeslab/omixer-rpm/blob/master/LICENSE)