A deep learning based tool to automatically select the best reconstructed 3D maps within a group of maps.
git clone https://github.com/AntiMatter568/DeepMASCcurl -fsSL https://pixi.sh/install.sh | bashOr if system-wide installation is wanted (replace /path/to/shared/folder with the path to your desired installation folder):
curl -fsSL https://pixi.sh/install.sh | PIXI_HOME=/path/to/shared/folder bashcd <Your Installation Folder> # default is DeepMASC
pixi installConfigure environment for shared usage:
chmod -R 777 . # set permission to read, write and exec for all userspixi run autoselectclassIf you want to run from abitrary directory (replace /path/to/DeepMASC/repo/pixi.toml with the path to your pixi.toml file)
pixi run --no-lockfile-update --manifest-path=/path/to/DeepMASC/repo/pixi.toml autoselectclassRequired 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. (If used from a different directory other than DeepMASC repo, the paths must be absolute) -
-o, --output: Output folder name. Directory where all output files will be stored. (If used from a different directory other than DeepMASC repo, the paths must be absolute) -
-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. -
--dryrun: When enabled, performs a dry run that only prints commands without actually executing CryoREAD. Useful for testing and verification.
pixi run --no-lockfile-update --manifest-path=/path/to/DeepMASC/repo/pixi.toml autoselectclass -f /path/to/relion/project/Class3D/job052/class1.mrc /path/to/relion/project/Class3D/job052/class2.mrc /path/to/relion/project/Class3D/job052/class3.mrc -g 0,1,2 -o /path/to/output/dirgtf_relion4_run_select_class3d.py<- this is the main file to executegtf_relion4_create_select3d_data_star.pygtf_relion4_select3d.py
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.
- From RELION GUI, Choose "External", then in "External Executable" box enter
python /path/to/gtf_relion4_run_select_class3d.py. - In the "Input" tab, in "Input Particles" box, enter the path to the input data star file like
Class3D/job052/run_it025_data.star. - In the Params tab, enter
gpusin values box, then enter the gpus to use for inference like0,1,2. (required) - In the Params tab, enter other optional parameters like
debug(optional, true or false),reso(optional, Low(>5Å) or High(<5Å)),batch(optional, on modern GPU 8 and 16 works well). - In the Running tab, the "Number of threads" box should be set to 1.
- Adjust your submission to queue setting accordingly if you use a managed queue job submission system.
- Click the "Run" button.
- Once the job is finished, the results will be stored in the output job directory created by RELION.
| 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 |
Required Arguments:
-i, --input_map_path: Input MRC map file to determine the contour (If used from a different directory other than DeepMASC repo, the paths must be absolute)-o, --output_folder: Output folder to store all the files (If used from a different directory other than DeepMASC repo, the paths must be absolute)-g, --gpu_id: GPU ID to use for CryoREAD prediction. Specifies which GPU device should be used for processing.
Optional Arguments:
-p, --plot_all: Plot all components (default: False)-n, --num_components: Number of components for mixture model (default: 2)-r, --refinement_mask: Generate more fine-grained mask for refinement (default: False)-b, --batch_size: Batch size for CryoREAD prediction (default: 8)-m, --morph_radius: Radius for morphological operations (opening, closing) (default: 3)-d, --mask_diameter: The diameter of the mask in percentage to the shortest dimension of the map (from 0 to 100), set to 0 to disable (default: 95)-a, --aggressive: Use more aggressive mask cutoff when using GMM mask (default: False)-c, --cutoff_prob: The cutoff probability for the mask if using CryoREAD mask (default: 0.3)--debug: Enable debug mode (default: False)
pixi run --no-lockfile-update --manifest-path=/path/to/DeepMASC/repo/pixi.toml autocontour -i ./Class3D/job052/class1.mrc -o ./output_folder -g 0 -ppixi run --no-lockfile-update --manifest-path=/path/to/DeepMASC/repo/pixi.toml autocontour -i ./Class3D/job052/class1.mrc -o ./output_folder -g 0 -p -r -b 16- (Optional) Apply a spherical mask (diameter controlled by
--mask_diameter, default: 95% of the map's smallest dimension, set to 0 to disable) to eliminate padding skip artifacts in the corners. - Extract all intensity and gradient features from the map where the value is non-zero.
- Apply a Bayesian GMM (Gaussian Mixture Model) to classify non-zero voxels in the previous step into a specified number of components (controlled by
--num_components, default: 2) using the features. - The component with mean intensity closest to zero is labeled noise and excluded from the mask.
- (Optional) Morphological operations are applied. Closing (fills holes) followed by opening (removes isolated points) using a spherical kernel with radius controlled by
--morph_radius(default: 3 pixels, set to 0 to disable) to clean the mask. - (Optional) If aggressive masking is enabled (
--aggressive), a secondary GMM further splits the retained voxels to remove weaker signal regions. - The final binary mask is saved as "prot_mask_final.mrc", preserving original voxel dimensions and header metadata. If
--plot_allis enabled, histograms for each component will be saved. - (Optional) When
--refinement_maskis used, the mask's contour level feeds into CryoREAD's neural network for detailed protein segmentation.
| File | Description |
|---|---|
| prot_mask_final.mrc | The final binary mask output. This will be either the GMM-based mask or CryoREAD-refined mask depending on your settings |
| prot_mask.mrc | The conservative GMM-based binary mask, the same as prot_mask_final.mrc if --aggressive is not used and not using --refinement_mask |
| prot_mask_aggressive.mrc | The aggressive GMM-based binary mask, the same as prot_mask_final.mrc if --aggressive is used and not using --refinement_mask |
| {input_name}_hist_overall.png | Overall density distribution histogram showing original and masked data distributions |
| {input_name}_hist_by_components.png | Component-wise density distribution histogram (generated when using --plot_all) |
| {input_name}_revised_contour.txt | Text file containing revised contour levels (both conservative and aggressive) and masked percentage |
When using --refinement_mask, additional files are generated:
| File | Description |
|---|---|
| input_segment.mrc | Input map after preprocessing for CryoREAD |
| mask_protein.mrc | Initial protein mask from CryoREAD |
| chain_protein_prob.mrc | Protein probability map from CryoREAD |
| chain_base_prob.mrc | Base probability map from CryoREAD |
| chain_phosphate_prob.mrc | Phosphate probability map from CryoREAD |
| chain_sugar_prob.mrc | Sugar probability map from CryoREAD |
| CCC_FSC05.txt | Cross-Correlation between input map and masked volume and FSC 0.5 cutoff value from CryoREAD |
gtf_relion4_run_autocontour.py<- this is the main file to execute
-
From RELION GUI, Choose "External", then in "External Executable" box enter
python /path/to/gtf_relion4_run_autocontour.py. -
In the "Input" tab:
- In "Reference map" box, select the map file you want to generate a mask for.
-
In the "Params" tab, you can set the following parameters:
gpus: GPU IDs to use for CryoREAD prediction (required), e.g.,0or0,1plot_all: Set toTrueto generate component plots (optional)num_components: Number of components for mixture model (optional, default: 2)refinement_mask: Set toTrueto use CryoREAD for fine-grained masking (optional)batch_size: Batch size for CryoREAD prediction (optional, default: 8)morph_radius: Radius for morphological operations (optional, default: 3)mask_diameter: Diameter of spherical mask in percentage (optional, default: 95)aggressive: Set toTruefor more aggressive masking (optional)cutoff_prob: Cutoff probability for CryoREAD mask (optional, default: 0.3)debug: Set toTrueto enable debug mode (optional)
-
In the Running tab:
- Set "Number of threads" to 1
- Adjust your submission to queue settings if using a managed queue system
-
Click the "Run" button to start the job.
-
Once finished, the results will be stored in the output job directory created by RELION, containing all the output files listed in the previous section.