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

anvi-update-structure-database -c contigs-db \ -s structure-db \ --gene-caller-ids 1,4,5

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

anvi-update-structure-database -c contigs-db \ -s structure-db \ --gene-caller-ids 1,4,5 \ --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

DATABASES Declaring relevant anvi'o databases. First things first.
-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 Specify which genes you want to be modelled. If a gene already exists in the DB, it will be overwritten if --overwrite is set. Otherwise, an error will be raised.
--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.
OUTPUT Output file and output style.
--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.
MODELLER PARAMS Parameters for MODELLER's homology modeling.
--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 PARAMS Parameters for structure prediction with ColabFold (AlphaFold2). These only apply when the structure database you are updating was created with the ColabFold engine. The scientific parameters (number of models, recycles, Amber relaxation, etc.) are read back from the database so the update stays consistent with how it was created; the parameters below are machine-specific and so must be provided again here.
--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.
EXTRA Everything else.
--rerun-genes
Supply if you would like to rerun structural modelling for your genes of interest if they are already present in your DB
--modeller-executable MODELLER_EXECUTABLE
The MODELLER program to use. For example, `mod9.19`. Anvi'o will try and find it if not provided.
-T, --num-threads NUM_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-size INT
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.