README.md 4.5 KB
Newer Older
Markus Rampp's avatar
Markus Rampp committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
# BioEM:  Bayesian inference of Electron Microscopy
# PRE-ALPHA VERSION: April 25, 2014


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

* 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:

The BioEM code compares one Model to multiple experimental  EM images.

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

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

	Command line inputs:
	  --Inputfile arg       (Mandatory) Name of input parameter file
	  --Modelfile arg       (Mandatory) Name of model file
	  --Particlesfile arg   (Mandatory) Name of paricles file
	  --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 red from maps file
	  --LoadMapDump         (Optional) Read Maps from dump instead of maps file
	  --help                (Optional) Produce help message


### OUTPUT:

* Main output file: "Output_Probabilities" with
     RefMap #(number Particle Map) Probability  #(log(P))
     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].

* (Optional) Write the probabilities for each triplet of Euler Angles (key word: WRITE_PROB_ANGLES in InputFile).

### EXAMPLE DIRECTORY:
 
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.

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

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