Commit 41500ddb authored by Pilar Cossio's avatar Pilar Cossio
Browse files

Merge branch 'master' of https://gitlab.rzg.mpg.de/BioEM/BioEM

parents ba7d67dc 5359112d
Pipeline #4719 passed with stage
No preview for this file type
...@@ -186,10 +186,11 @@ of the BioEM theory. Therefore, it is encouraged to read refs.~\cite{CossioHumme ...@@ -186,10 +186,11 @@ of the BioEM theory. Therefore, it is encouraged to read refs.~\cite{CossioHumme
\section{Installation} \section{Installation}
\subsection{Prerequisite programs and libraries} \subsection{Prerequisite programs and libraries}
Before installation, there are several programs and libraries that should be preinstalled on the compute node. In the following, Before installation, there are several programs and libraries that should be preinstalled on the compute node.
we give a brief explanation of the mandatory, and optional prerequisite programs. {\bf PC: The following needs checking::} First check that the compiler is a modern C++ compiler which is OpenMP compliant.
In the following, we give a brief explanation of the mandatory, and optional prerequisite programs. %{\bf PC: The following needs checking::}
\subsubsection{Mandatory preinstalled libraries/programs} \subsubsection{Mandatory preinstalled libraries}
\begin{itemize} \begin{itemize}
...@@ -202,8 +203,8 @@ such as linear algebra, pseudorandom number generation, multithreading, ...@@ -202,8 +203,8 @@ such as linear algebra, pseudorandom number generation, multithreading,
image processing, and unit testing. In particular, this library is used to access and organize input-data in the BioEM code. image processing, and unit testing. In particular, this library is used to access and organize input-data in the BioEM code.
BOOST can be downloaded from www.boost.org. BOOST can be downloaded from www.boost.org.
\item {\it OpenMP:} is a programming interface that supports shared memory parallel programming. %\item {\it OpenMP:} is a programming interface that supports shared memory parallel programming.
It is normally, included in the standard GNU or Intel c++ compliers, so no downloading should be necessary. For more information see http://openmp.org/. %It is normally, included in the standard GNU or Intel c++ compliers, so no downloading should be necessary. For more information see http://openmp.org/.
\end{itemize} \end{itemize}
...@@ -325,7 +326,7 @@ standard host compiler is incompatible with CUDA)\\ ...@@ -325,7 +326,7 @@ standard host compiler is incompatible with CUDA)\\
\parbox{12cm}{ \parbox{12cm}{
{\texttt{mkdir build \&\& cd build}}}} {\texttt{mkdir build \&\& cd build}}}}
\item[--] Run CMake with the desired options and the {\it CMakeLists.txt} file {\bf PC: Not working for me in the Bio cluster where the build is in-source??} \item[--] Run CMake with the desired options and the {\it CMakeLists.txt} file {\bf PC: This is not working for me, I'm getting in-source builds?}
\fbox{% \fbox{%
\parbox{12cm}{ \parbox{12cm}{
...@@ -353,39 +354,25 @@ For a simple test, run the BioEM executable ...@@ -353,39 +354,25 @@ For a simple test, run the BioEM executable
\vspace{0.5cm} \vspace{0.5cm}
If the code runs successfully, the output on the terminal screen should be as that shown in Table \ref{tableBioEM}. If the code runs successfully, the output on the terminal screen should be as that shown in Listing \ref{tableBioEM}.
\vspace{0.5cm} \begin{lstlisting}[frame=single,basicstyle={\ttfamily\small},label={tableBioEM},caption={BioEM commandline input options.}\\ ]
Command line inputs:
\begin{table}[h] --Modelfile arg (Mandatory) Name of model file
\begin{center} --Particlesfile arg if BioEM (Mandatory) Name of particle-image file
--Inputfile arg if BioEM (Mandatory) Name of input parameter file
\begin{tabular}{l} --PrintBestCalMap arg (Optional) Only print best calculated map. NO BioEM (!)
--ReadOrientation arg (Optional) Read file name containing orientations
\fbox{% --ReadPDB (Optional) If reading model file in PDB format
\parbox{12cm}{ --ReadMRC (Optional) If reading particle file in MRC format
{\texttt{ --ReadMultipleMRC (Optional) If reading Multiple MRCs
Command line inputs:\\ --DumpMaps (Optional) Dump maps after they were read from
--Modelfile arg (Mandatory) Name of model file\\ particle-image file
--Particlesfile arg if BioEM (Mandatory) Name of particle-image file\\ --LoadMapDump (Optional) Read Maps from dump option
--Inputfile arg if BioEM (Mandatory) Name of input parameter file\\ --OutputFile arg (Optional) For changing the outputfile name
--PrintBestCalMap arg (Optional) Only print best calculated map. NO BioEM (!)\\
--ReadOrientation arg (Optional) Read file name containing orientations\\
--ReadPDB (Optional) If reading model file in PDB format\\
--ReadMRC (Optional) If reading particle file in MRC format\\
--ReadMultipleMRC (Optional) If reading Multiple MRCs\\
--DumpMaps (Optional) Dump maps after they were read from particle-image file\\
--LoadMapDump (Optional) Read Maps from dump option\\
--OutputFile arg (Optional) For changing the outputfile name\\
--help (Optional) Produce help message --help (Optional) Produce help message
}}} \end{lstlisting}
}
\end{tabular}
\end{center}
\caption{BioEM commandline input options.}
\label{tableBioEM}
\end{table}
...@@ -394,7 +381,7 @@ Command line inputs:\\ ...@@ -394,7 +381,7 @@ Command line inputs:\\
\chapter{BioEM Input} \chapter{BioEM Input}
In this chapter, we describe the BioEM input commands and keywords. BioEM has two In this chapter, we describe the BioEM input commands and keywords. BioEM has two
main sources of input: from the commandline and from the input-parameter file. In the first section, we describe each commandline item from Table \ref{tableBioEM}. main sources of input: from the commandline and from the input-parameter file. In the first section, we describe each commandline item from Listing \ref{tableBioEM}.
In the second section, we describe the keywords that should be specified in the input-parameter file. Lastly, we describe the specific formats of the model, particle-image, In the second section, we describe the keywords that should be specified in the input-parameter file. Lastly, we describe the specific formats of the model, particle-image,
and input-paramter files that are used in the BioEM software. and input-paramter files that are used in the BioEM software.
...@@ -403,7 +390,7 @@ and input-paramter files that are used in the BioEM software. ...@@ -403,7 +390,7 @@ and input-paramter files that are used in the BioEM software.
The BioEM software requires a model, a set of experimental images and a input-parameter file. The BioEM software requires a model, a set of experimental images and a input-parameter file.
The names of these files are passed to the \texttt{bioEM} executable via the commandline, as well as their format specifications. The names of these files are passed to the \texttt{bioEM} executable via the commandline, as well as their format specifications.
We now give a detailed description of the commandline input items shown in Table \ref{tableBioEM}. We now give a detailed description of the commandline input items shown in Listing \ref{tableBioEM}.
\subsection{Model file} \subsection{Model file}
\label{modfile} \label{modfile}
......
# BioEM: Bayesian inference of Electron Microscopy # BioEM: Bayesian inference of Electron Microscopy
# PRE-ALPHA VERSION: April 25, 2014 # PRE-ALPHA VERSION: June, 2016
## Contributors ## Contributors
...@@ -12,76 +12,57 @@ Pilar Cossio, David Rohr, Fabio Baruffa, Markus Rampp, Volker Lindenstruth and G ...@@ -12,76 +12,57 @@ Pilar Cossio, David Rohr, Fabio Baruffa, Markus Rampp, Volker Lindenstruth and G
* Cossio, P., Rohr, D., Baruffa, F., Rampp, M., Lindenstruth, V. and Hummer, G. "BioEM: GPU-accelerated computing of Bayesian inference of electron microscopy images" (in preparation) * Cossio, P., Rohr, D., Baruffa, F., Rampp, M., Lindenstruth, V. and Hummer, G. "BioEM: GPU-accelerated computing of Bayesian inference of electron microscopy images" (in preparation)
## DESCRIPTION: ## Description
The BioEM code compares one Model to multiple experimental EM images. The BioEM code calculates the posterior probability of a structural model given multiple experimental EM images.
The posterior is calculated by solving a multidimensional integral over many nuisance parameters that account for
the experimental factors in the image formation, such as molecular orientation and interference effects.
The BioEM software computes this integral via numerical grid sampling over a portable CPU/GPU computing platform.
By comparing the BioEM posterior probabilities it is possible to discriminate and rank structural models, allowing to characterize
the variability and dynamics of the biological system.
See the BioEM_Maunal.pdf for a detailed description of the BioEM software.
### Command line input & help is found by just running the compiled executable ./bioEM ### Command line input & help is found by just running the compiled executable ./bioEM
++++++++++++ FROM COMMAND LINE +++++++++++ ++++++++++++ FROM COMMAND LINE +++++++++++
Command line inputs: Command line inputs:
--Inputfile arg (Mandatory) Name of input parameter file
--Modelfile arg (Mandatory) Name of model file --Modelfile arg (Mandatory) Name of model file
--Particlesfile arg (Mandatory) Name of paricles file --Particlesfile arg if BioEM (Mandatory) Name of particle-image file
--Inputfile arg if BioEM (Mandatory) Name of input parameter file
--PrintBestCalMap arg (Optional) Only print best calculated map. NO BioEM (!)
--ReadOrientation arg (Optional) Read file name containing orientations
--ReadPDB (Optional) If reading model file in PDB format --ReadPDB (Optional) If reading model file in PDB format
--ReadMRC (Optional) If reading particle file in MRC format --ReadMRC (Optional) If reading particle file in MRC format
--ReadMultipleMRC (Optional) If reading Multiple MRCs --ReadMultipleMRC (Optional) If reading Multiple MRCs
--DumpMaps (Optional) Dump maps after they were red from maps file --DumpMaps (Optional) Dump maps after they were read from
--LoadMapDump (Optional) Read Maps from dump instead of maps file particle-image file
--LoadMapDump (Optional) Read Maps from dump option
--OutputFile arg (Optional) For changing the outputfile name
--help (Optional) Produce help message --help (Optional) Produce help message
Details for the inputfiles and formats are provided in chapters 1 and 2 of the BioEM_Manual.pdf.
### OUTPUT: ### Output
* Main output file: "Output_Probabilities" with * Main output file with, default name "Output_Probabilities", provides the posterior probability for each image, as well as the parameters that give a maximum value of the posterior:
RefMap #(number Particle Map) Probability #(log(P)) RefMap #(number Particle Map) Probability #(log(P))
RefMap #(number Particle Map) Maximizing Param: #(Euler Angles) #(PSF parameters) #(center displacement) RefMap #(number Particle Map) Maximizing Param: #(Euler Angles) #(PSF parameters) #(center displacement)
**Important: It is recommended to compare log(P) with respect to other Models or to Noise as in [1]. **Important: It is recommended to compare log(P) with respect to other Models or to Noise as in [1].
* (Optional) Write the probabilities for each triplet of Euler Angles (key word: WRITE_PROB_ANGLES in InputFile). * (Optional) Write the posterior probabilities as a function of the orientations (key word: WRITE_PROB_ANGLES in InputFile, see BioEM_Manual.pdf).
### EXAMPLE DIRECTORY: ### Tutorial
A directory with example EM particles, c-alpha PDB & simple Model, and the corresponding launch scripts are provided. Standard input file parameters are provided and recommened. A directory with example EM particles, models, and input files are provided in the Tutorial_BioEM directory.
The tutorial is described in chapter 4 of the BioEM_Manual.pdf
### REMARKS:
#### EXPERIMENTAL IMAGE FORMAT:
Two options are allowed for the map-particle files:
* Simple *.txt or .dat with data formated as
printf"%8d%8d%12.4f\n" where the first two columns are
the pixel indexes and the third column is the intensity.
Multiple particles are read in the same file with the
separator "PARTICLE" & Number.
-- For this case it is recommended all particles
to be normalized to zero average and unit standard deviation.
* Standard MRC particle file. If reading multiple MRCs
provide in command line
--Particlesfile FILE --ReadMRC --ReadMultipleMRC
where FILE contains the names of each mrc file to be read.
If only one MRC on command line
--Particlesfile FILEMRC --ReadMRC
where FILEMRC is the name of the single mrc file.
#### MODEL FORMAT:
* Standard PDB file: Reading only CA atoms and corresponding
residues with proper density.
* *.txt *.dat file: With format printf"%f %f %f %f %f\n",
the first three columns as the coordinates of atoms or
voxels, fourth column is the radius (\AA) and the
last column is the corresponding density.
(Useful for all atom representation or 3D EM density maps).
[1] Cossio, P and Hummer, G. J Struct Biol. 2013 Dec;184(3):427-37. doi: 10.1016/j.jsb.2013.10.006.
### Installation
## Installation
To build and install bioEM a cmake procedure is used, for example: To build and install bioEM a cmake procedure is used, for example:
...@@ -123,3 +104,17 @@ Dependencies and software requirements: ...@@ -123,3 +104,17 @@ Dependencies and software requirements:
* CUDA (required to build and run the GPU version) * CUDA (required to build and run the GPU version)
for free software see: https://developer.nvidia.com/cuda-downloads for free software see: https://developer.nvidia.com/cuda-downloads
For details on the installation chapter 1 of the BioEM_Manual.pdf.
### Performance Variables
The BioEM performance variables enhance or modify the code's computational performance without modifying the numerical results.
They should be tuned for the specific computing node characteristics where bioEM is executed, e.g., select the number of GPUs to use, OpenMP
threads etc. These are passed via environment variables. See chapter 3 of the BioEM_Manual.pdf for a detailed description.
### License
The BioEM program is a free software, under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
This program is distributed in the hope that it will be useful, but without any warranty. See License.txt for more details.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment