--- name: "metaphlan" section: "1" platform: "linux" package: "metaphlan" version: "4.0.4+ds-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/metaphlan" --- # metaphlan(1) METAgenomic PHyLogenetic ANalysis for metagenomic taxonomic profiling ## NAME metaphlan2 - METAgenomic PHyLogenetic ANalysis for metagenomic taxonomic profiling ## SYNOPSIS **metaphlan2**\ **--input\_type** {fastq,fasta,multifasta,multifastq,bowtie2out,sam} \[--mpa\_pkl MPA\_PKL\] \[--bowtie2db METAPHLAN\_BOWTIE2\_DB\] \[--bt2\_ps BowTie2 presets\] \[--bowtie2\_exe BOWTIE2\_EXE\] \[--bowtie2out FILE\_NAME\] \[--no\_map\] \[--tmp\_dir\] \[--tax\_lev TAXONOMIC\_LEVEL\] \[--min\_cu\_len\] \[--min\_alignment\_len\] \[--ignore\_viruses\] \[--ignore\_eukaryotes\] \[--ignore\_bacteria\] \[--ignore\_archaea\] \[--stat\_q\] \[--ignore\_markers IGNORE\_MARKERS\] \[--avoid\_disqm\] \[--stat\] \[-t ANALYSIS TYPE\] \[--nreads NUMBER\_OF\_READS\] \[--pres\_th PRESENCE\_THRESHOLD\] \[--clade\] \[--min\_ab\] \[-h\] \[-o output file\] \[--sample\_id\_key name\] \[--sample\_id value\] \[-s sam\_output\_file\] \[--biom biom\_output\] \[--mdelim mdelim\] \[--nproc N\] \[-v\] \[INPUT\_FILE\] \[OUTPUT\_FILE\] ## DESCRIPTION ### MetaPhlAn 2 clade-abundance estimation The basic usage of MetaPhlAn 2 consists in the identification of the clades (from phyla to species and strains in particular cases) present in the metagenome obtained from a microbiome sample and their relative abundance. This correspond to the default analysis type (**--analysis\_type** rel\_ab). - \* Profiling a metagenome from raw reads: - metaphlan2 metagenome.fastq **--input\_type** fastq - \* You can take advantage of multiple CPUs and save the intermediate BowTie2 output for re-running - MetaPhlAn extremely quickly:\ metaphlan2 metagenome.fastq **--bowtie2out** metagenome.bowtie2.bz2 **--nproc** 5 **--input\_type** fastq - \* If you already mapped your metagenome against the marker DB (using a previous MetaPhlAn run), you can obtain the results in few seconds by using the previously saved **--bowtie2out** file and specifying the input (**--input\_type** bowtie2out): - metaphlan2 metagenome.bowtie2.bz2 **--nproc** 5 **--input\_type** bowtie2out - \* You can also provide an externally BowTie2-mapped SAM if you specify this format with **--input\_type**. Two steps: first apply BowTie2 and then feed MetaPhlAn2 with the obtained sam: - bowtie2 **--sam-no-hd** **--sam-no-sq** **--no-unal** **--very-sensitive** **-S** metagenome.sam **-x** /usr/share/metaphlan2/db\_v20/mpa\_v20\_m200 **-U** metagenome.fastq metaphlan2 metagenome.sam **--input\_type** sam \> profiled\_metagenome.txt - \* Multiple alternative ways to pass the input are also available: - cat metagenome.fastq \| metaphlan2 **--input\_type** fastq\ tar xjf metagenome.tar.bz2 **--to-stdout** \| metaphlan2 **--input\_type** fastq\ metaphlan2 **--input\_type** fastq \< metagenome.fastq\ metaphlan2 **--input\_type** fastq \<(bzcat metagenome.fastq.bz2)\ metaphlan2 **--input\_type** fastq \<(zcat metagenome\_1.fastq.gz metagenome\_2.fastq.gz) - \* We can also natively handle paired-end metagenomes, and, more generally, metagenomes stored in multiple files (but you need to specify the **--bowtie2out** parameter): - metaphlan2 metagenome\_1.fastq,metagenome\_2.fastq **--bowtie2out** metagenome.bowtie2.bz2 **--nproc** 5 **--input\_type** fastq ### MetaPhlAn 2 strain tracking MetaPhlAn 2 introduces the capability of charachterizing organisms at the strain level using non aggregated marker information. Such capability comes with several slightly different flavours and are a way to perform strain tracking and comparison across multiple samples. Usually, MetaPhlAn 2 is first ran with the default **--analysis\_type** to profile the species present in the community, and then a strain-level profiling can be performed to zoom-in into specific species of interest. This operation can be performed quickly as it exploits the **--bowtie2out** intermediate file saved during the execution of the default analysis type. - \* The following command will output the abundance of each marker with a RPK (reads per kil-base) higher 0.0. (we are assuming that metagenome\_outfmt.bz2 has been generated before as shown above). - metaphlan2 **-t** marker\_ab\_table metagenome\_outfmt.bz2 **--input\_type** bowtie2out \> marker\_abundance\_table.txt - The obtained RPK can be optionally normalized by the total number of reads in the metagenome to guarantee fair comparisons of abundances across samples. The number of reads in the metagenome needs to be passed with the '--nreads' argument - \* The list of markers present in the sample can be obtained with '-t marker\_pres\_table' - metaphlan2 **-t** marker\_pres\_table metagenome\_outfmt.bz2 **--input\_type** bowtie2out \> marker\_abundance\_table.txt - The **--pres\_th** argument (default 1.0) set the minimum RPK value to consider a marker present - \* The list '-t clade\_profiles' analysis type reports the same information of '-t marker\_ab\_table' but the markers are reported on a clade-by-clade basis. - metaphlan2 **-t** clade\_profiles metagenome\_outfmt.bz2 **--input\_type** bowtie2out \> marker\_abundance\_table.txt - \* Finally, to obtain all markers present for a specific clade and all its subclades, the '-t clade\_specific\_strain\_tracker' should be used. For example, the following command is reporting the presence/absence of the markers for the B. fragulis species and its strains the optional argument **--min\_ab** specifies the minimum clade abundance for reporting the markers - $ metaphlan2 **-t** clade\_specific\_strain\_tracker **--clade** s\_\_Bacteroides\_fragilis metagenome\_outfmt.bz2 **--input\_type** bowtie2out \> marker\_abundance\_table.txt ## OPTIONS ### positional arguments - INPUT\_FILE the input file can be: - \* a fastq file containing metagenomic reads - OR - \* a BowTie2 produced SAM file. - OR - \* an intermediary mapping file of the metagenome generated by a previous MetaPhlAn run - If the input file is missing, the script assumes that the input is provided using the standard input, or named pipes. IMPORTANT: the type of input needs to be specified with **--input\_type** - OUTPUT\_FILE the tab-separated output file of the predicted taxon relative abundances \[stdout if not present\] ### Required arguments - **--input\_type** {fastq,fasta,multifasta,multifastq,bowtie2out,sam} set whether the input is the multifasta file of metagenomic reads or the SAM file of the mapping of the reads against the MetaPhlAn db. \[default 'automatic', i.e. the script will try to guess the input format\] ### Mapping arguments: - **--mpa\_pkl** MPA\_PKL the metadata pickled MetaPhlAn file - **--bowtie2db** METAPHLAN\_BOWTIE2\_DB The BowTie2 database file of the MetaPhlAn database. Used if **--input\_type** is fastq, fasta, multifasta, or multifastq - **--bt2\_ps** BowTie2 presets presets options for BowTie2 (applied only when a multifasta file is provided) The choices enabled in MetaPhlAn are: - \* sensitive - \* very-sensitive - \* sensitive-local - \* very-sensitive-local - \[default very-sensitive\] - **--bowtie2\_exe** BOWTIE2\_EXE Full path and name of the BowTie2 executable. This option allows MetaPhlAn to reach the executable even when it is not in the system PATH or the system PATH is unreachable - **--bowtie2out** FILE\_NAME The file for saving the output of BowTie2 - **--no\_map** Avoid storing the **--bowtie2out** map file - **--tmp\_dir** the folder used to store temporary files \[default is the OS dependent tmp dir\] ### Post-mapping arguments - **--tax\_lev** TAXONOMIC\_LEVEL The taxonomic level for the relative abundance output:\ 'a' : all taxonomic levels\ 'k' : kingdoms\ 'p' : phyla only\ 'c' : classes only\ 'o' : orders only\ 'f' : families only\ 'g' : genera only\ 's' : species only\ \[default 'a'\] - **--min\_cu\_len** minimum total nucleotide length for the markers in a clade for estimating the abundance without considering sub-clade abundances \[default 2000\] - **--min\_alignment\_len** The sam records for aligned reads with the longest subalignment length smaller than this threshold will be discarded. \[default None\] - **--ignore\_viruses** Do not profile viral organisms - **--ignore\_eukaryotes** Do not profile eukaryotic organisms - **--ignore\_bacteria** Do not profile bacterial organisms - **--ignore\_archaea** Do not profile archeal organisms - **--stat\_q** Quantile value for the robust average \[default 0.1\] - **--ignore\_markers** IGNORE\_MARKERS File containing a list of markers to ignore. - **--avoid\_disqm** Deactivate the procedure of disambiguating the quasi-markers based on the marker abundance pattern found in the sample. It is generally recommended too keep the disambiguation procedure in order to minimize false positives - **--stat** EXPERIMENTAL! Statistical approach for converting marker abundances into clade abundances\ 'avg\_g' : clade global (i.e. normalizing all markers together) average\ 'avg\_l' : average of length-normalized marker counts\ 'tavg\_g' : truncated clade global average at **--stat\_q** quantile\ 'tavg\_l' : trunated average of length-normalized marker counts (at **--stat\_q**)\ 'wavg\_g' : winsorized clade global average (at **--stat\_q**)\ 'wavg\_l' : winsorized average of length-normalized marker counts (at **--stat\_q**)\ 'med' : median of length-normalized marker counts\ \[default tavg\_g\] ### Additional analysis types and arguments - **-t** ANALYSIS TYPE Type of analysis to perform: - \* rel\_ab: profiling a metagenomes in terms of relative abundances - \* rel\_ab\_w\_read\_stats: profiling a metagenomes in terms of relative abundances and estimate the number of reads coming from each clade. - \* reads\_map: mapping from reads to clades (only reads hitting a marker) - \* clade\_profiles: normalized marker counts for clades with at least a non-null marker - \* marker\_ab\_table: normalized marker counts (only when \> 0.0 and normalized by metagenome size if **--nreads** is specified) - \* marker\_counts: non-normalized marker counts \[use with extreme caution\] - \* marker\_pres\_table: list of markers present in the sample (threshold at 1.0 if not differently specified with **--pres\_th** - \[default 'rel\_ab'\] - **--nreads** NUMBER\_OF\_READS The total number of reads in the original metagenome. It is used only when **-t** marker\_table is specified for normalizing the length-normalized counts with the metagenome size as well. No normalization applied if **--nreads** is not specified - **--pres\_th** PRESENCE\_THRESHOLD Threshold for calling a marker present by the **-t** marker\_pres\_table option - **--clade** The clade for clade\_specific\_strain\_tracker analysis - **--min\_ab** The minimum percentage abundace for the clade in the clade\_specific\_strain\_tracker analysis - **-h**, **--help** show this help message and exit ### Output arguments - **-o** output file, **--output\_file** output file The output file (if not specified as positional argument) - **--sample\_id\_key** name Specify the sample ID key for this analysis. Defaults to '#SampleID'. - **--sample\_id** value Specify the sample ID for this analysis. Defaults to 'Metaphlan2\_Analysis'. - **-s** sam\_output\_file, **--samout** sam\_output\_file The sam output file - **--biom** biom\_output, **--biom\_output\_file** biom\_output If requesting biom file output: The name of the output file in biom format - **--mdelim** mdelim, **--metadata\_delimiter\_char** mdelim Delimiter for bug metadata: - defaults to pipe. e.g. the pipe in k\_\_Bacteria\|p\_\_Proteobacteria ### Other arguments - **--nproc** N The number of CPUs to use for parallelizing the mapping \[default 1, i.e. no parallelism\] - **-v**, **--version** Prints the current MetaPhlAn version and exit ## AUTHOR The code of MetaPhlAn was rwitten by Nicola Segata (nicola.segata@unitn.it), Duy Tin Truong (duytin.truong@unitn.it). This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program.