| taxgetrank

## Wiki

The master copies of EMBOSS documentation are available at http://emboss.open-bio.org/wiki/Appdocs on the EMBOSS Wiki.

Please help by correcting and extending the Wiki pages.

## Function

Get parents of taxon(s)

## Description

taxgetrank reads in one or more taxons, and reports the taxons at each level from the current to the top. The taxon input may be a literal sequence or read from a database, file, file of taxon names, or even the command-line or the output of another programs. The taxon output can be written to screen, to file, or passed to another program. A wide range of standard taxon formats may be specified for input and output.

## Algorithm

The NCBI taxonomy records the parent of each taxon, up to a known top level 1.

## Usage

Here is a sample session with taxgetrank

    % taxgetrank ttax:9606 -oformat excel
    Get parents of taxon(s)
    Taxonomic rank(s)
               kingdom : Kingdom
                phylum : Phylum
                 class : Class
                 order : Order
                family : Family
                 genus : Genus
               species : Species
                 tribe : Tribe
              varietas : varietas
         species group : Species group
      species subgroup : Species subgroup
               no rank : None
          superkingdom : Superkingdom
           superphylum : Superphylum
            superclass : Superclass
            superorder : Superorder
           superfamily : Superfamily
            subkingdom : Subkingdom
             subphylum : Subphylum
              subclass : Subclass
              suborder : Suborder
             subfamily : Subfamily
              subgenus : Subgenus
            subspecies : Subspecies
              subtribe : Subtribe
            infraclass : Infraclass
            infraorder : Infraorder
             parvorder : Parvorder
    Find taxons at rank [kingdom,phylum,class,order,family,genus,species]:
    Taxon output file [9606.excel]:

Go to the input files for this example
Go to the output files for this example

Example 2

    % taxgetrank ttax:9606 -oformat excel
    Get parents of taxon(s)
    Taxonomic rank(s)
               kingdom : Kingdom
                phylum : Phylum
                 class : Class
                 order : Order
                family : Family
                 genus : Genus
               species : Species
                 tribe : Tribe
              varietas : varietas
         species group : Species group
      species subgroup : Species subgroup
               no rank : None
          superkingdom : Superkingdom
           superphylum : Superphylum
            superclass : Superclass
            superorder : Superorder
           superfamily : Superfamily
            subkingdom : Subkingdom
             subphylum : Subphylum
              subclass : Subclass
              suborder : Suborder
             subfamily : Subfamily
              subgenus : Subgenus
            subspecies : Subspecies
              subtribe : Subtribe
            infraclass : Infraclass
            infraorder : Infraorder
             parvorder : Parvorder
    Find taxons at rank [kingdom,phylum,class,order,family,genus,species]: *
    Taxon output file [9606.excel]:

Go to the output files for this example

Example 3

    % taxgetrank ttax:9606 -oformat excel -hidden
    Get parents of taxon(s)
    Taxonomic rank(s)
               kingdom : Kingdom
                phylum : Phylum
                 class : Class
                 order : Order
                family : Family
                 genus : Genus
               species : Species
                 tribe : Tribe
              varietas : varietas
         species group : Species group
      species subgroup : Species subgroup
               no rank : None
          superkingdom : Superkingdom
           superphylum : Superphylum
            superclass : Superclass
            superorder : Superorder
           superfamily : Superfamily
            subkingdom : Subkingdom
             subphylum : Subphylum
              subclass : Subclass
              suborder : Suborder
             subfamily : Subfamily
              subgenus : Subgenus
            subspecies : Subspecies
              subtribe : Subtribe
            infraclass : Infraclass
            infraorder : Infraorder
             parvorder : Parvorder
    Find taxons at rank [kingdom,phylum,class,order,family,genus,species]: *
    Taxon output file [9606.excel]:

Go to the output files for this example

