anvi-update-structure-database
Add or re-run genes from an already existing structure database. All settings used to generate your database will be used in this program.
🔙 To the main page of anvi’o programs and artifacts.
Authors
Requires
contigs-db
structure-db
pan-db
genomes-storage-db 
Can use
genes-of-interest-txt
external-structures 
Provides
structure-db 
Usage
This program is used to add additional genes to or re-run the analysis of genes already within a structure-db.
For that reason, it is very similar to anvi-gen-structure-database and the parameters used to run that program (when you first generated your structure-db) will be automatically applied when you run this program. To know what MODELLER parameters are being used, you run this program on a structure-db with the flag --list-modeller-params.
To run this program, just provide a contigs-db and structure-db, and name your genes of interest (either in a file or directly). If the named genes are not already in your structure-db, they will be added to the database.
For example, if your structure-db already contains the genes with caller-IDs 1, 2 and 3, and you run
Then the structural analysis for genes 4 and 5 will be added to your structure-db (assuming templates are found). Gene 1 will be ignored, since it is already present.
If instead you want to re-run the structural analysis on genes that are already in your structure-db, you’ll need to specify that by adding the flag --rerun-genes
Now, the program will rerun the analysis for gene 1 and will still add genes 4 and 5 to the structure-db.
Both of these runs will have the same MODELLER parameters as your run of anvi-gen-structure-database. However, to get the raw outputs, you will need to use the parameter --dump-dir. You can also set a specific MODELLER program with --modeller-executable. Parameters for multi-threading would also have to be given again.
Like anvi-gen-structure-database, this program also accepts external-structures – for a contigs-db or a pangenome structure database. When updating a pangenome structure database, anvi’o reconciles the surrogate protein ids by natural key, so adding or re-running structures never disturbs the ids already in the database.
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-update-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
anvi-update-structure-database [-h] [-c CONTIGS_DB] [--pan-db PAN_DB] [-g GENOMES_STORAGE] -s STRUCTURE_DB [--genes-of-interest FILE] [--gene-caller-ids GENE_CALLER_IDS] [--gene-clusters-of-interest FILE] [--gene-cluster-ids GENE_CLUSTER_IDS] [--select-representative] [--external-structures FILE_PATH] [--dump-dir DUMP_DIR] [--list-modeller-params] [--colabfold-conda-env ENV_NAME] [--colabfold-msa-server] [--colabfold-db DB_DIR] [--only-msa] [--only-predict] [--rerun-genes] [--modeller-executable MODELLER_EXECUTABLE] [-T NUM_THREADS] [--write-buffer-size INT]
Parameters and their descriptions
-c, --contigs-db CONTIGS_DB
- Anvi'o contigs database generated by 'anvi-gen-contigs-database'
--pan-db PAN_DB
- Anvi'o pan database
-g, --genomes-storage GENOMES_STORAGE
- Anvi'o genomes storage file
-s, --structure-db STRUCTURE_DB required
- Anvi'o structure database.
--genes-of-interest FILE
- 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-ids GENE_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-interest FILE
- 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-ids GENE_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).
--external-structures FILE_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.
--dump-dir DUMP_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.
--list-modeller-params
- Since you are updating an existing DB, modeller params are set in place. You can have this program list them by providing this flag
--colabfold-conda-env ENV_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. Provide this if the database you are updating was created this way. Mutually exclusive with --colabfold-db.
--colabfold-db DB_DIR
- Generate the MSA step locally by searching a local ColabFold database in this directory (the one you set up with ColabFold's `setup_databases.sh`). Provide this if the database you are updating was created this way. This path is machine-specific, so it is not stored in the structure database and must be given again here. Mutually exclusive with --colabfold-msa-server.
--only-msa
- Run only ColabFold's multiple sequence alignment (MSA) step for the genes you are adding 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). No genes are added to the database 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 add the resulting structures to the database. You must provide the SAME --contigs-db and genes of interest as the --only-msa run. Requires --dump-dir (pointing at the --only-msa output). Mutually exclusive with --only-msa.
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.