DOCSEARCHbyAlgolia
Submit Docs

ModelAngelo

repository·main·Indexed 41 days ago

https://github.com/3dem/model-angelo

An automated tool for building atomic models from cryo-EM maps using graph neural networks. It supports model building with or without known FASTA sequences and provides tools for protein identification via HMM search and residue-level fit reporting.

Tokens
7.4K
Snippets
21
Records
27
Agent score
52%

What's inside ModelAngelo

  1. Install ModelAngelo in a shared computational environment

    main

    For cluster administrators wanting to provide ModelAngelo to multiple users:

    1. Setup Public Weights: Designate a directory (e.g., /public/model_angelo_weights) that is readable and executable by all users to store shared weights.
    2. Install with Weights: Set the TORCH_HOME environment variable to your designated path and run the install script with the --download-weights flag.
      export TORCH_HOME=/public/model_angelo_weights
cd model-angelo
source install_script.sh --download-weights
    3. Create a User Wrapper: Provide a bash script for users to easily access the environment and the tool:
      #!/bin/bash
source `which activate` model_angelo
model_angelo "$@"
    export TORCH_HOME=/public/model_angelo_weights
cd model-angelo
source install_script.sh --download-weights

  2. Perform HMM sequence search to identify proteins

    main

    If you built a model using build_no_seq, you can identify proteins by searching HMM profiles against a database (e.g., UniRef) using HHblits.

    1. Prepare Database: Download and uncompress (gunzip) a proteome FASTA file (e.g., Human or E.coli).
    2. Run Search:
      model_angelo hmm_search --i output --f PATH_TO_DB --o hmm_output

    Results:

    • HHR files: Individual HMM output files named by chain (e.g., hmm_output/A.hhr).
    • CSV Summaries:
      • output/all_hits.csv: All hits for all chains, sorted by E-value.
      • output/best_hits.csv: Unique hits containing the best hit information.
    model_angelo hmm_search --i output --f PATH_TO_DB --o hmm_output

  3. Build a model using a FASTA sequence

    main

    This is the recommended method when you have a medium-high resolution cryo-EM map (resolutions > 4 Å) and FASTA files for protein, RNA, or DNA sequences.

    Basic Protein Building:

    model_angelo build -v map.mrc -pf prot.fasta -o output

    Building with Nucleotides (RNA/DNA): If you have nucleotide sequences, provide them in separate files using -df (DNA) and -rf (RNA):

    model_angelo build -v map.mrc -pf prot.fasta -df dna.fasta -rf rna.fasta -o output

    Outputs:

    • The resulting model is an mmCIF file located in output/output.cif.
    • If you specify a custom output directory like -o testing/test/model_building, the file will be named testing/test/model_building/model_building.cif.
    • If the process halts before GNN model refinement, round 3 / 3, check output/model_angelo.log for bugs.

  4. Build a model without a FASTA sequence

    main

    Use model_angelo build_no_seq when protein sequences are unknown. This version uses a network not trained with input sequences and performs no post-processing on the built map.

    Usage:

    model_angelo build_no_seq -v map.mrc -o output

    Outputs:

    • An mmCIF model in output/output.cif.
    • HMM profile files for each chain in HMMER3 format located in output/hmm_profiles.

  5. Install ModelAngelo for personal use

    main

    To install ModelAngelo on a local machine, follow these steps:

    1. Install Conda: It is recommended to use miniconda3.
    2. Verify Conda: Run conda info to ensure it is working.
    3. Clone the repository:
      git clone https://github.com/3dem/model-angelo.git
    4. Run the installation script: Navigate to the directory and execute the script.
      cd model-angelo
source install_script.sh
    5. Activate the environment: Use the created model_angelo environment.
      conda activate model_angelo

    You can verify the installation by running model_angelo build -h.

    git clone https://github.com/3dem/model-angelo.git
cd model-angelo
source install_script.sh
conda activate model_angelo
model_angelo build -h

  6. How ModelAngelo handles intermediate results

    main

    By default, ModelAngelo cleans up after itself. After the GNN refinement rounds are complete, the command automatically deletes the following directories from the --output-dir to save space:

    • see_alpha_output (the initial C-alpha prediction results)
    • gnn_output_round_X (the results from each individual GNN refinement round)

    If you need to inspect these intermediate steps for debugging or analysis, use the --keep-intermediate-results flag.

  7. Understand hmm_search output files

    main

    The hmm_search command generates several files in the specified --output-dir (defaulting to output) to summarize search results. The filenames for HMMER outputs are derived from the chain names in your build_no_seq model.

    Output Files

    • <chain_name>.hhr: HMMER hit results for a specific chain.
    • <chain_name>.a2m: Multiple Sequence Alignment (MSA) for a specific chain.
    • all_hits.csv: A complete summary of all hits found, sorted by E-value.
    • best_hits.csv: A summary containing only the best hit (lowest E-value) for each unique target_name.

  8. Use the ModelAngelo build command to build atomic models

    main

    The build command is used to generate atomic models from cryo-EM maps. It performs an initial C-alpha prediction followed by multiple rounds of GNN (Graph Neural Network) refinement.

    Required Inputs:

    1. A cryo-EM map in .mrc format (via --volume-path or -v).
    2. A FASTA file containing potential amino acid sequences (via --protein-fasta, --fasta-path, -f, --pf, or -pf).

    Optional Inputs:

    • A mask file for the volume (--mask-path, -m).
    • RNA or DNA sequence files (--rna-fasta, --rf or --dna-fasta, --df).
    • A custom configuration file (--config-path, -c).
    • A specific compute device (--device, -d), such as cpu or a GPU number.

    Outputs:

    • A pruned mmCIF file (the primary model).
    • A raw mmCIF file (without pruning).
    • Entropy score CIF files (located in output_dir/entropy_scores/) which use the bfactor column to indicate residue identity confidence.
    # Basic usage example