## Command line arguments

    Get parents of taxon(s)
    Version: EMBOSS:6.6.0.0

       Standard (Mandatory) qualifiers:
      [-taxons]            taxon      Taxon filename and optional format, or
                                      reference (input query)
      [-rank]              menu       [kingdom,phylum,class,order,family,genus,species]
                                      Multiple ranks can be specified, or '*' for
                                      all (Values: kingdom (Kingdom); phylum
                                      (Phylum); class (Class); order (Order);
                                      family (Family); genus (Genus); species
                                      (Species); tribe (Tribe); varietas
                                      (varietas); species group (Species group);
                                      species subgroup (Species subgroup); no rank
                                      (None); superkingdom (Superkingdom);
                                      superphylum (Superphylum); superclass
                                      (Superclass); superorder (Superorder);
                                      superfamily (Superfamily); subkingdom
                                      (Subkingdom); subphylum (Subphylum);
                                      subclass (Subclass); suborder (Suborder);
                                      subfamily (Subfamily); subgenus (Subgenus);
                                      subspecies (Subspecies); subtribe
                                      (Subtribe); infraclass (Infraclass);
                                      infraorder (Infraorder); parvorder
                                      (Parvorder))
      [-outfile]           outtaxon   (no help text) outtaxon value

       Additional (Optional) qualifiers: (none)
       Advanced (Unprompted) qualifiers:
       -hidden             boolean    [N] Show taxons hidden in GenBank

       Associated qualifiers:

       "-taxons" associated qualifiers
       -iformat1           string     Input taxonomy format
       -iquery1            string     Input query fields or ID list
       -ioffset1           integer    Input start position offset
       -idbname1           string     User-provided database name

       "-outfile" associated qualifiers
       -odirectory3        string     Output directory
       -oformat3           string     Taxonomy output format

       General qualifiers:
       -auto               boolean    Turn off prompts
       -stdout             boolean    Write first file to standard output
       -filter             boolean    Read first file from standard input, write
                                      first file to standard output
       -options            boolean    Prompt for standard and additional values
       -debug              boolean    Write debug output to program.dbg
       -verbose            boolean    Report some/full command line options
       -help               boolean    Report command line options and exit. More
                                      information on associated and general
                                      qualifiers can be found with -help -verbose
       -warning            boolean    Report warnings
       -error              boolean    Report errors
       -fatal              boolean    Report fatal errors
       -die                boolean    Report dying program messages
       -version            boolean    Report version number and exit

Qualifier | Type | Description | Allowed values | Default
--- | --- | --- | --- | ---
Standard (Mandatory) qualifiers
[-taxons] (Parameter 1) | taxon | Taxon filename and optional format, or reference (input query) | NCBI taxonomy entries |
[-rank] (Parameter 2) | list | Multiple ranks can be specified, or '*' for all |
kingdom | (Kingdom)
phylum | (Phylum)
class | (Class)
order | (Order)
family | (Family)
genus | (Genus)
species | (Species)
tribe | (Tribe)
varietas | (varietas)
species group | (Species group)
species subgroup | (Species subgroup)
no rank | (None)
superkingdom | (Superkingdom)
superphylum | (Superphylum)
superclass | (Superclass)
superorder | (Superorder)
superfamily | (Superfamily)
subkingdom | (Subkingdom)
subphylum | (Subphylum)
subclass | (Subclass)
suborder | (Suborder)
subfamily | (Subfamily)
subgenus | (Subgenus)
subspecies | (Subspecies)
subtribe | (Subtribe)
infraclass | (Infraclass)
infraorder | (Infraorder)
parvorder | (Parvorder)
| kingdom,phylum,class,order,family,genus,species
[-outfile] (Parameter 3) | outtaxon | (no help text) outtaxon value | NCBI taxonomy entries |
Additional (Optional) qualifiers
(none)
Advanced (Unprompted) qualifiers
-hidden | boolean | Show taxons hidden in GenBank | Boolean value Yes/No | No
Associated qualifiers
"-taxons" associated taxon qualifiers
-iformat1 -iformat_taxons | string | Input taxonomy format | Any string |
-iquery1 -iquery_taxons | string | Input query fields or ID list | Any string |
-ioffset1 -ioffset_taxons | integer | Input start position offset | Any integer value | 0
-idbname1 -idbname_taxons | string | User-provided database name | Any string |
"-outfile" associated outtaxon qualifiers
-odirectory3 -odirectory_outfile | string | Output directory | Any string |
-oformat3 -oformat_outfile | string | Taxonomy output format | Any string |
General qualifiers
-auto | boolean | Turn off prompts | Boolean value Yes/No | N
-stdout | boolean | Write first file to standard output | Boolean value Yes/No | N
-filter | boolean | Read first file from standard input, write first file to standard output | Boolean value Yes/No | N
-options | boolean | Prompt for standard and additional values | Boolean value Yes/No | N
-debug | boolean | Write debug output to program.dbg | Boolean value Yes/No | N
-verbose | boolean | Report some/full command line options | Boolean value Yes/No | Y
-help | boolean | Report command line options and exit. More information on associated and general qualifiers can be found with -help -verbose | Boolean value Yes/No | N
-warning | boolean | Report warnings | Boolean value Yes/No | Y
-error | boolean | Report errors | Boolean value Yes/No | Y
-fatal | boolean | Report fatal errors | Boolean value Yes/No | Y
-die | boolean | Report dying program messages | Boolean value Yes/No | Y
-version | boolean | Report version number and exit | Boolean value Yes/No | N

