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 186 - (view) (download) (as text)

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