batman: Perform BATMAN and Plot Analysis Result

Description Usage Arguments Value See Also Examples

View source: R/batman.R

Description

The main function, it performs metabolite and wavelet fitting to input NMR spectra, plots fitting results, posterior distributions for relateive concentrations and peak positions, and saves output. If the input createDir = TRUE, a folder name "runBATMAN" will be created in specified directory, within which, two folders "BatmanInput" and "BatmanOutput" are created. "BatmanInput" contains the input data files copied from installed package folder "extdata". The user only needs to modify files in this folder to change the settings for running batman. The batman output files are saved in "BatmanOutput" subfolders.

Usage

1
2
3
4
 batman(BrukerDataDir, BrukerDataZipDir, txtFile, rData, createDir = TRUE, 
        runBATMANDir = getwd(), overwriteDir = FALSE, 
        figBatmanFit = TRUE, listMeta = FALSE, 
        figRelCon = FALSE, figMetaFit = FALSE, showPlot)

Arguments

BrukerDataDir

The directory of the folder containing 1D Bruker spectral data files. If not specified, spectral data will be read in from one of the following inputs prioritized in the order: BrukerDataZipDir, txtFile, rData and NMRdata.txt in "BatmanInput" folder.

BrukerDataZipDir

The directory of the folder containing zipped 1D Bruker spectral data files. If not specified, spectral data will be read in from one of the following inputs prioritized in the order: BrukerDataDir, txtFile, rData and NMRdata.txt in "BatmanInput" folder.

txtFile

The .txt file containing spectral data in the format of first column ppm, and the second column the real part of spectrum. If not specified, spectral data will be read in from one of the following inputs prioritized in the order: BrukerDataDir, BrukerDataZipDir, rData and NMRdata.txt in "BatmanInput" folder.

rData

The R data file containing spectral data in the format of first column ppm, and the second column the real part of spectrum. If not specified, spectral data will be read in from one of the following inputs prioritized in the order: BrukerDataDir, BrukerDataZipDir, txtFile and NMRdata.txt in "BatmanInput" folder.

createDir

If set TRUE, a new BATMAN work directory will be created specified by runBATMANDir. If set FALSE, batman input will be obtained from the "extdata" folder in batman package installation directory, and the batman output files will also be put within this folder. The default is TRUE.

runBATMANDir

User specified BATMAN work directory, the default is current work directory. It will only work when createDir is set TRUE.

overwriteDir

If folder "runBATMAN" exists, set TRUE to overwrite folder. The default is FALSE.

figBatmanFit

Plot metabolites and wavelets fit if set TRUE. The default is TRUE.

listMeta

Individual metabolite fit will also be shown in the plot if set TRUE. The default is FALSE.

figRelCon

Plot posterior samples of the relative concentration for fitted metabolites with 95% credible interval if set TRUE. The default is FALSE.

figMetaFit

If set TRUE, plot the posterior mean of the metabolites fit with 95% credible interval. The default is FALSE.

showPlot

If set FALSE, no plot will be shown on display, the pdf file(s) for the figure plot(s) will be created in output folder. If missing from input, for windows and osx operating systems, it will be set to TRUE, for the rest operating systems, it will be set to FALSE automatically.

Value

It returns a data list with the following objects:

specTitle

A matrix (2 \times n) containing the spectrum number in its first row and the corresponding title of the spectrum in its second row.

sFit

A matrix t \times 5n of BATMAN fit results (down sampled). For 1 spectrum, it is a matrix with 5 columns:

[ppm, original spectrum, metabolites fit, wavelets fit, overall fit].

The "overall fit" is the posterior mean of the BATMAN fit results after MCMC burn in iterations. Certain numbers of burn in iterations are used at the beginning of an MCMC run for finding a good starting point. n is the number of spectra, and t is the number of data points in each spectrum.

sFitHR

A matrix t \times 3n of BATMAN fit results in the original resolution (without down sample). For 1 spectrum, it is a matrix with 3 columns:

[ppm, original spectrum, metabolites fit].

n is the number of spectra, and t is the number of data points (without down sample) in each spectrum.

beta

A matrix (m \times n) containing the posterior means of relative concentrations for m fitted metabolites and n spectra after burn in.

betaSam

