anvi-gen-structure-database
Table of Contents
Creates a database of protein structures. Predict protein structures for the genes of a contigs database or a pangenome using either template-based homology modelling (MODELLER) or AlphaFold2 (ColabFold), or import pre-computed PDB structures you already have..
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
contigs-db 
pan-db genomes-storage-db
Can use
pdb-db genes-of-interest-txt 
external-structures
Provides
Usage
This program creates a structure-db by predicting the 3D structures of proteins encoded by genes in your contigs-db. You can choose between two prediction engines with the --engine flag: (a) modeller (the default), which uses template-based homology modelling with DIAMOND and MODELLER, or (b) colabfold, which uses AlphaFold2 via ColabFold. Alternatively, you can (c) import pre-existing structures you already have using an external-structures file.
The basics of the MODELLER pipeline
This section covers the default modeller engine, where structures are predicted with homology modelling.
DIAMOND first searches your sequence(s) against a database of proteins with a known structure. This database is downloaded from the Sali lab, who created and maintain MODELLER, and contains all of the PDB sequences clustered at 95% identity.
If any good hits are found, they are selected as templates, and their structures are nabbed either from the RCSB directly, or from a local pdb-db database which you can create yourself with anvi-setup-pdb-database. Then, anvi’o passes control over to MODELLER, which creates a 3D alignment for your sequence to the template structures, and makes final adjustments to it based off of empirical distributions of bond angles. For more information, check this blogpost.
The output of this program is a structure-db, which contains all of the modelled structures. Currently, the primary use of the structure-db is for interactive exploration with anvi-display-structure. You can also export your structures into external .pdb files with anvi-export-structures, or incorporate structural information in the variability-profile-txt with anvi-gen-variability-profile.
Basic standard run
Here is a simple run:
anvi-gen-structure-database -c contigs-db \ --gene-caller-ids 1,2,3 \ -o STRUCTURE.db
Following this, you will have the structures for genes 1, 2, and 3 stored in STRUCTURE.db, assuming reasonable templates were found. Alternatively, you can provide a file name with the gene caller IDs (one ID per line) with the flag --genes-of-interest.
If you have already run anvi-setup-pdb-database and therefore have a local copy of representative PDB structures, make sure you use it by providing the --offline flag. If you put it in a non-default location, provide the path to your pdb-db:
anvi-gen-structure-database -c contigs-db \ --gene-caller-ids 1,2,3 \ --pdb-database pdb-db \ -o STRUCTURE.db
To quickly get a very rough estimate for your structures, you can run with the flag --very-fast.
Predicting structures with ColabFold (AlphaFold2)
Instead of homology modelling, you can predict structures with AlphaFold2 via ColabFold by setting --engine colabfold. This does not require good templates to exist for your proteins.
Anvi’o does not assume ColabFold is on your $PATH. If you installed it in a conda environment (for example, one named colabfold), tell anvi’o its name and every ColabFold command will be run via conda run -n <name>:
ColabFold generates a multiple sequence alignment (MSA) and then predicts the structure. You must explicitly choose how the MSA step is done. The simplest option is to use the public MMseqs2 MSA server hosted by the ColabFold team with --colabfold-msa-server (this requires an internet connection and is appropriate for a handful of sequences):
anvi-gen-structure-database -c contigs-db \ --engine colabfold \ --colabfold-conda-env colabfold \ --colabfold-msa-server \ --gene-caller-ids 1,2,3 \ -o STRUCTURE.db
The public MSA server is a limited shared resource. If you have many sequences, please set up a local ColabFold database instead (see below).
If you have set up a local ColabFold database (with ColabFold’s setup_databases.sh), generate the MSA locally by pointing anvi’o to that directory with --colabfold-db instead of --colabfold-msa-server:
anvi-gen-structure-database -c contigs-db \ --engine colabfold \ --colabfold-conda-env colabfold \ --colabfold-db /path/to/colabfold_db \ --gene-caller-ids 1,2,3 \ -o STRUCTURE.db
All genes of interest are predicted together in a single ColabFold run, which is far more efficient on a GPU than predicting one gene at a time. ColabFold reports its own confidence metrics (per-residue pLDDT and model-level pTM), which anvi’o stores in the resulting structure-db.
You can tune the prediction with --num-models (how many AlphaFold2 models to run per gene), --num-recycle (more recycles can improve quality at the cost of runtime), and --amber (relax the best model with OpenMM/Amber for better side-chains). Anything not exposed as a dedicated flag can be passed straight through to colabfold_batch with --colabfold-additional-parameters (because its value starts with dashes, attach it with an equals sign, e.g. --colabfold-additional-parameters="--num-seeds 2"). As with the MODELLER engine, you can provide a --dump-dir to keep all of the raw ColabFold output.
Splitting the MSA and prediction steps (–only-msa / –only-predict)
A ColabFold run has two very differently-shaped halves: generating the multiple sequence alignments (MSA) is CPU-heavy, while predicting the structures is GPU-heavy. When you scale up to many genes or genomes, you often want to run these on different machines — for example, the MSA step on CPU nodes and the prediction step on GPU nodes of a cluster, wired together by a workflow manager like Snakemake. The --only-msa and --only-predict flags let you split the run at that seam, using a --dump-dir as an on-disk checkpoint that connects the two steps.
--only-msa runs only the MSA step and stops, writing the alignments and a small checkpoint manifest into --dump-dir. This only works with a local ColabFold database (--colabfold-db): the public MSA server (--colabfold-msa-server) generates the MSA and predicts the structure in a single step that cannot be split. No structure database is produced yet.
anvi-gen-structure-database -c contigs-db \ --engine colabfold \ --colabfold-conda-env colabfold \ --colabfold-db /path/to/colabfold_db \ --gene-caller-ids 1,2,3 \ --only-msa \ --dump-dir MY_CHECKPOINT
--only-predict then resumes from that checkpoint, predicting the structures and building the structure-db. You must give it the same contigs-db and genes of interest as the --only-msa run: anvi’o verifies that the sequences match the checkpoint before predicting and refuses to continue if they do not, so you cannot accidentally predict structures against MSAs that were built for different genes.
anvi-gen-structure-database -c contigs-db \ --engine colabfold \ --colabfold-conda-env colabfold \ --gene-caller-ids 1,2,3 \ --only-predict \ --dump-dir MY_CHECKPOINT \ -o STRUCTURE.db
Basic import run
If you already possess structures and would like to create a structure-db for downstream anvi’o uses such as anvi-display-structure, you should create a external-structures file. Then, create the database as follows:
anvi-gen-structure-database -c contigs-db \ --external-structures external-structures \ -o STRUCTURE.db
You can also import structures for a pangenome, by pointing at a pan-db and its genomes-storage-db instead of a contigs-db:
anvi-gen-structure-database --pan-db pan-db \ -g genomes-storage-db \ --external-structures external-structures \ -o STRUCTURE.db
The external-structures file format differs slightly between the two (a pangenome file names the genome each gene comes from); see external-structures for both layouts.
Please avoid using any MODELLER-specific parameters when using this mode, as they will be silently ignored.
Advanced Parameters
Here, we will go through a brief overview of the MODELLER parameters that you are able to change. See this page for more information.
- The number of models to be simulated. The default is 1.
- The standard deviation of atomic perturbation of the initial structure (i.e. how much you change the position of the atoms before fine tuning with other analysis). The default is 4 angstroms.
- The MODELLER database used. The default is
pdb_95, which can be found here. This is the same database that is downloaded by anvi-setup-pdb-database. - The scoring function used to compare potential models. The default is
DOPE_score. - The minimum percent identity cutoff for a template to be further considered.
- The minimum alignment fraction that the sequence is covered by the template in order to be further considered.
- The maximum number of templates that the program will consider. The default is 5.
- The MODELLER program to use. The default is
mod9.19, but anvi’o is somewhat intelligent and will look for the most recent version it can find.
For a case study on how some of these parameters matter, see here.
You also have the option to
- Skip the use of DSSP, which predicts beta sheets, alpha helices, certain bond angles, and relative solvent acessibility of residues.
- Output all the raw data, just provide a path to the desired directory with the flag
--dump-dir.
Edit this file to update this information.
Command line interface
The following is the list of parameters and their descriptions in the latest version of anvi-gen-structure-database.
The code that generates this web page ensures that this information is the latest available in 9-dev (eunice). Which means, in some cases the information in this section (generated automatically) might be more comprehensive or up-to-date compared to the descriptions above (written by humans).
Command line usage
Parameters and their descriptions
-c, --contigs-dbCONTIGS_DB- Anvi'o contigs database generated by 'anvi-gen-contigs-database'
--pan-dbPAN_DB- Anvi'o pan database
-g, --genomes-storageGENOMES_STORAGE- Anvi'o genomes storage file
--pdb-dbPDB_DB- By default, this program accesses the structure files it needs from an internal anvi'o database that can be set up with anvi-setup-pdb-database. If a required structure is not in this database, it will instead be downloaded from the RCSB PDB server. This parameter exists only if a) you created a database and b) it exists in a custom location. In this case, please provide that path here. Otherwise we vibing.
--genes-of-interestFILE- A file with anvi'o gene caller IDs. There should be only one column in the file, and each line should correspond to a unique gene caller id (without a column header).
--gene-caller-idsGENE_CALLER_IDS- Gene caller ids to focus on. Multiple of them can be declared separated by a delimiter (the default is a comma, and if there is no option to change the delimiter, you must use a comma).In anvi-gen-variability-profile, if you declare nothing you will get all genes matching your other filtering criteria. In other programs, you may get everything, nothing, or an error. It really depends on the situation. Fortunately, mistakes are cheap, so it's worth a try.
--gene-clusters-of-interestFILE- A file with anvi'o gene cluster ids. There should be only one column in the file, and each line should correspond to a unique gene cluster id (without a column header). This is the gene-cluster analogue of --genes-of-interest.
--gene-cluster-idsGENE_CLUSTER_IDS- Gene cluster ids to focus on. Multiple of them can be declared, separated by a comma (e.g., --gene-cluster-ids GC_00000001,GC_00000002). This is the gene-cluster analogue of --gene-caller-ids. If you declare nothing, anvi'o may assume all of them, depending on the program.
--select-representative- Instead of selecting every gene in each gene cluster of interest, select a single representative gene per gene cluster. Anvi'o picks the representative using a medoid-based strategy over the aligned amino acid sequences (it discards length outliers and prefers complete gene calls), so this requires a pangenome for which gene-cluster alignments were computed. The representative is a real gene from the cluster (not a consensus sequence).
-o, --output-db-pathDB_FILE_PATH- Output file path for the new database.
--dump-dirDUMP_DIR- Modeling and annotating structures requires a lot of moving parts, each which have their own outputs. The output of this program is a structure database containing the pertinent results of this computation, however a lot of stuff doesn't make the cut. By providing a directory for this parameter you will get, in addition to the structure database, a directory containing the raw output for everything.
--engineENGINE- The structure-prediction engine to use. 'modeller' (the default) predicts structures with template-based homology modelling. 'colabfold' predicts structures with AlphaFold2 via ColabFold. Each engine has its own set of parameters (see the MODELLER PARAMS and COLABFOLD PARAMS groups), while a few parameters apply to both (see SHARED PREDICTION PARAMS). This has no effect if you import structures with --external-structures instead of predicting them. Choices:
modellercolabfoldDefault:modeller
--num-models, -NNUM_MODELS- The number of structures ("models") to compute per protein; the best one is kept. For the MODELLER engine, each of the N models perturbs the initial atomic positions (by an amount set with --deviation) and is optimized independently, so a larger N searches more of the solution space (though template quality matters most, so there is no need to go overboard). For the ColabFold engine, this is the number of AlphaFold2 models (1-5) to run, and the highest-confidence one is kept. In both cases, fewer models is faster but explores less. The default is 1. Default:
1 --skip-DSSP- Dictionary of Secondary Structure of Proteins (DSSP) is a program that takes as its input a protein structure file and outputs predicted secondary structure (alpha helix, beta strand, etc.), measures of solvent accessibility, and hydrogen bonds for each residue in the protein. If for some reason you don't want this, provide this flag.
--deviation, -dDEVIATION- Deviation (angstroms) Default:
4.0 --modeller-database, -DMODELLER_DATABASE- Which database do you want to search the structures of? Default is "pdb_95". If you have your own database it must have either the extension .bin or .pir. If you don't have a database or don't know what this means, don't worry, we will both inform you and take care of you. Default:
pdb_95 --scoring-method, -bSCORING_METHOD- How should the best model be decided? The metric used could be any of GA341_score, DOPE_score, and molpdf. GA341 is an absolute measure, where a good model will have a score near 1.0, whereas anything below 0.6 can be considered bad. DOPE and molpdf scores are relative energy measures, where lower scores are better. DOPE has been generally shown to be a better distinguisher between good and bad models than molpdf. The default is DOPE_score. To learn more see the MODELLER tutorial: https://salilab.org/modeller/tutorial/basic.html. Default:
DOPE_score --very-fast- If provided, a very fast optimization is done for each model at the cost of accuracy. It is recommended to use a --num-models of 1, since the optimization is so crude that all models will likely converge to the same solution.
--percent-cutoff, -pPERCENT_CUTOFF- If a protein in the database has a percent identity to the gene of interest that is less than this parameter, then it is not considered as a template. The default is 30.000000. Default:
30 --alignment-fraction-cutoff, -aALIGNMENT_FRACTION_CUTOFF- If a protein in the database aligns to a fraction of the gene of interest that is less than this parameter, the template is not considered. For example, if --alignment-cutoff is set to 0.90, and the fraction of the gene of interest that is covered by a potential template is 0.80 in their alignment, the template does not align to enough of the gene of interest to be considered. The default is 0.800000. Default:
0.8 --max-number-templates, -tMAX_NUMBER_TEMPLATES- Generally speaking it is best to use as many templates as possible given that they have high proper percent identity to the gene of interest. Taken from https://salilab.org/modeller/methenz/andras/node4.html: 'The use of several templates generally increases the model accuracy. One strength of MODELLER is that it can combine information from multiple template structures, in two ways. First, multiple template structures may be aligned with different domains of the target, with little overlap between them, in which case the modeling procedure can construct a homology-based model of the whole target sequence. Second, the template structures may be aligned with the same part of the target, in which case the modeling procedure is likely to automatically build the model on the locally best template [43,44]. In general, it is frequently beneficial to include in the modeling process all the templates that differ substantially from each other, if they share approximately the same overall similarity to the target sequence.' The default is 5. Default:
5 --modeller-executableMODELLER_EXECUTABLE- The MODELLER program to use. For example, `mod9.19`. Anvi'o will try and find it if not provided
--offline-mode- Anvi'o first tries to obtain template structures from a database (see --pdb-db for details). If the requested template does not exist in the database, its structure will be downloaded from the RCSB PDB server. However, if you don't have access to internet, or hate the RCSB PDB, provide this flag so that all operations of this program remain offline. If the template structure is not in the database, then no template structure for you.
--colabfold-conda-envENV_NAME- The name of the conda environment in which ColabFold (colabfold_batch / colabfold_search) is installed. Anvi'o will run every ColabFold command via `conda run -n ENV_NAME`. If you leave this blank, anvi'o will assume the ColabFold programs are directly available (e.g. on your $PATH).
--colabfold-msa-server- Use the public MMseqs2 MSA server hosted by the ColabFold team to generate the multiple sequence alignment (MSA) step online. This requires an internet connection and is fine for a handful of sequences. Mutually exclusive with --colabfold-db. You must choose one of the two.
--colabfold-dbDB_DIR- Generate the MSA step locally instead of using the public server, by searching a local ColabFold database in this directory (the one you set up with ColabFold's `setup_databases.sh`). Recommended when you have many sequences. Mutually exclusive with --colabfold-msa-server. You must choose one of the two.
--num-recycleINT- Number of prediction recycles for ColabFold. Increasing this can improve prediction quality at the cost of runtime. If not set, ColabFold's default is used.
--amber- Relax the best predicted structure with OpenMM/Amber. This can improve the quality of side-chains at the cost of longer runtime.
--colabfold-additional-parametersCMD LINE PARAMS- Additional parameters to pass verbatim to `colabfold_batch`, for anything not exposed as a dedicated flag above. Because the value itself begins with dashes, you must attach it with an equals sign so it is not mistaken for anvi'o's own flags, e.g. --colabfold-additional-parameters="--num-seeds 2 --use-dropout". Anvi'o does not validate these, so use with care.
--only-msa- Run only ColabFold's multiple sequence alignment (MSA) step and stop, writing the MSAs and a small checkpoint manifest into --dump-dir. This creates a resumable checkpoint so you can run the CPU-heavy MSA step and the GPU-heavy prediction step separately (e.g. on different cluster nodes). This only works with a local ColabFold database (--colabfold-db): the public MSA server (--colabfold-msa-server) generates the MSA and predicts the structure in a single step that cannot be split. No structure database is produced in this mode; you finish the job later with --only-predict. Requires --dump-dir.
--only-predict- Skip the MSA step and predict structures from an MSA checkpoint that an earlier --only-msa run wrote to --dump-dir, then build the structure database. You must provide the SAME --contigs-db and genes of interest as the --only-msa run: anvi'o verifies that the sequences match the checkpoint before predicting, and refuses to continue if they do not. Requires --dump-dir (pointing at the --only-msa output); the structure database goes to -o (default STRUCTURE.db). Mutually exclusive with --only-msa.
--external-structuresFILE_PATH- A two-column TAB-delimited flat text file that lists PDB protein structures. The first item in the header line should read 'gene_callers_id', and the second should read 'path'. Each line in the file should describe a single entry, where the first column is the gene_callers_id that the structure corresponds to, and the second column is the path to the structure file.
-T, --num-threadsNUM_THREADS- Maximum number of threads to use for multithreading whenever possible. Very conservatively, the default is 1, unless the environmental variable `ANVIO_THREADS` sets another positive integer. If you use this parameter, it will override `ANVIO_THREADS`. It is a good idea to not exceed the number of CPUs / cores on your system. Plus, please be careful with this option if you are running your commands on a SGE -- if you are clusterizing your runs, and asking for multiple threads to use, you may deplete your resources very fast. Default:
1 --write-buffer-sizeINT- How many items should be kept in memory before they are written to the disk. The default is 25. The larger the buffer size, the less frequently the program will access the disk, yet the more memory will be consumed since the processed items will be cleared off the memory only after they are written to the disk. The default buffer size will likely work for most cases, but if you feel you need to reduce it, we trust you. Please keep an eye on the memory usage output to make sure the memory use never exceeds the size of the physical memory. If --num-threads is 1, this parameter is ignored because the DB is written to after each gene Default:
25
Additional Resources
Are you aware of resources that may help users better understand the utility of this program? Please feel free to edit this file on GitHub. If you are not sure how to do that, find the __resources__ tag in this file to see an example.