Addition of GBMs and utility functions for switching DBs

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: omixerRpm
 Type: Package
 Title: Metabolic module profiling of microbiome samples
-Version: 0.3.0
+Version: 0.3.1
 Date: 2018-11-13
 Author: Youssef Darzi
 Maintainer: Youssef Darzi<[email protected]>

R/listDB.R

@@ -0,0 +1,5 @@
+listDB <- function() {
+	db.path <- system.file("extdata", package = "omixerRpm")
+	db.list = gsub(".txt", "", dir(db.path, pattern=".txt"))
+	db.list
+}

R/loadDB.R

@@ -0,0 +1,6 @@
+loadDB <- function(name) {
+	db.path <- system.file("extdata", package = "omixerRpm")
+	db <- ModuleDB(directory = db.path, modules = paste0(name, ".txt"), module.names.file=paste0(name, ".names"))
+	print(paste("Loaded", name))
+	db
+}

R/loadDefaultDB.R

@@ -1,6 +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 <- ModuleDB(directory = gmms.db.path, modules = "GMMs.v1.07.txt", module.names.file="GMMs.v1.07.names")
+	print("Loaded GMMs v1.07")
 	gmms.db
 }

R/rpm.R

@@ -5,8 +5,7 @@ rpm <- function(x, minimum.coverage=-1, score.estimator="median", annotation = 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")
+		module.db <- loadDefaultDB()
 	}
 
 	# Prepare output directories

README.md

