README.md 6.4 KB
Newer Older
Markus Rampp's avatar
Markus Rampp committed
1
# BioEM:  Bayesian inference of Electron Microscopy
2
# 2.1 VERSION: July, 2019
Markus Rampp's avatar
Markus Rampp committed
3

4
5
## Build status and test coverage

6
7
[![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?job=total_coverage)](http://MPIBP-Hummer.pages.mpcdf.de/BioEM/)
Luka Stanisic's avatar
Luka Stanisic committed
8
[![Doc](https://readthedocs.org/projects/bioem/badge/)](http://bioem.readthedocs.io)
Luka Stanisic's avatar
Luka Stanisic committed
9
[![License: GPL v3][license-badge]](License.txt)
10

Markus Rampp's avatar
Markus Rampp committed
11
12
13

## Contributors

Luka Stanisic's avatar
Luka Stanisic committed
14
Pilar Cossio, David Rohr, Fabio Baruffa, Markus Rampp, Luka Stanisic, Volker Lindenstruth and Gerhard Hummer
Markus Rampp's avatar
Markus Rampp committed
15
16
17
18
19

## 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)

20
* Cossio, P., Rohr, D., Baruffa, F., Rampp, M., Lindenstruth, V. and Hummer, G. "BioEM: GPU-accelerated computing of Bayesian inference of electron microscopy images"  [Computer Physics Communications, 210C, 163-171 (2017)](http://dx.doi.org/10.1016/j.cpc.2016.09.014), [arXiv:1609.06634](https://arxiv.org/abs/1609.06634)
Markus Rampp's avatar
Markus Rampp committed
21

Pilar Cossio's avatar
Pilar Cossio committed
22
## Description
Markus Rampp's avatar
Markus Rampp committed
23

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

31
For a detailed description of the BioEM software see the [BioEM documentation](http://bioem.readthedocs.io), also provided in the doc/ directory.
Markus Rampp's avatar
Markus Rampp committed
32
33
34
35
36
37

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

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

	Command line inputs:
Luka Stanisic's avatar
Luka Stanisic committed
38
39
40
	  --Modelfile       arg (Mandatory) Name of model file
	  --Particlesfile   arg (Mandatory) Name of particle-image file
	  --Inputfile       arg (Mandatory) Name of input parameter file
Pilar Cossio's avatar
Pilar Cossio committed
41
	  --ReadOrientation arg (Optional) Read file name containing orientations
Markus Rampp's avatar
Markus Rampp committed
42
	  --ReadPDB             (Optional) If reading model file in PDB format
43
	  --ReadModelMRC        (Optional) If reading model file in MRC format
Markus Rampp's avatar
Markus Rampp committed
44
	  --ReadMRC             (Optional) If reading particle file in MRC format
45
	  --ReadMultipleMRC     (Optional) If reading multiple MRCs
Luka Stanisic's avatar
Luka Stanisic committed
46
	  --DumpMaps            (Optional) Dump maps after they were read from particle-image file
Pilar Cossio's avatar
Pilar Cossio committed
47
	  --LoadMapDump         (Optional) Read Maps from dump option
48
49
50
	  --DumpModel           (Optional) Dump model after it was read from model file
	  --LoadModelDump       (Optional) Read model from dump option
	  --PrintCOORDREAD      (Optional) Print model coordinates
Luka Stanisic's avatar
Luka Stanisic committed
51
	  --OutputFile      arg (Optional) For changing the outputfile name
Markus Rampp's avatar
Markus Rampp committed
52
53
	  --help                (Optional) Produce help message

54
Details for the inputfiles and formats are provided in sections [1](http://bioem.readthedocs.io/en/latest/index.html#the-bioem-software) and [2](http://bioem.readthedocs.io/en/latest/index.html#bioem-input) of the [BioEM documentation](http://bioem.readthedocs.io).
Markus Rampp's avatar
Markus Rampp committed
55

Pilar Cossio's avatar
Pilar Cossio committed
56
### Output
Markus Rampp's avatar
Markus Rampp committed
57

Pilar Cossio's avatar
Pilar Cossio committed
58
* 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:
59

Markus Rampp's avatar
Markus Rampp committed
60
     RefMap #(number Particle Map) Probability  #(log(P))
61

Markus Rampp's avatar
Markus Rampp committed
62
63
64
65
     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].

66
* (Optional) Write the posterior probabilities as a function of the orientations (key word: WRITE_PROB_ANGLES in InputFile, see [documentation](http://bioem.readthedocs.io/en/latest/index.html#std:inpar-WRITE_PROB_ANGLES)).
Markus Rampp's avatar
Markus Rampp committed
67

Pilar Cossio's avatar
Pilar Cossio committed
68
### Tutorial
69
70

A directory with example EM particles, models, and input files are provided in the Tutorial_BioEM directory of the [BioEM-tutorials subproject](https://github.com/bio-phys/BioEM-tutorials).
71
The tutorial is described in [section 4 of the BioEM documentation](http://bioem.readthedocs.io/en/latest/index.html#tutorial). 
Markus Rampp's avatar
Markus Rampp committed
72
73


Pilar Cossio's avatar
Pilar Cossio committed
74
### Installation
Markus Rampp's avatar
Markus Rampp committed
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

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
92
93
94
       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
Markus Rampp's avatar
Markus Rampp committed
95
96
97
98

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

* MPI: the Message Passing Standard library
99
100
       (tested with Intel MPI 4.1-5.1, IBM PE 1.3-1.4)
    -> adapt the names of the MPI compiler wrappers using ccmake
Markus Rampp's avatar
Markus Rampp committed
101
102

    for free software see: http://www.open-mpi.de/
103

Markus Rampp's avatar
Markus Rampp committed
104
105
106
* 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

107
    for free software see: http://www.fftw.org
Markus Rampp's avatar
Markus Rampp committed
108

109
* CUDA (required to build and run the GPU version)
Markus Rampp's avatar
Markus Rampp committed
110
111

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

113
For details on the installation [section 1 of the BioEM documentation](http://bioem.readthedocs.io/en/latest/index.html#the-bioem-software).
Pilar Cossio's avatar
Pilar Cossio committed
114
115


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 
120
threads etc. These are passed via environment variables. See [section 4 of the BioEM documentation](http://bioem.readthedocs.io/en/latest/index.html#performance) for a detailed description.
Pilar Cossio's avatar
Pilar Cossio committed
121

122
### License
Pilar Cossio's avatar
Pilar Cossio committed
123
124

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.
Luka Stanisic's avatar
Luka Stanisic committed
126
127

[license-badge]: https://img.shields.io/badge/License-GPL%20v3-blue.svg