School of Physics
Huazhong University of Science and Technology

Huang Laboratory


HOME    RESEARCH    PEOPLE    PUBLICATIONS    SOFTWARE    LINKS    CONTACT    Job Opening   
Welcome to
Huang Lab

About EMReady

Improving the quality and interpretability of cryo-EM maps by local and non-local deep learning

Copyright © 2022 Jiahua He, Tao Li, Sheng-You Huang and Huazhong University of Science and Technology
Released under GNU General Public License Version 3

EMReady is freely available for academic or commercial users. If you have any questions regarding EMReady, please don't hesitate to contact us via huangsy@hust.edu.cn

Reference:
He J, Li T, Huang S-Y.* Improvement of cryo-EM maps by simultaneous local and non-local deep learning. Nature Communications, 2023;14:3217. [link]

Click here to download the data supporting the findings of EMReady paper.

Download EMReady

The download link below contains the trained EMReady models and Python script for applying EMReady.

Click here to download EMReady v1.2.2

Click here to download EMReady v1.2.1

Click here to download EMReady v1.2

Click here to download EMReady v1.1

Click here to download EMReady v1.0

Release notes:
1. The memory in version 1.1 is optimized. Compared with version v1.0, the version 1.1 consumes much less memory while maintaining the same peformance.
2. The version 1.2 now supports mask input and includes the capability for inverse interpolation to ensure that the EMReady-processed map has the same voxel size as the input map.
3. We noticed that when installing the emready_env environment, the default version of setuptools installed was too high, which caused errors on some systems when using f2py to compile interp3d. We have now specified the version of setuptools in the environment.yml. version 1.2.1
4. We have optimized the compatibility of some packages in environment.yml and replaced the original interp3d.f90 with interp3d.py. This ensures that users won't miss the opportunity to explore EMReady due to configuration issues. Click here to download EMReady v1.2.2.



List of files
     EMReady.sh: the main program of EMReady
     pred.py: Python prediction program of EMReady
     frn.py: Pytorch implementation of Filter Response Normalization Layer used in EMReady
     interp3d.f90: Fortran source code for the interpolation of EM grid
     scunet.py: Pytorch implementation of 3D Swin-Conv-UNet used in EMReady
     utils.py: Python utilities used in EMReady
     interp_back.py: Python script for inverse interpolation
     model_state_dicts/:
             model_state_dicts/model_grid_size_1.0.pth: the trained EMReady model with 1.0 Angstrom grid size
             model_state_dicts/model_grid_size_0.5.pth: the trained EMReady model with 0.5 Angstrom grid size
     environment.yml: Required packages for Python virtual environment of EMReady

Install EMReady

Software requirements

Quick installation of required online packages

$ conda env create -f environment.yml
This command will create a Python conda virtual environment named "emready_env" and install all the required packages

Details of required online packages

Python (3.8.8) (https://www.python.org)
     Python package requirements:
         pytorch (1.8.1+cuda11.1) (https://pytorch.org)
         torchvision (0.9.1+cuda11.1) (https://pytorch.org)
         cudatoolkit (11.1) (https://developer.nvidia.com/cuda-toolkit)
         numpy (1.19.2) (https://www.numpy.org)
         einops (0.3.2) (https://einops.rocks/)
         mrcfile (1.3.0) (https://github.com/ccpem/mrcfile)
         timm(0.4.12) (https://github.com/rwightman/pytorch-image-models)
         tqdm (4.60.0) (https://github.com/tqdm/tqdm)

NOTE: In order to run Python scripts properly, users should properly set the variables in EMReady.sh:

     1. Set "EMReady_home" to the root directory of EMReady, for example, if EMReady is unzipped to "/home/jhe/data/EMReady", set EMReady_home="/home/jhe/data/EMReady"

     2. Set "activate" to path of conda activator, for example
activate="/home/jhe/data/anaconda3/bin/activate"

     3. Set "EMReady_env" to name of the python conda virtual environment that have all the required packages installed. An conda environment named "emready_env" will be created using the quick installation command, so EMReady_env="emready_env". If the environment is built with a different name, users should modify "EMReady_env" accordingly

If you are using interp3d.py, skip this step

In addition to online packages, the interpolation program "interp3d.f90" should be built as a python package 'interp3d' using f2py in the conda virtual environment of EMReady
$ conda activate emready_env $ f2py -c ./interp3d.f90 -m interp3d
     This command will generate an ELF file with name like "interp3d.cpython-*.so". Please keep "interp3d.cpython-*.so" with all python scripts "*.py" in the same directory. It should be noted that the version of f2py should match the version of Python of the conda environment of EMReady. Fortran compiler (e.g. gfortran, ifort, etc) is required to run f2py. For Linux systems with Debian package management (e.g. Debian, Ubuntu), gfortran can be easily installed via $ sudo apt-get install gfortran



How to Run EMReady

Usage:
$ ./EMReady.sh in_map.mrc out_map.mrc [Options]
        Required arguments:
                 in_map.mrc:   File name of input EM density map in MRC2014 format.
                 out_map.mrc:   File name of the output EMReady-processed density map.

        Options:
                -g  GPU_ID:    ID(s) of GPU devices to use. e.g. '0' for GPU #0, and '2,3,6' for GPUs #2, #3, and #6. (default: '0')
                -s STRIDE:    The step of the sliding window for cutting the input map into overlapping boxes. Its value should be an integer within [12,48]. (default: 12)
                -b BATCH_SIZE:    Number of boxes input into EMReady in one batch. (default: 10)
                -m MASK_MAP:    Input mask map in MRC2014 format. (default: None)
                -c MASK_MAP_CONTOUR:    Set the contour level of the mask. (default: 0.0)
                -p MASK_STRUCTURE:    Input structure mask files in PDB or CIF format (default: None)
                -r MASK_STRUCTURE_RADIUS:    Zone radius in angstroms (default: 4.0)
                -mo MASK_OUT_PATH:    File path of the output binary mask map. (default: None)
                --use_cpu:    Run EMReady on CPU instead of GPU.

Notes:

1. Users can specify a larger STRIDE of sliding window (default=12) to reduce the number of overlapping boxes to calculate. If users run out of memory, they may set it to a larger value. Howerver, since the size of the overlapping boxes is 48×48×48, the value of STRIDE should not exceed 48.

2. By default, EMReady will run on GPU(s). Users can adjust the BATCH_SIZE according to the VRAM of their GPU. Empirically, an NVIDIA A100 with 40 GB VRAM can afford a BATCH_SIZE of 30. Users can run EMReady on CPUs by setting --use_cpu. But this may take very long time for large density maps.

Examples

Click here to download all the examples
or download one of the examples listed in the following to test EMReady.

EMD-22216
Input density map
Output processed map

EMD-22829
Input density map
Output processed map

EMD-0257 (merged half-maps)
Input density map
Output processed map


© Lab of Biophysics and Molecular Modeling, huanglab@hust.edu.cn