Skip to content

README_AutoSelect3D.md

Latest commit

 

History

History
175 lines (114 loc) · 8.59 KB

README_AutoSelect3D.md

File metadata and controls

175 lines (114 loc) · 8.59 KB

AutoSelect3D

AutoSelect3D automatically selects the best reconstructed 3D maps within a group of maps using deep learning.

Standalone Usage

Details

Basic Usage

conda activate DeepMASC
PYTHONNOUSERSITE=1 python main.py

Alternative: Using Direct Python Path (No Activation Required)

You can also run DeepMASC without activating the environment by using the direct path to the conda environment's Python interpreter:

# Find your conda/mamba environment path
conda info --envs
# OR if using mamba:
mamba info --envs

# Use the direct Python path (replace <CONDA_PATH> with your actual conda installation path)
<CONDA_PATH>/envs/DeepMASC/bin/python main.py

For example:

# Common conda paths:
# Miniconda: ~/miniconda3/envs/DeepMASC/bin/python main.py
# Miniforge: ~/miniforge3/envs/DeepMASC/bin/python main.py
# System conda: /opt/conda/envs/DeepMASC/bin/python main.py

~/miniconda3/envs/DeepMASC/bin/python main.py -f examples/Class3D/job016/run_it025_class001.mrc -g 0 -o output_test

Alternative: Using Module Wrapper (Recommended)

If you have installed the DeepMASC module system (see module/README.md), you can use the convenient wrapper commands:

# Load the module
module load deepmasc

# Run AutoSelect3D using the wrapper
deepmasc -f examples/Class3D/job016/run_it025_class*.mrc -g 0 -o output

# No need to activate conda or specify full paths!

Benefits:

  • No need to activate conda environment
  • Clean, short commands
  • Works from any directory

For installation instructions, see module/INSTALL.md.

Arguments

Required Arguments:

  • -f, --files: List of input mrc files. Accepts multiple files separated by spaces. These are the MRC files that will be processed and selected.

  • -o, --output: Output folder name. Directory where all output files will be stored.

  • -g, --gpus: GPU ID to use for CryoREAD prediction. Specifies which GPU device should be used for processing. Multiple GPU IDs can be provided using a comma-separated list.

Optional Arguments:

  • --debug: Enable debug mode to generate full output (default: False). When enabled, copy the full cryoREAD output to the output directory for debugging.

  • -r, --reso: Resolution setting to choose the deep learning model (default: "Low", options are "Low" (>5Å) or "High" (<5Å)). Determines which model checkpoint will be used based on the desired resolution.

  • -b, --batch: Batch size to use for CryoREAD prediction. Controls how many boxes are processed simultaneously during the prediction phase.

  • --resolution_threshold: Resolution threshold in Angstroms for filtering maps (default: 30.0). Maps with FSC 0.5 resolution greater than this threshold will be excluded from the final results. This filtering is applied after CryoREAD processing.

  • --dryrun: When enabled, performs a dry run that only prints commands without actually executing CryoREAD. Useful for testing and verification.

Examples

PYTHONNOUSERSITE=1 python main.py -f examples/Class3D/job016/run_it025_class???.mrc -g 0 -o output_autoselectclass

Using your own data:

PYTHONNOUSERSITE=1 python main.py -f /path/to/your/class1.mrc /path/to/your/class2.mrc /path/to/your/class3.mrc -g 0,1,2 -o /path/to/output/dir

Using custom resolution threshold:

# Only keep maps with FSC 0.5 resolution ≤ 25 Å
PYTHONNOUSERSITE=1 python main.py -f examples/Class3D/job016/run_it025_class???.mrc -g 0 -o output_autoselectclass --resolution_threshold 25.0

RELION GUI Integration

Details

Files

There are three files associated with RELION integration of AutoSelect3D:

  • gtf_relion4_run_select_class3d.py <- this is the main file to execute
  • gtf_relion4_create_select3d_data_star.py
  • gtf_relion4_select3d.py

Arguments

Required Arguments:

  • -i, --input, --in_parts: Input particle star file path (relative). This star file should come from RELION InitialModel/Class3D run and is automatically generated by RELION.

  • -o, --output: Output job directory path (relative). This directory is automatically generated by RELION and will store all output files.

  • -g, --gpus: GPU ID to use for CryoREAD prediction. Specifies which GPU device should be used for processing. Multiple GPU IDs can be provided using a comma-separated list.

Optional Arguments:

  • --debug: Enable debug mode to generate full output (default: False). When enabled, copy the full cryoREAD output to the output directory for debugging.

  • -r, --reso: Resolution setting to choose the deep learning model (default: "Low", options are "Low" (>5Å) or "High" (<5Å)). Determines which model checkpoint will be used based on the desired resolution.

  • -b, --batch: Batch size to use for CryoREAD prediction. Controls how many boxes are processed simultaneously during the prediction phase.

  • --resolution_threshold: Resolution threshold in Angstroms for filtering maps (default: 30.0). Maps with estimated resolution greater than this threshold will be excluded before CryoREAD processing. This helps avoid processing low-quality maps.

RELION GUI Setup Instructions

Note: If you have installed the DeepMASC module system (see module/README.md), you can use the convenient wrapper commands instead of full Python paths:

  • Use deepmasc-relion-select instead of python /path/to/gtf_relion4_run_select_class3d.py
  • No need to activate conda or specify full paths!

Traditional Setup (without module system):

  1. From RELION GUI, Choose "External", then in "External Executable" box enter:

    • External Executable: python /path/to/gtf_relion4_run_select_class3d.py

  2. In the "Input" tab:

    • In "Input particles" box, enter the path to the input data star file like examples/Class3D/job016/run_it025_data.star (using the provided example) or your own Class3D/jobXXX/run_it025_data.star.

  3. In the "Params" tab, you can set the following parameters:

    • gpus: GPU IDs to use for CryoREAD prediction (required), e.g., 0 or 0,1,2
    • debug: Set to True to enable debug mode (optional)
    • reso: Resolution setting (optional, Low(>5Å) or High(<5Å))
    • batch: Batch size for CryoREAD prediction (optional, on modern GPU 8 and 16 works well)
    • resolution_threshold: Resolution threshold in Angstroms for filtering maps (optional, default: 30.0)

  4. In the "Running" tab:

    • Set "Number of threads" to 1
    • Adjust your submission to queue settings if using a managed queue system

  5. Click the "Run" button to start the job.

  6. Once finished, the results will be stored in the output job directory created by RELION.

List of Output Files

Details
File Description
{map_name}_CCC_FSC05.txt The first line is Real space CCC between CryoREAD prediction probabilities and input map, the second line is FSC 0.5 cutoff between the two maps
{map_name}_chain_base_prob.mrc, {map_name}_chain_phosphate_prob.mrc, {map_name}_chain_sugar_prob.mrc, {map_name}_chain_protein_prob.mrc The predicted probabilities for nitrogenous bases, phosphate backbone, sugar ring, and protein
selected_model_map.mrc The selected map based on maximum CCC criteria
{map_name}_mask_protein.mrc The generated protein mask based on a custom cutoff value on protein probability
{map_name}_segment.mrc The resampled and cropped map used as input for CryoREAD