readme.md 5.01 KB
Newer Older
Maximilian Beckers's avatar
Maximilian Beckers committed
1
2
3
4
5
# False discovery rate control of cryo-EM maps

Confidence maps are complementary maps generated from cryo-EM maps by means of statistical hypothesis testing and subsequent FDR control. They allow thresholding of EM maps based on the expected amount of background noise visible at the respective threshold and thus allow rigorous error assessment of visible features in the density. 
Additional post-processing like local filtering or local amplitude scaling (LocScale) can be incorporated in the framework in order to increase the statistical power.

Maximilian Beckers's avatar
Maximilian Beckers committed
6
**For a detailed introduction, please see the file confidenceMaps_tutorial.pdf**
Maximilian Beckers's avatar
Maximilian Beckers committed
7
8
9
10
11
12

## Getting Started


### Prerequisites

Maximilian Beckers's avatar
Maximilian Beckers committed
13
The software is written in Python and itself dependent on NumPy and Matplotlib libraries. 
Maximilian Beckers's avatar
Maximilian Beckers committed
14
15
16
17


### Installing

Maximilian Beckers's avatar
Maximilian Beckers committed
18
The folder just has to be copied to your computer and can be run with a NumPy and Matplotlib capable Python installation.
Maximilian Beckers's avatar
Maximilian Beckers committed
19
20
21
22
23
24
25


## How to use

The simplest, and probably most important case, is the generation of a confidence map from a simple cryoEM density without incorporation of local resolution or atomic model information.

```
Maximilian Beckers's avatar
Maximilian Beckers committed
26
python /path/to/FDRcontrol.py -em yourMap.mrc -p thePixelSize
Maximilian Beckers's avatar
Maximilian Beckers committed
27
28
29
30
31
32
33
34
```

The output will be the corresponding confidence map ( yourMap_confidenceMap.mrc ) and a diagnostic image (diag_image.pdf), that shows three slices thorugh the map together with the regions used for noise estimation. In order to get good estimates of the background noise distribution, you should make sure that the region contains just noise and no signal of the particle.

Size of the noise estimation region can be adjusted with -w sizeOfRegion. If the default regions for noise estimation fall into noise, you can specify the center of region of your choice with -noiseBox x y z .
For example:

```
Maximilian Beckers's avatar
Maximilian Beckers committed
35
python /path/to/FDRcontrol.py -em yourMap.mrc -p 5.6 -w 20 -noiseBox 50 50 120
Maximilian Beckers's avatar
Maximilian Beckers committed
36
37
38
39
40
41
42
43
44
45
```

### Incorporation of local resolution information

A corresponding local resolution map can be supplied to the program by -locResMap yourLocalResolutionMap.mrc .

The ouput will be a locally filtered map together with the diagnostic image and the confidence map. Adjustment of the noise estimation region can be done accordingly.

Example usage:
```
Maximilian Beckers's avatar
Maximilian Beckers committed
46
python /path/to/FDRcontrol.py -em yourMap.mrc -p thePixelSize -locResMap yourLocalResolutionMap.mrc
Maximilian Beckers's avatar
Maximilian Beckers committed
47
48
49
50
51
52
53
54
55
56
57
```

### Incorporation of local amplitude scaling

LocScale inside FDRcontrol.py can be used by supplying a model map with -mm youModelMap.mrc, where the model map is generated in the LocScale workflow. For usage of parallelisation, -mpi can be specified. The window size can be specified with -w windowSize,
 and is also the size of the region used for noise estimation.
The ouput will be the locally scaled map together with the diagnostic image and the confidence map. 

Example usage:

```
Maximilian Beckers's avatar
Maximilian Beckers committed
58
python /path/to/FDRcontrol.py -em yourMap.mrc -p thePixelSize -mm yourModelMap.mrc -w 20
Maximilian Beckers's avatar
Maximilian Beckers committed
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
```

## Instructions for use and important tips

The programs require an unmasked map as input. Masking will make the noise estimation impossible.

It is critical that the regions used for noise estimation do not fall into the particle of interest. While in single particle analysis (SPA), 
the data generating process makes choice of the regions straightforward, sub-tomogram-averaged structures usually require specification of this region from the user.
The region can be identified by means of the slice-views in the diagnostic image of a first run with default parameters, and then adjust center and width of the noise region for a subsequent run. 
The axes in the diagnostic image are labelled with the voxel indices.

**Always have a look in the diagnostic image.** 

If your map contains large background areas, i.e. small particle compared to the box size, you can try to increase the sizes of the noise estimation regions with -w in 
order to get more accurate estimates of the background noise distribution.

Be aware, inclusion of either local resolution and/or atomic model information depend on the accuracy of this prior information, if the information is inaccurate, the final confidence maps will be, too.
Make sure orientations of model maps and/or local resolution maps with respect to the input EM-map are correct.

**As confidence maps are almost binary and have huge contrast, they might look quite sharp and edged. For visualization the representation can be easily improved, for example in Chimera by 
turning on surface smoothing in the Volume Viewer in Features --> Sufrace and Mesh options.**

## Demonstration with TRPV1 EMD5778

We will demonstrate the procedure using the 3.4 Angstrom structure of TRPV1 (EMD5778, Liao et al. 2013)

Download the map by clicking on: 

ftp://ftp.wwpdb.org/pub/emdb/structures/EMD-5778/other/TRPV1_sharpened_-100_3.4A.map.gz

Go into the respective directory and unzip the file. 

```
gunzip TRPV1_sharpened_-100_3.4A.map.gz
```

We are ready to generate the confidence map by

```
Maximilian Beckers's avatar
Maximilian Beckers committed
98
python /path/to/FDRcontrol.py -em TRPV1_sharpened_-100_3.4A.map -p 1.2156
Maximilian Beckers's avatar
Maximilian Beckers committed
99
100
101
```

The expected run time on normal desktop computer should be around 1-2 minutes for this example.
Maximilian Beckers's avatar
Maximilian Beckers committed
102

Maximilian Beckers's avatar
Maximilian Beckers committed
103
    
Maximilian Beckers's avatar
Maximilian Beckers committed
104
    
Maximilian Beckers's avatar
Maximilian Beckers committed
105
106
107