SCM

SCM Repository

[batman] Annotation of /pkg/batman/man/batman.Rd
ViewVC logotype

Annotation of /pkg/batman/man/batman.Rd

Parent Directory Parent Directory | Revision Log Revision Log


Revision 120 - (view) (download) (as text)

1 : jie 120 \name{batman}
2 :     \alias{batman}
3 :     \title{Perform BATMAN and Plot Analysis Result}
4 :     \description{The main function, it performs metabolite and wavelet fitting to input NMR spectra,
5 :     plots fitting results, posterior distributions for relateive concentrations and peak positions,
6 :     and saves output. If the input \code{createDir = TRUE}, a folder name "runBATMAN"
7 :     will be created in specified directory, within which, two folders "BatmanInput" and
8 :     "BatmanOutput" are created. "BatmanInput" contains the input data files copied from
9 :     installed package folder "extdata". The user only needs to modify files in this
10 :     folder to change the settings for running \code{batman}. The \code{batman}
11 :     output files are saved in "BatmanOutput" subfolders.}
12 :     \usage{
13 :     batman(BrukerDataDir, txtFile, rData, createDir = TRUE,
14 :     runBATMANDir = getwd(), overwriteDir = FALSE,
15 :     figBatmanFit = TRUE, listMeta = FALSE,
16 :     figRelCon = FALSE, figMetaFit = FALSE)}
17 :     \arguments{
18 :     \item{BrukerDataDir}{The directory of the folder containing 1D Bruker spectral data files.
19 :     If not specified, spectral data will be read in from one of the following inputs prioritized
20 :     in the order: \code{txtFile}, \code{rData} and NMRdata.txt in "BatmanInput" folder.}
21 :     \item{txtFile}{The .txt file containing spectral data in the format of first column ppm, and
22 :     the second column the real part of spectrum. If not specified, spectral data will be read in
23 :     from one of the following inputs prioritized in the order: \code{BrukerDataDir},
24 :     \code{rData} and NMRdata.txt in "BatmanInput" folder.}
25 :     \item{rData}{The R data file containing spectral data in the format of first column ppm,
26 :     and the second column the real part of spectrum. If not specified, spectral data will be read in
27 :     from one of the following inputs prioritized in the order: \code{BrukerDataDir},
28 :     \code{txtFile} and NMRdata.txt in "BatmanInput" folder.}
29 :     \item{createDir}{If set TRUE, a new BATMAN work directory will be created specified by \code{runBATMANDir}.
30 :     If set FALSE, batman input will be obtained from the "extdata" folder in batman package installation directory,
31 :     and the batman output files will also be put within this folder. The default is TRUE.}
32 :     \item{runBATMANDir}{User specified BATMAN work directory, the default is current work directory.
33 :     It will only work when \code{createDir} is set TRUE.}
34 :     \item{overwriteDir}{If folder "runBATMAN" exists, set TRUE to overwrite folder. The default is FALSE.}
35 :     \item{figBatmanFit}{Plot metabolites and wavelets fit if set TRUE. The default is TRUE.}
36 :     \item{listMeta}{Individual metabolite fit will also be shown in the plot if set TRUE. The default is FALSE.}
37 :     \item{figRelCon}{Plot posterior samples of the relative concentration for fitted
38 :     metabolites with 95\% credible interval if set TRUE. The default is FALSE.}
39 :     \item{figMetaFit}{If set TRUE, plot the posterior mean of the metabolites fit with 95\%
40 :     credible interval. The default is FALSE.}
41 :     }
42 :     \value{
43 :     It returns a data list with the following objects:
44 :    
45 :     \item{specTitle}{A matrix (\eqn{2 \times n}) containing the spectrum number in its
46 :     first row and the corresponding title of the spectrum in its second row.}
47 :    
48 :     \item{sFit}{A matrix \eqn{t \times 5n} of BATMAN fit results (down sampled). For 1 spectrum, it
49 :     is a matrix with 5 columns: \deqn{[ppm, original spectrum,
50 :     metabolites fit, wavelets fit, overall fit].} The "overall fit" is the posterior mean of
51 :     the BATMAN fit results after MCMC burn in iterations. Certain numbers of burn in iterations are used
52 :     at the beginning of an MCMC run for finding a good starting point.
53 :     \eqn{n} is the number of spectra, and \eqn{t} is the number of data points in each spectrum.}
54 :    
55 :     \item{sFitHR}{A matrix \eqn{t \times 3n} of BATMAN fit results in the original resolution (without
56 :     down sample). For 1 spectrum, it is a matrix with 3 columns:
57 :     \deqn{[ppm, original spectrum, metabolites fit].} \eqn{n} is the number of spectra, and
58 :     \eqn{t} is the number of data points (without down sample) in each spectrum.}
59 :    
60 :     \item{beta}{A matrix (\eqn{m \times n}) containing the posterior means of relative
61 :     concentrations for \eqn{m} fitted metabolites and \eqn{n} spectra after burn in.}
62 :    
63 :     \item{betaSam}{A matrix (\eqn{m \times (s*n)}) containing (for the first spectrum)
64 :     \eqn{s} posterior samples of the relative concentrations in its rows.
65 :     \eqn{m} is the number of fitted metabolites. \eqn{n} is the number of spectra analyzed.
66 :     The subsequent columns contain the same format of data for the rest \eqn{n-1} spectra.}
67 :    
68 :     \item{betaCI}{A matrix (\eqn{m \times 2n}) containing the 95\% credible interval of
69 :     the relative concentrations for \eqn{m} fitted metabolites. Every pair of columns is
70 :     for one spectrum.}
71 :    
72 :     \item{metaTemp}{A matrix (\eqn{t \times (m*n)}) containing the posterior means of
73 :     \eqn{m} fitted metabolite templates in its columns (down sampled) after burn in.
74 :     \eqn{n} is the number of spectra analyzed and \eqn{t} is the number of data
75 :     points in each spectrum.}
76 :    
77 :     \item{metaTempHR}{A matrix (\eqn{t \times (m*n)}) containing the posterior means of
78 :     \eqn{m} fitted metabolite templates in its columns (without down sample) after burn in.
79 :     \eqn{n} is the number of spectra analyzed and \eqn{t} is the number of data
80 :     points (without down sample) in each spectrum.}
81 :    
82 :     \item{metaFitSam}{A matrix (\eqn{t \times (s*n)}) containing \eqn{s} posterior samples
83 :     of total metabolites fit during MCMC iterations in its columns. \eqn{n} is the number
84 :     of spectra analyzed and \eqn{t} is the number of data points in each spectrum.
85 :     The remaining \eqn{n-1} spectra metabolites fit results are saved in the same sequence
86 :     in subsequent columns.}
87 :    
88 :     \item{metaIndFitSam}{A matrix (\eqn{t \times (m*s*n)}) containing \eqn{s} posterior
89 :     samples of \eqn{m} individual metabolites fit during MCMC iterations in its columns.
90 :     \eqn{n} is the number of spectra analyzed and \eqn{t} is the number of data points
91 :     in each spectrum. The remaining \eqn{n-1} spectra results are saved
92 :     in the same sequence in subsequent columns.}
93 :    
94 :     \item{thetaSam}{A matrix (\eqn{t \times (s*n)}) containing \eqn{s} samples of wavelet
95 :     fit during MCMC iterations in its columns. \eqn{n} is the number of spectra analyzed.
96 :     The remaining \eqn{n-1} spectra wavelet fit results are saved in the same sequence
97 :     in subsequent columns.}
98 :    
99 :     \item{delta}{A matrix (\eqn{M \times n}) containing posterior means of \eqn{M}
100 :     multiplets ppm shift of fitted metabolites in its rows. \eqn{M} is the sum of all
101 :     multiplets in the fitted metabolts. Each column of the matrix
102 :     corresponds to one spectrum. If only 1 spectrum is analyzed, delta is a column vector.}
103 :    
104 :     \item{deltaSam}{A matrix (\eqn{s \times (M*n)}) containing the posterior samples
105 :     of multiplets ppm shift. Every \eqn{M} columns correspond the shift posterior samples
106 :     of \eqn{M} multiplets for one spectrum. \eqn{M} is the sum of all
107 :     multiplets in the fitted metabolts and \eqn{n} is the number of spectra analyzed.}
108 :    
109 :     \item{outputDir}{The directory of output folder with all the output result files.}
110 :     }
111 :     \seealso{
112 :     \code{\link{readBatmanOutput}, \link{batmanrerun}}
113 :     }
114 :     \examples{
115 :     library(batman)
116 :     ## Run BATMAN
117 :     bm<-batman()
118 :     100
119 :     1
120 :     ## This will create the folder "runBATMAN" in current working directory,
121 :     ## within the folder "runBATMAN", a subfolder "BatmanInput" contains all the
122 :     ## input files batman uses. Users can modify "metabolitesList.csv",
123 :     ## "batmanOptions.txt" and so on to change the settings of batman.
124 :     ## Please check "BatmanInput" for details on how to adjust input parameters.
125 :     ########################################################################
126 :     ## The following is an example of what will be displayed in R
127 :     ## and what value the user could input:
128 :     ########################################################################
129 :     ## batman...
130 :     ## Enter number of post-burn-in iterations (burn-in currently set to
131 :     ## 400 iterations):
132 :     ## 1: 100 ## user input
133 :     ##
134 :     ## Enter a number of choice from the menu below:
135 :     ##
136 :     ## 1: Include the default template of multiplets in multi_data.csv file only.
137 :     ## 2: Include the user input template of multiplets in multi_data_user.csv file only.
138 :     ## 3: Include both the above files.
139 :     ##
140 :     ## Selection: 1 ## user input
141 :     ## Loading multi_data.csv...
142 :     ## Percentage completed...
143 :     ## | | 0%
144 :     ## Size of each spectrum is 393.
145 :     ## Size of metabolite list is 22.
146 :     ## Constructing chain data structure...
147 :     ## time used is 0 seconds.
148 :     ## Running MCMC...
149 :     ## |=================================================== | 80%
150 :     ## time used for burnin is 76 seconds.
151 :     ## |==================================================================| 100%
152 :     ## time used is 95 seconds.
153 :     ## saving posteriors...
154 :     ##
155 :     ## time elapsed
156 :     ## 95.61
157 :     ## second.
158 :     ## Reading in saved data in folder
159 :     ## .../user_specified_dir/runBATMAN/BatmanOutput/07_Dec_17_19_18
160 :     ## Completed.
161 :     ########################################################################
162 :     ## Alternatively if more than 1 spectrum are included without using fixed effect
163 :     ## (in batmanOptions.txt file, set
164 :     ## "Same concentration for all spectra (fixed effect) (1/0): 0"),
165 :     ## user will be asked to input the following parameter:
166 :     ########################################################################
167 :     ## How many parallel processes (multicores) do you want to run
168 :     ## the multi-spectra analysis?
169 :     ## (Enter 1 for running them sequentially.)
170 :     ##
171 :     ## Parallel processing of multi spectra currently cannot display
172 :     ## progress bar (or any words), if you input is > 1, please be patient
173 :     ## for the results :)
174 :     ##
175 :     ## 1: 2 ## user input
176 :     ## time elapsed
177 :     ## 78.79
178 :     ## second.
179 :     ## Reading in saved data in folder
180 :     ## .../user_specified_dir/runBATMAN/BatmanOutput/07_Dec_17_35_53
181 :     ## Completed.
182 :     ########################################################################
183 :     }
184 :     \keyword{datasets}

root@r-forge.r-project.org
ViewVC Help
Powered by ViewVC 1.0.0  
Thanks to:
Vienna University of Economics and Business Powered By FusionForge