python model_angelo/apps/build.py \
    --volume-path my_map.mrc \
    --fasta-path my_sequences.fasta \
    --output-dir my_model_output

  9. Use the ModelAngelo hmm_search command

    main

    The hmm_search command performs HMM searches against a provided FASTA file using the HMM profiles generated by a previous model_angelo build_no_seq run. It identifies sequence hits and produces HMMER output files (.hhr), Multiple Sequence Alignments (.a2m), and CSV summaries of the hits.

    Prerequisites

    1. A directory containing the output from model_angelo build_no_seq.
    2. A FASTA sequence file containing the sequences you wish to search against.

    Basic Usage

    To run a standard search, provide the input directory from your build step and the path to your FASTA file:

    model_angelo hmm_search --input-dir <BUILD_NO_SEQ_DIR> --fasta-path <YOUR_FASTA_FILE>
    model_angelo hmm_search --input-dir <BUILD_NO_SEQ_DIR> --fasta-path <YOUR_FASTA_FILE>

  10. Use the build_no_seq command to build atomic models without sequence information

    main

    The build_no_seq command builds atomic models from a cryo-EM map without requiring sequence information. While the resulting models are less accurate than those produced by the standard build command, this command outputs HMM profiles that can be used to search for potential sequences in your map using tools like HHBlits or HMMER.

    Requirements:

    • A cryo-EM map in .mrc format.

    Outputs:

    • An mmCIF file containing the predicted model.
    • An (experimental) mmCIF file where the bfactor column contains entropy scores for each residue (useful for identifying regions with low confidence in residue identity).
    • A hmm_profiles directory containing HMM profiles named after the chains found in the model (e.g., A_u.hmm for chain A).
    # Example usage (conceptual based on CLI arguments)
python build_no_seq.py --volume-path path/to/map.mrc --output-dir my_output --mask-path path/to/mask.mrc

  11. Run C-alpha model training via main.py

    main

    The model_angelo/c_alpha/main.py file serves as the entrypoint for training C-alpha models. It orchestrates the full training pipeline, including argument parsing, dataset loading (using CASDataset), model initialization (via get_model_from_file), optimizer setup, and distributed training via Hugging Face accelerate.

    Workflow

    1. Argument Parsing: Uses parse_arguments() to ingest training configurations.
    2. Environment Setup: Initializes an accelerate.Accelerator and sets up logging and directory structures in args.log_dir.
    3. Data Loading: Creates DataLoader instances for both training (args.dataset_list) and validation (args.valid_dataset_list) datasets. It supports data augmentation and global normalization.
    4. Model & Optimizer: Loads the model architecture from a file and initializes an AdamW optimizer with weight decay groups handled by no_weight_decay_groups.
    5. Checkpointing: If args.dont_load is false, it attempts to resume training from the latest checkpoint using checkpoint_load_latest.
    6. Distributed Training: Uses accelerator.prepare to wrap the model, optimizer, and dataloaders for distributed execution.
    7. Execution: Calls the train function to start the training loop.
    # This file is an entrypoint script intended to be run from the command line.
# Example usage (conceptual):
# python model_angelo/c_alpha/main.py --dataset_list data.txt --log_dir ./logs --batch_size 32

  12. Use the ModelAngelo refine command to refine atomic models

    main

    The refine command is used to refine an existing built model or to generate HMM profiles from poly-alanine chains.

    Requirements:

    1. A PDB/mmCIF file containing the built model (provided via --input-structure or -i).
    2. A cryo-EM map .mrc file (provided via --volume-path or -v).

    Optional Inputs/Outputs:

    • Specify an output directory with --output-dir or -o (defaults to output).
    • Generate HMM profile outputs by adding the --write-hmm-profiles or -w flag.

    Workflow:

    1. The command standardizes the input volume.
    2. It performs GNN model refinement.
    3. It produces a refined mmCIF file (named {output_dir_name}_refined.cif) and optionally HMM profiles.
    python -m model_angelo.apps.refine --input-structure model.cif --volume-path map.mrc --output-dir my_refinement_results --write-hmm-profiles