Job: DeepEMhancer (Wrapper)

Overview of the DeepEMhancer Wrapper in CryoSPARC.

Description

This job is a wrapper for DeepEMhancer, a deep learning model trained to perform masking-like and sharpening-like postprocessing on cryo-EM maps [1].

DeepEMhancer License

Structura Biotechnology Inc. and CryoSPARC do not license DeepEMhancer nor distribute DeepEMhancer binaries. Please ensure you have your own copy of DeepEMhancer licensed and installed under the terms of its Apache License 2.0.

Installation

For the following instructions, do not use the Anaconda Python that is installed by CryoSPARC. This installation is destroyed and recreated with CryoSPARC updates, so new environments created by it will be erased and any changes made to it may break other CryoSPARC jobs.

DeepEMhancer has dependencies on other python packages outside of what CryoSPARC provides. In order to install DeepEMhancer, you must create a conda environment using a python installation separate from the CryoSPARC python installation, and use that environment to install dependencies.

Install deepEMhancer using Anaconda or Miniconda, from source or Anaconda cloud, following instructions in the deepEMhancer repository:https://github.com/rsanchezgarc/deepEMhancer

Important considerations for Master/Worker or Cluster installations: The path to the Anaconda installation on the machine hosting cryosparc_master must exactly match the path on machines hosting cryosparc_worker The Anaconda installation directory must be accessible by the CryoSPARC Linux user account with the required permissions for executing the deepemhancer script.

Finding the executable path

With deepEMhancer installed and its Anaconda environment active in the current shell, run

which deepemhancer

to find the full path to the deepEMhancer script. It should be similar to this:

/home/cryosparcuser/anaconda3/envs/deepEMhancer_env/bin/deepemhancer

When running the CryoSPARC wrapper, input this as the value for the ‘Path to deepEMhancer executable’ parameter.

(Optional) Create a shell script

The CryoSPARC and deepEMhancer environments and dependencies may conflict. As a workaround, you may need to wrap deepEMhancer in a shell script that deactivates the CryoSPARC environment and activates the deepEMhancer one.

Create a deepemhancer.sh file in a well known location, such as the home directory (e.g., ~/deepemhancer.sh). The file should contain the following, making the noted substitutions:

#!/usr/bin/env bash
if command -v conda > /dev/null 2>&1; then
conda deactivate > /dev/null 2>&1 || true  # ignore any errors
conda deactivate > /dev/null 2>&1 || true  # ignore any errors
fi
unset _CE_CONDA
unset CONDA_DEFAULT_ENV
unset CONDA_EXE
unset CONDA_PREFIX
unset CONDA_PROMPT_MODIFIER
unset CONDA_PYTHON_EXE
unset CONDA_SHLVL
unset PYTHONPATH
unset LD_PRELOAD
unset LD_LIBRARY_PATH

source $HOME/anaconda3/etc/profile.d/conda.sh
conda activate deepEMhancer_env
exec deepemhancer $@
  • Replace $HOME/anaconda3 on line 17 with the path to your Anaconda installation.

Make this file executable by the CryoSPARC user from the command line

chmod +x deepemhancer.sh

Then, when running the CryoSPARC wrapper, input the full path to deepemhancer.sh as the value for the ‘Path to deepEMhancer executable’ parameter. This file needs to be accessible at the same path from both the master and worker nodes.

(Optional) Set DeepEMhancer executable path as project-level default parameter

To avoid having to locate and set the executable path when building every DeepEMhancer job, in v4.1 onwards you can set a project-level default that will apply to all newly created DeepEMhancer jobs.

Navigate to the projects view, select a project and choose the DeepEMhancer executable path under the 'Project Level Parameters' module within the sidebar details panel:

Inputs

  • Volume map

    • half maps (map_half_A and map_half_B) or full map (map), as specified by the Use half maps parameter

  • Input mask (optional)

    • used to calculate the noise mean and standard deviation if the Normalization mode parameter is 1: Noise statistics, or provided as a binary mask if the normalization parameter is 2: Binary Mask

Outputs

  • Sharpened volume map (map_sharp)

Common Parameters

  • Path to deepEMhancer executable: full path to the deepEMhancer script, for example /home/cryosparcuser/anaconda3/envs/deepEMhancer_env/bin/deepemhancer

  • Path to deepEMhancer models: full path to where the deepEMhancer pretrained models were installed, for example /home/cryosparcuser/.local/share/deepEMhancerModels/production_checkpoints

For details on the other processing parameters, see the deepEMhancer repository, or the help command (deepemhancer -h with the Anaconda environment activated)

Next Steps

Downloading and viewing the postprocessed map in a software such as UCSF Chimera, or in CryoSPARC’s built in volume viewer.

References

[1] R. Sanchez-Garcia, J. Gomez-Blanco, A. Cuervo et al., *“*DeepEMhancer: a deep learning solution for cryo-EM volume post-processing”, Communications Biology, vol. 4, no. 874, 2021. Available: 10.1038/s42003-021-02399-1.

Last updated