RosEM - Pipeline and GUI for cryoEM model refinement using rosetta and phenix

Introduction

The GUI and command-line apps provide easy access to the rosetta cryo-EM refinement protocol by Frank DiMaio et al. The pipeline automates testing of different density weights, use of reference/starting model restraints and selections.

At the moment only the FastRelax protocol based on this tutorial (https://faculty.washington.edu/dimaio/files/rosetta_density_tutorial_aug18_1.pdf) is implemented.

Installation

Install rosetta and phenix from

https://www.rosettacommons.org/software/license-and-download

https://phenix-online.org/download/

Compatibility was tested against phenix v1.21.2 and rosetta v3.14.

Installation (conda)

cd /some/directory/
git clone https://github.com/fmi-basel/RosEM.git
conda activate rosem-conda
cd RosEM
python3 -m pip install .
# GUI
rosemgui
# Commandline app
rosemcl

Make sure rosetta and phenix executables are in the PATH. If not you need to specify them manually in the GUI settings or use respective flags in the command line app.

Tested on Linux Ubuntu 18.x and MacOS BigSur

Installation (Virtualenv)

Dependencies Python>=3.10 Qt5 (v5.15)

cd /some/folder
git clone https://github.com/fmi-basel/RosEM.git
python3 -m venv rosem-env
source rosem-env/bin/activate
pip install --upgrade pip
cd RosEM
python3 -m pip install .

Usage

GUI Application

rosemgui.py

When launching the GUI for the first time, you will be prompted to create a project. Choose a folder where job output should be saved.

When the main GUI has started, hovering over input fields will show context help.

Minimum input requirement is:

• A model file [.pdb]
• A map file [.mrc]
• Effective resolution

Command line

mkdir some_jobname
cd some_jobname
rosemcl --help

Minimum input:

rosemcl map.mrc model.pdb -r 3.0

By default the pipeline will generate 5 models and select the best one based on FSC correlation.

Expected output:

<JOBID>_<JOBNAME>/
    best_model_w<weight>.pdb
    (run.sh)
    job_w<weight>
    (validation)
    <JOBID>_<JOBNAME>.log
    (submit_script)

• best_model_w<weight>.pdb - The best model for a specified density weight based on FSC
• run.sh - The command used by GUI to run the pipeline
• job_w<weight> - Folder containing rosetta_scripts instructions (.xml), individual models (.pdb), rosetta command line scripts (.sh), and rosetta logfiles (.pdb)
• validation - If validation was requested, the folder contains output from molprobity
• <JOBID>_<JOBNAME>.log - Logfile from the pipeline
• submission_script - If queue submission was used from the GUI, this file contains the submission commands

Setup of queue submission (optional)

When RosEM jobs started from the GUI are intended to be run on infrastructure with a queueing system (such as SLURM), several settings and a submission script template need to be defined.

Submission script template

An example submission script can be found in the templates folder.

The following placeholder variables are required: {{command}} This will be replaced with the actual job command generated by the GUI

{{logfile}} This will be replaced by the logfile name used by the GUI

Optional variables are:

{{mem}} Memory per task. The default is 1 GB. You can also set this directly in the template.

{{account}} Only necessary if the queueing system requires an account

The submission script template needs to be saved in the templates folder with the name submission_script.j2 or defined in the settings.

Settings

In the settings dialog the queue settings need to be defined:

queue submission command The command to submit a job to the queue, e.g. sbatch in case of SLURM

queue cancel command The command to cancel a job, e.g. scancel in case of SLURM

queue jobid regex A python regular expression to extract the jobid from the message after submitting a job, e.g. SLURM prints "Submitted batch job 360053". The regular expression \D*(\d+)\D will extract the number. This regular expression might need to be adapted in case the message is different in other queuing systems. Currently, if the queuing system doesn't print a message with a job id, tracking and cancelling of the job will not work.

Licenses

RosEM is licensed under the Apache License, Version 2.0.

Icons are from the GTK framework, licensed under GPL.

Third-party software and libraries may be governed by separate terms and conditions or license provisions. Your use of the third-party software, libraries or code is subject to any such terms and you should check that you can comply with any applicable restrictions or terms and conditions before use.

Acknowledgments

The density-guided FastRelax and B-factor refinement protocols are adapted from a tutorial by Frank DiMaio et al.

Citations

Relevant citations for the adapted protocols

Wang et al., 2016: Automated structure refinement of macromolecular assemblies from cryo-EM maps using Rosetta