anvi-merge

Merge multiple anvio profiles.

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

Authors

A. Murat Eren (Meren)
WebEmailTwitterGithub

Requires

single-profile-db contigs-db

Provides

profile-db

Can provide

misc-data-items-order

Usage

The main function of anvi-merge is to convert multiple single-profile-dbs into a single profile-db (also called a merged profile database). Basically, this takes the alignment data from each sample (each contained in its own single-profile-db) and combines them into a single database that anvi’o can look through more easily.

Overview: How to run anvi-merge

  1. Set up your contigs-db. See that page for more information

  2. Use anvi-profile to create a single-profile-db for each of your samples (formatted into a bam-file) (Note: for each of these runs, you’ll need to use the same contigs-db and parameters)

  3. Use anvi-merge to merge those single-profile-dbs into a single database, called a profile-db. This will look something like the following:

anvi-merge -c cool_contigs.db \ Single_profile_db_1 Single_profile_db_2 \ -o cool_contigs_merge

This will put all of the output files (the final profile-db as well as a misc-data-items-order which is the result of your hierarchical clustering and describes the order to display your contigs in) into the folder cool_contigs_merge .

Other Parameters

You must give anvi-merge your contigs database and single profile databases. However, you can also provide more information or give addtional instructions. Use the flag -h at any time to display the help menu.

Hierarchical Clustering

To run or not to run?

  • Use the flag --skip-hierarchical-clustering to turn hierarchical clustering off. This will save on computation time, but will skip out on creating the tree of contigs at the center of the interactive interface. If you have more than 25,000 splits in the final profile, this will be set automatically.
  • Use the flag --enforce-hierarchical-clustering to turn hierarchical clustering back on. This will take a long time, but will produce a lovely contigs tree for the interactive interface.

Additional parameters

  • Provide a custom distance metric for clustering using the flag --distance. (The default is euclidean)
  • Provide a custom linkage method for clustering using the flag --linkage. (The default is ward)

Providing additional information

  • Provide the sample name using the flag -S. If you don’t, anvi’o will come up with one, but it probably won’t be any good.
  • Provide a text file in markdown to describe the project using the flag --description. This will show up when you later use the interactive interface to analyze your profile-db.

Output Information

  • Provide an output destination with the flag -o.
  • Add the flag -W to overwrite existing files in that directory.

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

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-merge [-h] -c CONTIGS_DB [-o DIR_PATH] [-S NAME] [--description TEXT_FILE] [--skip-hierarchical-clustering] [--enforce-hierarchical-clustering] [--distance DISTANCE_METRIC] [--linkage LINKAGE_METHOD] [-W] SINGLE_PROFILE(S) [SINGLE_PROFILE(S) ...]

Parameters and their descriptions

positional arguments
SINGLE_PROFILE(S) required
Anvi'o single profiles to merge
options
-c, --contigs-db CONTIGS_DB required
Anvi'o contigs database generated by 'anvi-gen-contigs-database'
-o, --output-dir DIR_PATH
Directory path for output files
-S, --sample-name NAME
It is important to set a sample name (using only ASCII letters and digits and without spaces) that is unique (considering all others). If you do not provide one, anvi'o will try to make up one for you based on other information (although, you should never let the software decide these things).
--description TEXT_FILE
A plain text file that contains some description about the project. You can use Markdown syntax. The description text will be rendered and shown in all relevant interfaces, including the anvi'o interactive interface, or anvi'o summary outputs.
--skip-hierarchical-clustering
If you are not planning to use the interactive interface (or if you have other means to add a tree of contigs in the database) you may skip the step where hierarchical clustering of your items are preformed based on default clustering recipes matching to your database type.
--enforce-hierarchical-clustering
If you have more than 25,000 splits in your merged profile, anvi-merge will automatically skip the hierarchical clustering of splits (by setting --skip-hierarchical-clustering flag on). This is due to the fact that computational time required for hierarchical clustering increases exponentially with the number of items being clustered. Based on our experience we decided that 25,000 splits is about the maximum we should try. However, this is not a theoretical limit, and you can overwrite this heuristic by using this flag, which would tell anvi'o to attempt to cluster splits regardless.
--distance DISTANCE_METRIC
The distance metric for the hierarchical clustering. If you do not use this flag, the default distance metric will be used for each clustering configuration which is "euclidean".
--linkage LINKAGE_METHOD
The same story with the `--distance`, except, the system default for this one is ward.
-W, --overwrite-output-destinations
Overwrite if the output files and/or directories exist.

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.

Copyleft, The anvi'o Project