README.md 5.5 KB
Newer Older
Markus Rampp's avatar
Markus Rampp committed
1
# BioEM:  Bayesian inference of Electron Microscopy
Pilar Cossio's avatar
Pilar Cossio committed
2
# 1.0 VERSION: June, 2016
Markus Rampp's avatar
Markus Rampp committed
3

4
5
6
7
8
## Build status and test coverage

[![Build status](https://gitlab.mpcdf.mpg.de/MPIBP-Hummer/BioEM/badges/master/build.svg)](https://gitlab.mpcdf.mpg.de/MPIBP-Hummer/BioEM/commits/master)
[![Code coverage](https://gitlab.mpcdf.mpg.de/MPIBP-Hummer/BioEM/badges/master/coverage.svg)](http://MPIBP-Hummer.pages.mpcdf.de/BioEM/) 

Markus Rampp's avatar
Markus Rampp committed
9
10
11
12
13
14
15
16
17

## Contributors

Pilar Cossio, David Rohr, Fabio Baruffa, Markus Rampp, Volker Lindenstruth and Gerhard Hummer

## References

* [Cossio, P and Hummer, G. J Struct Biol. 2013 Dec;184(3):427-37. doi: 10.1016/j.jsb.2013.10.006.](http://www.ncbi.nlm.nih.gov/pubmed/24161733)

18
* Cossio, P., Rohr, D., Baruffa, F., Rampp, M., Lindenstruth, V. and Hummer, G. "BioEM: GPU-accelerated computing of Bayesian inference of electron microscopy images" Comp. Phys. Comm accepted, [arXiv:1609.06634](https://arxiv.org/abs/1609.06634)
Markus Rampp's avatar
Markus Rampp committed
19

Pilar Cossio's avatar
Pilar Cossio committed
20
## Description
Markus Rampp's avatar
Markus Rampp committed
21

Pilar Cossio's avatar
Pilar Cossio committed
22
23
24
25
26
27
28
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.

Pilar Cossio's avatar
Pilar Cossio committed
29
For a detailed description of the BioEM software see the BioEM_Maunal.pdf that is provided in the Manual directory.
Markus Rampp's avatar
Markus Rampp committed
30
31
32
33
34
35
36

### Command line input & help is found by just running the compiled executable ./bioEM

      ++++++++++++ FROM COMMAND LINE +++++++++++

	Command line inputs:
	  --Modelfile arg       (Mandatory) Name of model file
Pilar Cossio's avatar
Pilar Cossio committed
37
38
39
40
	  --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
Markus Rampp's avatar
Markus Rampp committed
41
42
43
	  --ReadPDB             (Optional) If reading model file in PDB format
	  --ReadMRC             (Optional) If reading particle file in MRC format
	  --ReadMultipleMRC     (Optional) If reading Multiple MRCs
Pilar Cossio's avatar
Pilar Cossio committed
44
45
46
47
	  --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
Markus Rampp's avatar
Markus Rampp committed
48
49
	  --help                (Optional) Produce help message

Pilar Cossio's avatar
Pilar Cossio committed
50
Details for the inputfiles and formats are provided in chapters 1 and 2 of the BioEM_Manual.pdf.
Markus Rampp's avatar
Markus Rampp committed
51

Pilar Cossio's avatar
Pilar Cossio committed
52
### Output
Markus Rampp's avatar
Markus Rampp committed
53

Pilar Cossio's avatar
Pilar Cossio committed
54
* 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:
Pilar Cossio's avatar
Pilar Cossio committed
55
     
Markus Rampp's avatar
Markus Rampp committed
56
     RefMap #(number Particle Map) Probability  #(log(P))
Pilar Cossio's avatar
Pilar Cossio committed
57
     
Markus Rampp's avatar
Markus Rampp committed
58
59
60
61
     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].

Pilar Cossio's avatar
Pilar Cossio committed
62
* (Optional) Write the posterior probabilities as a function of the orientations (key word: WRITE_PROB_ANGLES in InputFile, see BioEM_Manual.pdf).
Markus Rampp's avatar
Markus Rampp committed
63

Pilar Cossio's avatar
Pilar Cossio committed
64
### Tutorial
Markus Rampp's avatar
Markus Rampp committed
65
 
Pilar Cossio's avatar
Pilar Cossio committed
66
A directory with example EM particles, models, and input files are provided in the Tutorial_BioEM directory. 
Pilar Cossio's avatar
Pilar Cossio committed
67
The tutorial is described in chapter 4 of the BioEM_Manual.pdf 
Markus Rampp's avatar
Markus Rampp committed
68
69


Pilar Cossio's avatar
Pilar Cossio committed
70
### Installation
Markus Rampp's avatar
Markus Rampp committed
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

To build and install bioEM a cmake procedure is used, for example:

```
#clone the repository
git clone ...
cd BioEM
#build the code (CPU version)
mkdir build
cd build
cmake ..
make VERBOSE=1
```

Dependencies and software requirements:

* Compiler: a modern C++ compiler which is OpenMP compliant
              and (optionally) complies with CUDAs nvcc
              (tested with Intel icpc 12-16, GCC 4.7-5.1)
    -> adapt the name of the compiler using ccmake 

    for free software see: https://gcc.gnu.org/

* MPI: the Message Passing Standard library
         (tested with Intel MPI 4.1-5.1, IBM PE 1.3-1.4)
    -> adapt the names of the MPI compiler wrappers using ccmake 

    for free software see: http://www.open-mpi.de/
          
* FFTW: a serial but fully thread-safe fftw3 installation or equivalent (tested with fftw 3.3)
     -> point environment variable $FFTW_ROOT to a FFTW3 installation or use ccmake to specify

    for free software see: http://www.fftw.org 

* BOOST

    for free software see: http://www.boost.org/

* CUDA (required to build and run the GPU version) 

    for free software see: https://developer.nvidia.com/cuda-downloads
Pilar Cossio's avatar
Pilar Cossio committed
112
113
114
115

For details on the installation chapter 1 of the BioEM_Manual.pdf. 


Pilar Cossio's avatar
Pilar Cossio committed
116
117
118
### Performance Variables

The BioEM performance variables enhance or modify the code's computational performance without modifying the numerical results.
Pilar Cossio's avatar
Pilar Cossio committed
119
They should be tuned for the specific computing node characteristics where bioEM is executed, e.g., select the number of GPUs to use, OpenMP 
Pilar Cossio's avatar
Pilar Cossio committed
120
121
threads etc. These are passed via environment variables. See chapter 3 of the BioEM_Manual.pdf for a detailed description.

Pilar Cossio's avatar
Pilar Cossio committed
122
123
124
### 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. 
Pilar Cossio's avatar
Pilar Cossio committed
125
This program is distributed in the hope that it will be useful, but without any warranty.  See License.txt for more details.