anvi-display-structure

Authors
Requires
Can use
Provides
Usage

Before running
MODELLER and ColabFold structures
Basic Run
Refining your search
Other parameters

Command line interface

Command line usage
Parameters and their descriptions

Additional Resources

Interactively visualize sequence variants on protein structures.

🔙 To the main page of anvi’o programs and artifacts.

Authors

Evan Kiefl

Özcan C. Esen

Requires

structure-db

Can use

variability-profile-txt contigs-db profile-db splits-txt genes-of-interest-txt

Provides

interactive

Usage

This program opens an interactive interface to explore single amino acid variants (SAAVs) and single codon variants (SCVs) in the context of predicted tertiary protein structures and binding sites. There are many example uses here and you can work through an example as part of the infant gut tutorial as well. This is an integral program of anvi’o structure, which you can learn more about here.

In short, this program enables users to explore sequence variation in the context of 3D protein structure, which reveals insight that cannot be learned from purely sequence-based approaches.

Before running

To run this program, you’ll need to have created a structure-db which can be easily done with a contigs-db and the program anvi-gen-structure-database.

You’ll also need a profile-db that was created using anvi-profile’s flag --profile-SCVs, which means that single codon variants (SCVs) have been profiled. Very sorry if this forces you to re-profile, but as of v6.2, this is now a very expedient process.

MODELLER and ColabFold structures

anvi-display-structure works with a structure-db regardless of whether its structures were predicted by MODELLER (template-based homology modelling) or ColabFold (AlphaFold2). The interface adapts to the prediction engine: for MODELLER structures it reports the DOPE, GA341, and molpdf model scores along with the PDB templates that were used, while for ColabFold structures it reports the model’s mean pLDDT and pTM (ColabFold is template-free, so no templates are shown). For ColabFold structures, the per-residue pLDDT confidence is also available as a variable you can color the protein by and filter variants on, just like the other residue-level annotations.

Basic Run

There are two ways to provide the variability information to this program.

The first is to provide a contigs-db and profile-db pair, and let this program calculate SAAVs and SCVs as they are requested by the interface.

anvi-display-structure -s structure-db \ -p profile-db \ -c contigs-db

The second is to use anvi-gen-variability-profile to create a variability-profile-txt. This way, you pre-load all of the variability data and don’t have to wait for anvi-display-structure to calculate variability on-the-fly. This option is probably most convenient in instances where you have already generated a variability-profile-txt for other reasons. If you fall into this camp, you can run anvi-display-structure as so:

anvi-display-structure -s structure-db \ -c contigs-db \ -v variability-profile-txt

You still must provide the contigs-db used to generate the variability-profile-txt, since it contains other necessary information such as functional annotations and ligand binding predictions. You may optionally provide a profile-db if custom sample grouping is important to you.

During anvi-gen-variability-profile, if you are only interested in genes that have predicted structures, you may want to run anvi-gen-variability-profile with the flag --only-if-structure.

Refining your search

You have several options to refine what proteins and variants you’re looking at:

Provide a list of gene caller IDs to only display specific genes (this can be provided either directly as a parameter or as a file with one gene caller ID per line)
Specify the minimum departure from the consensus sequence. This is a number from 0-1 that describes the threshold for a variability position to be displayed. For example, if this is set to 0.2, then all SAAVs and SCVs where less than 20 percent of the reads vary from the consensus sequence will not be displayed.
Specify samples of interest. Those in your profile-db or variability-profile-txt that are not in the samples of interest will be filtered out.

If you’re choosing to have anvi-display-structure calculate variability on-the-fly, you can speed things up by choosing to only calculate SAAVs or only calculate SCVs.

Other parameters

Power users can also change the server configuration (i.e. set the IP address, port number, browser path, server password, etc.)

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-display-structure.

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-display-structure [-h] -s STRUCTURE_DB [-p PROFILE_DB] [-c CONTIGS_DB] [-V VARIABILITY_TABLE] [--splits-of-interest FILE] [--samples-of-interest FILE] [--genes-of-interest FILE] [--gene-caller-ids GENE_CALLER_IDS] [-j FLOAT] [--SAAVs-only] [--SCVs-only] [-I IP_ADDR] [-P INT] [--browser-path PATH] [--server-only] [--password-protected]

Parameters and their descriptions

STRUCTURE Information related to the structure database, which can be created with anvi-gen-structure-database.

-s, --structure-db STRUCTURE_DB required: Anvi'o structure database.

VARIABILITY We can overlay codon and amino acid variability in your metagenomes but we need a data source of this variability. Most simply, anvi'o can learn this information when you provide both your profile (-p) and contigs (-c) databases. Alternatively, you can provide a variability table output (-V) from the program anvi-gen-variability-profile. If you don't want to visualize variants, this is the wrong tool for the job. Instead, export the PDB files with anvi-export-structures, and open with a more comprehensive protein viewing software.

-p, --profile-db PROFILE_DB: Anvi'o profile database
-c, --contigs-db CONTIGS_DB: Anvi'o contigs database generated by 'anvi-gen-contigs-database'
-V, --variability-profile VARIABILITY_TABLE: The output of anvi-gen-variability-profile, or a different variant-calling output that has been converted to the anvi'o format.

REFINING PARAMETERS Which samples, genes, and contigs etc. are you interested in? Define that stuff here.

--splits-of-interest FILE: A file with split names. There should be only one column in the file, and each line should correspond to a unique split name.
--samples-of-interest FILE: A file with samples names. There should be only one column in the file, and each line should correspond to a unique sample name (without a column header).
--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.
-j, --min-departure-from-consensus FLOAT: Takes a value between 0 and 1, where 1 is maximum divergence from the consensus. it can be an expensive operation to display every variable position, and so the default is 0.05. To display every variable position, set this parameter to 0. Default: 0.05
--SAAVs-only: If provided, variability will be generated for single amino acid variants (SAAVs) and not for single codon variants (SCVs). This could save you some time if you're only interested in SAAVs.
--SCVs-only: If provided, variability will be generated for single codon variants (SCVs) and not for single amino acid variants (SAAVs). This could save you some time if you're only interested in SCVs.

SERVER CONFIGURATION For power users.

-I, --ip-address IP_ADDR: IP address for the HTTP server. The default ip address (localhost) should work just fine for most. Default: localhost
-P, --port-number INT: Port number to use for anvi'o services. If nothing is declared, anvi'o will try to find a suitable port number, starting from the default port number, 8080.
--browser-path PATH: By default, anvi'o will use your default browser to launch the interactive interface. If you would like to use something else than your system default, you can provide a full path for an alternative browser using this parameter, and hope for the best. For instance we are using this parameter to call Google's experimental browser, Canary, which performs better with demanding visualizations.
--server-only: The default behavior is to start the local server, and fire up a browser that connects to the server. If you have other plans, and want to start the server without calling the browser, this is the flag you need.
--password-protected: If this flag is set, command line tool will ask you to enter a password and interactive interface will be only accessible after entering same password. This option is recommended for shared machines like clusters or shared networks where computers are not isolated.

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.