anvi-gen-fixation-index-matrix

Authors
Requires
Can use
Provides
Usage

What’s a fixation index?

Anvi-gen-fixation-index

Input 1: Variability Profile
Input 2: Anvi’o databases
Additional Parameters

Command line interface

Command line usage
Parameters and their descriptions

Additional Resources

Generate a pairwise matrix of a fixation indices between samples.

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

Authors

Evan Kiefl

Requires

contigs-db profile-db

Can use

structure-db bin variability-profile-txt splits-txt genes-of-interest-txt

Provides

fixation-index-matrix

Usage

This program generates a matrix of the pairwise fixation indices (F_ST) between your samples.

What’s a fixation index?

As described in the Infant Gut Tutorial, the fixation index is a measure of the distance between two populations, based on their sequence variants (usually SNVs). Specifically, the fixation index is the ratio between the variance in allele frequency between subpopulations and the variance in the total population.

The fixation index has its own Wikipedia page and is a special case of F-statistics.

In anvi’o, the fixation index is calculated in accordance with Schloissnig et al. (2013)’s work to allow variant positions with multiple competing alleles.

Anvi-gen-fixation-index

There are two ways to run this program.

Input 1: Variability Profile

The simplest one is the one shown in the Infant Gut Tutorial: just provide a variability-profile, like so:

anvi-gen-fixation-index-matrix --variability-profile variability-profile \ --output-file my_matrix.txt

This will use the information in your variability-profile-txt to generate the fixation index for each of the pairwise sample comparisons, and store the results in a fixation-index-matrix named my_matrix.txt.

Input 2: Anvi’o databases

Instead of providing a variability-profile, you can instead provide the inputs to anvi-gen-variability-profile and let anvi’o do all of the work for you. Specifically, this means providing a contigs-db and profile-db pair to find your variability positions and a specific subset to focus on in any of these ways:

Provide a list of gene caller IDs (as a parameter with the flag --gene-caller-ids or in a file with one ID per line with the flag --genes-of-interest)
Provide a list of splits (in a splits-txt)
Provide a collection and bin

Additionally, you can add structural annotations by inputting a structure-db (and focus only on genes with structural annotations with the flag --only-if-structure) or choose to focus on only a subset of your samples by providing a file of samples of interest.

When doing this, you can also set the variability engine to get the fixation index for SCVs (--engine CDN) or SAAVs (--engine AA).

You can find more information about these parameters on the page for anvi-gen-variability-profile.

Additional Parameters

While a fixation index is usually between 0 and 1, it is possible for an index to be negative (usually because of out-breeding). By default, anvi’o sets these negative values to 0, but you can choose to keep the negative values with the flag --keep-negatives

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-fixation-index-matrix.

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-gen-fixation-index-matrix [-h] [-p PROFILE_DB] [-c CONTIGS_DB] [-s STRUCTURE_DB] [-V VARIABILITY_TABLE] [-C COLLECTION_NAME] [-b BIN_NAME] [--splits-of-interest FILE] [--genes-of-interest FILE] [--gene-caller-ids GENE_CALLER_IDS] [--only-if-structure] [--samples-of-interest FILE] [--engine ENGINE] [--min-coverage-in-each-sample INT] [-o FIXATION_INDICES] [--keep-negatives]

Parameters and their descriptions

DATABASES Declaring relevant anvi'o databases. First things first. Some are mandatory, some are optional.

-p, --profile-db PROFILE_DB: Anvi'o profile database
-c, --contigs-db CONTIGS_DB: Anvi'o contigs database generated by 'anvi-gen-contigs-database'
-s, --structure-db STRUCTURE_DB: Anvi'o structure 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.

FOCUS :: BIN You need to pick someting to focus. You can ask anvi'o to work with a bin in a collection.

-C, --collection-name COLLECTION_NAME: Collection name.
-b, --bin-id BIN_NAME: Bin name you are interested in.

FOCUS :: SPLIT NAMES Alternatively you can declare split names to focus.

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

FOCUS :: GENE CALLER IDs Alternatively you can declare gene caller IDs to focus.

--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.
--only-if-structure: If provided, your genes of interest will be further subset to only include genes with structures in your structure database, and therefore must be supplied in conjunction with a structure database, i.e. `-s <your_structure_database>`. If you did not specify genes of interest, ALL genes will be subset to those that have structures.

SAMPLES You can ask anvi'o to focus only on a subset of samples.

--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).

ENGINE Set your engine. This is important as it will define the output profile you will get from this program. The engine can focus on nucleotides (NT), codons (CDN), or an amino acids (AA).

--engine ENGINE: Variability engine. The default is 'NT'. Default: NT

FILTERS Parameters that will help you to do a very precise analysis. If you declare nothing from this bunch, you will get "everything" to play with, which is not necessarily a good thing...

--min-coverage-in-each-sample INT: Minimum coverage of a given variable nucleotide position in all samples. If a nucleotide position is covered less than this value even in one sample, it will be removed from the analysis. Default is 0. Default: 0

OUTPUT Output file and style

-o, --output-file FIXATION_INDICES: File path to store results. Default: fixation_indices.txt

EXTRAS Because why not be extra?

--keep-negatives: Negative numbers are theoretically possible, and are sometimes interpreted as out-breeding. By default, we set negative numbers to 0 so the results are reflective of a standard distance metric. Provide this flag if you would prefer otherwise.

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.