A matrix (m \times (s*n)) containing (for the first spectrum) s posterior samples of the relative concentrations in its rows. m is the number of fitted metabolites. n is the number of spectra analyzed. The subsequent columns contain the same format of data for the rest n-1 spectra.

betaCI

A matrix (m \times 2n) containing the 95% credible interval of the relative concentrations for m fitted metabolites. Every pair of columns is for one spectrum.

metaTemp

A matrix (t \times (m*n)) containing the posterior means of m fitted metabolite templates in its columns (down sampled) after burn in. n is the number of spectra analyzed and t is the number of data points in each spectrum.

metaTempHR

A matrix (t \times (m*n)) containing the posterior means of m fitted metabolite templates in its columns (without down sample) after burn in. n is the number of spectra analyzed and t is the number of data points (without down sample) in each spectrum.

metaFitSam

A matrix (t \times (s*n)) containing s posterior samples of total metabolites fit during MCMC iterations in its columns. n is the number of spectra analyzed and t is the number of data points in each spectrum. The remaining n-1 spectra metabolites fit results are saved in the same sequence in subsequent columns.

metaIndFitSam

A matrix (t \times (m*s*n)) containing s posterior samples of m individual metabolites fit during MCMC iterations in its columns. n is the number of spectra analyzed and t is the number of data points in each spectrum. The remaining n-1 spectra results are saved in the same sequence in subsequent columns.

thetaSam

A matrix (t \times (s*n)) containing s samples of wavelet fit during MCMC iterations in its columns. n is the number of spectra analyzed. The remaining n-1 spectra wavelet fit results are saved in the same sequence in subsequent columns.

delta

A matrix (M \times n) containing posterior means of M multiplets ppm shift of fitted metabolites in its rows. M is the sum of all multiplets in the fitted metabolts. Each column of the matrix corresponds to one spectrum. If only 1 spectrum is analyzed, delta is a column vector.

deltaSam

A matrix (s \times (M*n)) containing the posterior samples of multiplets ppm shift. Every M columns correspond the shift posterior samples of M multiplets for one spectrum. M is the sum of all multiplets in the fitted metabolts and n is the number of spectra analyzed.

outputDir

The directory of output folder with all the output result files.

See Also

readBatmanOutput, batmanrerun

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
library(batman)
## Run BATMAN
if(interactive()) bm<-batman()
## This will create the folder "runBATMAN" in current working directory, 
## within the folder "runBATMAN", a subfolder "BatmanInput" contains all the
## input files batman uses. Users can modify "metabolitesList.csv", 
## "batmanOptions.txt" and so on to change the settings of batman.
## Please check "BatmanInput" for details on how to adjust input parameters.
########################################################################
## The following is an example of what will be displayed in R 
## and what value the user could input: 
########################################################################
## batman...
## Number of burn-in iterations:  4000 
## Number of post-burn-in iterations:  100 
## 
## The template file used is
##  1: The default template of multiplets in multi_data.csv file.
## 
## Loading multi_data.csv...
## Percentage completed...
##   |                                                                  |   0%
## Size of each spectrum is 393.
## Size of metabolite list is 22.
## Constructing chain data structure...
## time used is 0 seconds.
## Running MCMC...                                                                   
##   |===================================================               |  80%
## time used for burnin is 76 seconds.                                                                         
##   |==================================================================| 100%
## time used is 95 seconds.
## saving posteriors...
##  
## time elapsed 
##   95.61 
##  second.
## Reading in saved data in folder
## .../user_specified_dir/runBATMAN/BatmanOutput/07_Dec_17_19_18
## Completed.
########################################################################
## Alternatively if more than 1 spectrum are included without using fixed effect
## (in batmanOptions.txt file, set 
## "Same concentration for all spectra (fixed effect) (1/0): 0"),  
## user will be asked to input the following parameter: 
########################################################################
## How many parallel processes (multicores) do you want to run 
## the multi-spectra analysis?
## (Enter 1 for running them sequentially.)
##
##  Parallel processing of multi spectra currently cannot display 
##  progress bar (or any words), if you input is > 1, please be patient 
##  for the results :)
##
## 1: 2   ## user input
## time elapsed 
##   78.79 
##  second.
## Reading in saved data in folder
## .../user_specified_dir/runBATMAN/BatmanOutput/07_Dec_17_35_53
## Completed.
########################################################################

Example output



batman documentation built on Jan. 25, 2018, 3:05 p.m.