anvi-refine

Start an anvi'o interactive interactive to manually curate or refine a genome, whether it is a metagenome-assembled, single-cell, or an isolate genome.

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

Authors

A. Murat Eren (Meren)
WebEmailTwitterGithub
Daniel Blankenberg
EmailGithub

Requires

profile-db contigs-db

Can use

bin

Provides

bin

Usage

This program opens the anvi’o interactive interface to let the user refine what contigs are contained in a specific bin or manually split one bin into several.

In the interactive interface, any bins that you create will overwrite the bin that you originally opened. If you don’t provide any names, the new bins’ titles will be prefixed with the name of the original bin, so that bin will continue to live on in spirit.

Essentially, it is like running anvi-interactive, but disposing of the original bin when you’re done.

Potential Use Cases

There are several reasons you might want to use anvi-refine:

  • Your dataset is just really big.

    This process has its own dedicated blog post, but, in short, the interactive interface and analysis, like all things, has its limits. Instead of trying to actively analyze all of your data at once, which will be very computationally heavy and might limit the types of analysis you’ll even be able to do, it will be helpful to split your data into several smaller bins first. Then you can use anvi-refine on each one to replace those temporary bins with your final bins.

  • You want to refine a bin generated by automated binning software.

    After automated binning (which you can do in anvi’o with anvi-cluster-contigs), you might see an awkward bin or two. These programs often have difficultly separating bins in some scenarios, as well as sorting out prophages, mobile genetic elements, and other things that you might want to have in their own bin. You can take these out of your MAGs and put them in their own bins, split bins with high redundency, or just refine them in any way you please, using anvi-refine.

  • You’re just not happy with one of your bins.

    Happens to everyone. Maybe the redundency is just a little too high and you want to take a closer look, or maybe you just want to split up two contigs giving you different taxonomy results. Feel free to go in and take specfic contigs out or split one bin into several.

If you just want to look at the contents of partiuclarly glorious bin, you should probably just use anvi-interactive for that, since you don’t want to risk overwriting your bin.

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

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-refine [-h] -p PROFILE_DB -c CONTIGS_DB [-C COLLECTION_NAME] [-b BIN_NAME] [-B FILE_PATH] [--find-from-split-name SPLIT_NAME] [-t NEWICK] [--skip-hierarchical-clustering] [--load-full-state] [-V ADDITIONAL_VIEW] [-A ADDITIONAL_LAYERS] [-F FUNCTION ANNOTATION SOURCE] [--show-all-layers] [--split-hmm-layers] [--taxonomic-level {t_domain,t_phylum,t_class,t_order,t_family,t_genus,t_species}] [--hide-outlier-SNVs] [--title NAME] [--export-svg FILE_PATH] [--dry-run] [--skip-init-functions] [--skip-news] [--distance DISTANCE_METRIC] [--linkage LINKAGE_METHOD] [--skip-auto-ordering] [-I IP_ADDR] [-P INT] [--browser-path PATH] [--read-only] [--server-only] [--password-protected]

Parameters and their descriptions