@@ -17,28 +17,47 @@ Download the latest source from [the release page](https://github.com/omixer/omi
 <code>R CMD INSTALL omixer-rpmR-x.y.z.tar.gz</code>
 
 
-#### Usage example
+#### Usage
 
+##### Mapping example
 Download the example [matrix.tsv](https://github.com/omixer/omixer-rpmR/blob/master/test/matrix.tsv) ([raw link](https://raw.githubusercontent.com/omixer/omixer-rpmR/master/test/matrix.tsv)) form the test [directory](https://github.com/omixer/omixer-rpmR/blob/master/test).
 
 <pre>library(omixerRpm)
-# read a functional profile matrix into R or create it inside R
+# read a functional profile matrix into R or create it inside R. Please note that row.names should not be used while reading the matrix. 
 dat &lt;- read.table("matrix.tsv", header=T, sep="\t")
 # Run the module mapping on the loaded table.
 mods &lt;- rpm(dat, minimum.coverage=0.3, annotation = 1)
+
 # alternatively run the mapping without loading the table into R.
 mods &lt;- rpm("matrix.tsv", minimum.coverage=0.3, annotation = 1)
+
 # Load the default mapping database
 db &lt;- loadDefaultDB()
 # get the name of the first predicted module
 getNames(db, mods@annotation[1,])
 </pre>
 
 
+##### Using an alternative database, several options are available
+
+1. load one of the bundled databases. Type listDB() to check the list of available databases
+<pre>
+db &lt;- loadDB("GBMs.v1.0")
+</pre>
+
+2. load an external database. Please refer to this [module.list](https://github.com/omixer/omixer-rpmR/blob/master/inst/extdata/GMMs.v1.07.txt) and [module.names](https://github.com/omixer/omixer-rpmR/blob/master/inst/extdata/GMMs.v1.07.names) for examples
+<pre>
+db &lt;- ModuleDB(directory = "/path/to/moduledb/", modules = "module.list", module.names.file="module.names")
+</pre>
+
+#### Bundled databases
+1. Gut Brain Modules, [Valles-Colomer et al. 2019](https://www.nature.com/articles/s41564-018-0337-x), The neuroactive potential of the human gut microbiota in quality of life and depression, Nature Microbiology 2019.
+2. Gut Metabolic Modules, [Vieira-Silva et al. 2016](https://www.nature.com/articles/nmicrobiol201688), Species-function relationships shape ecological properties of the human gut microbiome, Nature Microbiology 2016.
+
 #### Citing omixer-rpmR
 omixer-rpmR was developed as part of GOmixer. If you use omixer-rpmR in your work please cite: 
 
-Youssef Darzi, Gwen Falony, Sara Silva, Jeroen Raes. [Towards biome-specific analysis of meta-omics data](https://www.nature.com/articles/ismej2015188), The ISME journal, 2015
+Youssef Darzi, Gwen Falony, Sara Silva, Jeroen Raes. [Towards biome-specific analysis of meta-omics data](https://www.nature.com/articles/ismej2015188), The ISME journal, 2015.
 
 #### License
 GNU General Public License v3.0. 

inst/extdata/GBMs.v1.0.names

@@ -0,0 +1,56 @@
+MGB001	Serotonin synthesis I
+MGB002	Serotonin synthesis II
+MGB003	Melatonin synthesis
+MGB004	Kynurenine synthesis
+MGB005	Tryptophan synthesis
+MGB006	Glutamate synthesis I
+MGB007	Glutamate synthesis II
+MGB008	Acetylcholine synthesis
+MGB009	Histamine synthesis
+MGB010	Histamine degradation
+MGB011	Cortisol degradation
+MGB012	Dopamine synthesis
+MGB013	Noradrenaline synthesis
+MGB014	Adrenaline synthesis
+MGB015	p-Cresol synthesis
+MGB016	p-Cresol degradation
+MGB017	IPA synthesis (Clostridium sporogenes pathway)
+MGB018	Kynurenine degradation
+MGB019	GABA degradation
+MGB020	GABA synthesis I
+MGB021	GABA synthesis II
+MGB022	GABA synthesis III
+MGB023	Dopamine degradation
+MGB024	DOPAC synthesis
+MGB025	Nitric oxide synthesis I (NO synthase)
+MGB026	Nitric oxide synthesis II (nitrite reductase)
+MGB027	Nitric oxide degradation I (NO dioxygenase)
+MGB028	Nitric oxide degradation II (NO reductase)
+MGB029	ClpB (ATP-dependent chaperone protein)
+MGB030	Polysaccharide A
+MGB031	17-beta-Estradiol degradation
+MGB032	Quinolinic acid synthesis
+MGB033	Quinolinic acid degradation
+MGB034	Isovaleric acid synthesis I (KADH pathway)
+MGB035	Isovaleric acid synthesis II (KADC pathway)
+MGB036	S-Adenosylmethionine (SAM) synthesis
+MGB037	Inositol synthesis
+MGB038	Inositol degradation
+MGB039	g-Hydroxybutyric acid (GHB) degradation
+MGB040	Menaquinone synthesis (vitamin K2) I
+MGB041	Menaquinone synthesis (vitamin K2) II (alternative pathway: futalosine pathway)
+MGB042	PUFAs synthesis (AA, EPA, DHA)
+MGB043	Acetate synthesis I
+MGB044	Acetate synthesis II
+MGB045	Acetate synthesis III
+MGB046	Acetate synthesis IV
+MGB047	Acetate degradation
+MGB048	Propionate synthesis I
+MGB049	Tryptophan degradation
+MGB050	Glutamate degradation I
+MGB051	Glutamate degradation II
+MGB052	Butyrate synthesis I
+MGB053	Butyrate synthesis II
+MGB054	Propionate synthesis II
+MGB055	Propionate synthesis III
+MGB056	Propionate degradation I

inst/extdata/GBMs.v1.0.txt

@@ -0,0 +1,229 @@
+MGB001	Serotonin synthesis I
+COG2509
+K01593	COG0076
+///
+MGB002	Serotonin synthesis II
+K01593	COG0076
+K00492
+///
+MGB003	Melatonin synthesis
+bactNOG26316	proNOG30191
+K00543	COG0500
+///
+MGB004	Kynurenine synthesis
+K00453	K00463	bactNOG12453	COG3483
+K01432	K07130	COG1878
+///
+MGB005	Tryptophan synthesis
+K01657,K01658	K13497	K13501	K13503
+K00766	K13497
+K01817	K13498	K13501
+K01609	K13498	K13501
+K01695,K01696	K01695,K06001
+///
+MGB006	Glutamate synthesis I
+K00261	K00262
+///
+MGB007	Glutamate synthesis II
+K00265,K00266	K00284
+///
+MGB008	Acetylcholine synthesis
+K00624	bactNOG82617	bactNOG02159
+///
+MGB009	Histamine synthesis
+K01590	TIGR00541	bactNOG05829	bactNOG16627
+///
+MGB010	Histamine degradation
+K00276	bactNOG08340	bactNOG01662
+///
+MGB011	Cortisol degradation
+COG3959
+bactNOG01844
+COG1063
+bactNOG03269
+///
+MGB012	Dopamine synthesis
+K00505	TIGR01269	bactNOG14098	bactNOG20249
+K01593	K01592	TIGR03811	TIGR03812	COG0076
+///
+MGB013	Noradrenaline synthesis
+NOG132553
+///
+MGB014	Adrenaline synthesis
+NOG133663
+///
+MGB015	p-Cresol synthesis
+K18427,K18428	K15760,K15761,K15762,K15763,K15764	K03150	bactNOG28876
+///
+MGB016	p-Cresol degradation
+K05797	K03380	K00448,K00449	TIGR02423,TIGR02422	K00448,TIGR02422	TIGR02423,K00449
+///
+MGB017	IPA synthesis (Clostridium sporogenes pathway)
+firmNOG04290
+firmNOG00626,bactNOG07881,bactNOG15341
+///
+MGB018	Kynurenine degradation
+K00486	bactNOG02592
+///
+MGB019	GABA degradation
+K07250	K14268	K00823	K13524	K00613	K16871
+///
+MGB020	GABA synthesis I
+K09470
+K09471
+K09472
+K09473
+///
+MGB021	GABA synthesis II
+K09251
+K00137
+///
+MGB022	GABA synthesis III
+K01580	bactNOG01793
+///
+MGB023	Dopamine degradation
+K01014	K00545	K00274	K00276	K13371,K13372	bactNOG08340
+///
+MGB024	DOPAC synthesis
+K00274	K00276	K13371,K13372	bactNOG08340
+K00128	K00129	COG1012
+///
+MGB025	Nitric oxide synthesis I (NO synthase)
+K00491	bactNOG12836	bactNOG51678
+///
+MGB026	Nitric oxide synthesis II (nitrite reductase)
+K00368	K15864	bactNOG10247	COG3303
+///
+MGB027	Nitric oxide degradation I (NO dioxygenase)
+K05916	bactNOG05056	bactNOG36984
+///
+MGB028	Nitric oxide degradation II (NO reductase)
+K04561,K02305	bactNOG03766,bactNOG18192	K04561,bactNOG18192	bactNOG03766,K02305
+///
+MGB029	ClpB (ATP-dependent chaperone protein)
+K03695	TIGR03346	COG0542
+///
+MGB030	Polysaccharide A
+bactNOG00014
+bactNOG18519
+bactNOG24711	bactNOG18630	bactNOG31116
+///
+MGB031	17-beta-Estradiol degradation
+COG0300	K07124
+///
+MGB032	Quinolinic acid synthesis
+K03517,K00278	TIGR00550,TIGR00551	bactNOG02239,COG0029	K03517,TIGR00551	K03517,COG0029	TIGR00550,K00278	TIGR00550,COG0029	bactNOG02239,K00278	bactNOG02239,TIGR00551
+///
+MGB033	Quinolinic acid degradation
+K00767	TIGR00078	bactNOG00441
+K00969	bactNOG30464	bactNOG69335
+K01916	K01950	TIGR00552	COG0171
+///
+MGB034	Isovaleric acid synthesis I (KADH pathway)
+K00826	TIGR01122	TIGR01123	COG0115
+K00166,K00167	K11381
+K09699
+K00382	TIGR01350
+K01073	K10806	bactNOG27043
+///
+MGB035	Isovaleric acid synthesis II (KADC pathway)
+K00826	TIGR01122	TIGR01123	COG0115
+K01568	COG3961
+K00128	bactNOG00852
+///
+MGB036	S-Adenosylmethionine (SAM) synthesis
+K00789	TIGR01034	bactNOG02937
+///
+MGB037	Inositol synthesis
+K01858	bactNOG06811
+K01092	K18649	COG0483
+///
+MGB038	Inositol degradation
+K00010	TIGR04380	bactNOG07153
+///
+MGB039	g-Hydroxybutyric acid (GHB) degradation
+K00043	K08318	K18120	bactNOG10565
+///
+MGB040	Menaquinone synthesis (vitamin K2) I
+K01851	K02361	K02552	K04781
+K02551
+K08680
+K02549
+K01911
+K01661
+K12073	K19222
+K02523	K00805
+K02548
+K03183
+///
+MGB041	Menaquinone synthesis (vitamin K2) II (alternative pathway: futalosine pathway)
+K11782
+K11783
+K11784
+K11785
+K02548
+K03183
+///
+MGB042	PUFAs synthesis (AA, EPA, DHA)
+bactNOG04578,bactNOG62245,bactNOG02194,bactNOG48307	COG3321,bactNOG02194,bactNOG48307
+///
+MGB043	Acetate synthesis I
+K00656	K00169,K00170,K00171,K00172	K03737
+K00625	K13788	K15024
+K00925
+///
+MGB044	Acetate synthesis II
+K00656	K00169,K00170,K00171,K00172	K03737
+K01905
+///
+MGB045	Acetate synthesis III
+K00656	K00169,K00170,K00171,K00172	K03737
+K18118
+///
+MGB046	Acetate synthesis IV
+K01568
+K14519
+///
+MGB047	Acetate degradation
+K01895	bactNOG00947	bactNOG01259
+///
+MGB048	Propionate synthesis I
+K13923
+K00932	K19697
+///
+MGB049	Tryptophan degradation
+K01667	TIGR02617	bactNOG02881
+///
+MGB050	Glutamate degradation I
+K00260	K15371	K00261
+K00109
+K01039,K01040
+K01615
+///
+MGB051	Glutamate degradation II
+K01846,K19268
+K04835
+///
+MGB052	Butyrate synthesis I
+K00248
+K00634
+K00929
+///
+MGB053	Butyrate synthesis II
+K00248
+K01034,K01035	K19709
+///
+MGB054	Propionate synthesis II
+K01026
+///
+MGB055	Propionate synthesis III
+K01847	K01849,K01848	K11942
+K05606
+K03416,K17489,K17490
+///
+MGB056	Propionate degradation I
+K01908
+K01659
+K01720
+K01682
+K03417