## Input file format

The input is a standard EMBOSS taxonomy query.

The expected source of taxonomy information is the NCBI Taxonomy database "taxon" which is available as a standard database in all EMBOSS installations.

Data can also be read from taxonomy output in "ncbi" format written by an EMBOSS application.

See: http://emboss.sf.net/docs/themes/TaxonFormats.html for further information on taxon formats.

### Input files for usage example

'ttax:9606' is a sequence entry in the example taxonomy database 'ttax'

### Database entry: ttax:9606

    id: 9606
    parent: 9605
    rank: species
    emblprefix: HS
    division: 5
    divflag: 1
    gencode: 1
    gcflag: 1
    mitocode: 2
    mgcflag 1
    hidden: 1
    nosequence: 1
    scientific name: Homo sapiens
    authority: Homo sapiens Linnaeus, 1758
    genbank common name: human
    common name: man

## Output file format

The output is a standard EMBOSS taxon file.

The results can be output in one of several styles by using the command-line qualifier `-oformat xxx`, where 'xxx' is replaced by the name of the required format. The available format names are: ncbi, ebi, tax, excel.

See: http://emboss.sf.net/docs/themes/TaxonFormats.html for further information on taxon formats.

### Output files for usage example

### File: 9606.excel

    9605	207598	genus	N	Homo
    9604	314295	family	N	Hominidae
    9443	314146	order	N	Primates
    40674	32524	class	N	Mammalia
    7711	33511	phylum	N	Chordata
    33208	33154	kingdom	N	Metazoa

### Output files for usage example 2

### File: 9606.excel

    9605	207598	genus	N	Homo
    9604	314295	family	N	Hominidae
    9526	314293	parvorder	N	Catarrhini
    376913	9443	suborder	N	Haplorrhini
    9443	314146	order	N	Primates
    314146	9347	superorder	N	Euarchontoglires
    9347	32525	no rank	N	Eutheria
    40674	32524	class	N	Mammalia
    117571	117570	no rank	N	Euteleostomi
    7742	89593	no rank	N	Vertebrata
    89593	7711	subphylum	N	Craniata
    7711	33511	phylum	N	Chordata
    33208	33154	kingdom	N	Metazoa
    2759	131567	superkingdom	N	Eukaryota

### Output files for usage example 3

### File: 9606.excel

    9605	207598	genus	N	Homo
    207598	9604	subfamily	Y	Homininae
    9604	314295	family	N	Hominidae
    314295	9526	superfamily	Y	Hominoidea
    9526	314293	parvorder	N	Catarrhini
    314293	376913	infraorder	Y	Simiiformes
    376913	9443	suborder	N	Haplorrhini
    9443	314146	order	N	Primates
    314146	9347	superorder	N	Euarchontoglires
    9347	32525	no rank	N	Eutheria
    32525	40674	no rank	Y	Theria
    40674	32524	class	N	Mammalia
    32524	32523	no rank	Y	Amniota
    32523	8287	no rank	Y	Tetrapoda
    8287	117571	no rank	Y	Sarcopterygii
    117571	117570	no rank	N	Euteleostomi
    117570	7776	no rank	Y	Teleostomi
    7776	7742	superclass	Y	Gnathostomata
    7742	89593	no rank	N	Vertebrata
    89593	7711	subphylum	N	Craniata
    7711	33511	phylum	N	Chordata
    33511	33316	no rank	Y	Deuterostomia
    33316	33213	no rank	Y	Coelomata
    33213	6072	no rank	Y	Bilateria
    6072	33208	no rank	Y	Eumetazoa
    33208	33154	kingdom	N	Metazoa
    33154	2759	no rank	Y	Fungi/Metazoa group
    2759	131567	superkingdom	N	Eukaryota
    131567	1	no rank	Y	cellular organisms

## Data files

The NCBI Taxonomy Ontology is included in EMBOSS as local database taxon.

## Notes

None.

## References

None.

## Warnings

None.

## Diagnostic Error Messages

None.

## Exit status

It always exits with status 0.

## Known bugs

None.

## See also

Program name | Description
--- | ---
taxget | Get taxon(s)
taxgetdown | Get descendants of taxon(s)
taxgetspecies | Get all species under taxon(s)
taxgetup | Get parents of taxon(s)

## Author(s)

Peter Rice
European Bioinformatics Institute, Wellcome Trust Genome Campus, Hinxton, Cambridge CB10 1SD, UK

Please report all bugs to the EMBOSS bug team (emboss-bug © emboss.open-bio.org) not to the original author.

## History

## Target users

This program is intended to be used by everyone and everything, from naive users to embedded scripts.

## Comments

None