DEFAULT INPUTS The interavtive interface can be started with and without anvi'o databases. The default use assumes you have your profile and contigs database, however, it is also possible to start the interface using ad-hoc input files. See 'MANUAL INPUT' section for other set of parameters that are mutually exclusive with datanases.
-p, --profile-db PROFILE_DB required
Anvi'o profile database
-c, --contigs-db CONTIGS_DB required
Anvi'o contigs database generated by 'anvi-gen-contigs-database'
REFINE-SPECIFICS Parameters that are essential to the refinement process.
-C, --collection-name COLLECTION_NAME
Collection name.
-b, --bin-id BIN_NAME
Bin name you are interested in.
-B, --bin-ids-file FILE_PATH
Text file for bins (each line should be a unique bin id).
--find-from-split-name SPLIT_NAME
If you don't know the bin name you want to work with but if you know the split name it contains you can use this parameter to tell anvi'o the split name, and so it can find the bin for you automatically. This is something extremely difficult for anvi'o to do, but it does it anyway because you.
ADDITIONAL STUFF Parameters to provide additional layers, views, or layer data.
-t, --tree NEWICK
NEWICK formatted tree structure
--skip-hierarchical-clustering
Skip hierarchical clustering for the splits in the refined bin, if you skip clustering you need to provide your own newick formatted tree using --tree parameter.
--load-full-state
Often the minimum and maximum values defined for the an entire profile database that contains all contigs do not scale well when you wish to work with a single bin in the refine mode. For this reason, the default behavior of anvi-refine is to ignore min/max values set in the default state. This flag is your way of telling anvi'o to not do that, and load the state stored in the profile database as is. Please note that this variable has no influence on the `detection` view. For the `detection` view, anvi'o will always load the global detection settings as if you have used this flag.
-V, --additional-view ADDITIONAL_VIEW
A TAB-delimited file for an additional view to be used in the interface. This file should contain all split names, and values for each of them in all samples. Each column in this file must correspond to a sample name. Content of this file will be called 'user_view', which will be available as a new item in the 'views' combo box in the interface
-A, --additional-layers ADDITIONAL_LAYERS
A TAB-delimited file for additional layers for splits. The first column of this file must be split names, and the remaining columns should be unique attributes. The file does not need to contain all split names, or values for each split in every column. Anvi'o will try to deal with missing data nicely. Each column in this file will be visualized as a new layer in the tree.
-F, --annotation-source-for-per-split-summary FUNCTION ANNOTATION SOURCE
Using this parameter with a functional annotation source that (1) is in the contigs database and (2) has a maximum of 10 different function names, will dynamically add a new layer to the intearctive interface where proportions of functions in that source will be shown per split as stacked bar charts.
VISUALS RELATED Parameters that give access to various adjustements regarding the interface.
--show-all-layers
When declared, this flag tells the interface to show every additional layer even if there are no hits. By default, anvi'o doesn't show layers if there are no hits for any of your items.
--split-hmm-layers
When declared, this flag tells the interface to split every gene found in HMM searches that were performed against non-singlecopy gene HMM profiles into their own layer. Please see the documentation for details.
--taxonomic-level TAXONOMIC_LEVEL
The taxonomic level to use whenever relevant and/or available. The default taxonomic level is t_genus, but if you choose something specific, anvi'o will focus on that whenever possible. Choices: t_domain t_phylum t_class t_order t_family t_genus t_species Default: t_genus
--hide-outlier-SNVs
During profiling, anvi'o marks positions of single-nucleotide variations (SNVs) that originate from places in contigs where coverage values are a bit 'sketchy'. If you would like to avoid SNVs in those positions of splits in applicable projects you can use this flag, and the interface would hide SNVs that are marked as 'outlier' (although it is clearly the best to see everything, no one will judge you if you end up using this flag) (plus, there may or may not be some historical data on this here: https://github.com/meren/anvio/issues/309).
--title NAME
Title for the interface. If you are working with a RUNINFO dict, the title will be determined based on information stored in that file. Regardless, you can override that value using this parameter.
--export-svg FILE_PATH
The SVG output file path.
SWEET PARAMS OF CONVENIENCE Parameters and flags that are not quite essential (but nice to have).
--dry-run
Don't do anything real. Test everything, and stop right before wherever the developer said 'well, this is enough testing', and decided to print out results.
--skip-init-functions
When declared, function calls for genes will not be initialized (therefore will be missing from all relevant interfaces or output files). The use of this flag may reduce the memory fingerprint and processing time for large datasets.
--skip-news
Don't try to read news content from upstream.
--distance DISTANCE_METRIC
The distance metric for the hierarchical clustering of splits in the bin. Only relevant if you are not using --skip-hierarchical-clustering. The default is "euclidean". Default: euclidean
--linkage LINKAGE_METHOD
The linkage method for the hierarchical clustering of splits in the bin. Only relevant if you are not using --skip-hierarchical-clustering. The default is "ward". Default: ward
--skip-auto-ordering
When declared, the attempt to include automatically generated orders of items based on additional data is skipped. In case those buggers cause issues with your data, and you still want to see your stuff and deal with the other issue maybe later.
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.
--read-only
When the interactive interface is started with this flag, all 'database write' operations will be disabled.
--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.

Copyleft, The anvi'o Project