The unipept taxa2tree command takes one or more NCBI taxon IDs as input and returns the taxonomic tree of these taxa as output. All this information is fetched by doing API-requests to the Unipept server.

Input

The unipept taxa2tree command expects NCBI taxon IDs as input. The source of this input can be command line arguments, a file, or standard input. If input is supplied using multiple sources at the same time, the order of priority as described above is used.

Command line arguments

If input is supplied using command line arguments, the taxon IDs must be separated by spaces.

Example
$ unipept taxa2tree 817 329854 1099853
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]

File input

Use the --input parameter to specify a file to use as input. If input is supplied using a file, a single taxon id (and optionally the occurrences of this taxon, delimited by comma) per line is expected.

Example
$ cat input.txt
817,5
329854,4
1099853,78
$ unipept taxa2tree --input input.txt
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]

Standard input

If the command is run without arguments and no file is specified, unipept taxa2tree will read its input from standard input. When standard input is used, a single taxon id per line is expected.

Example
$ cat input.txt
817,5
329854,4
1099853,78
$ cat input | unipept taxa2tree
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]

Output

The unipept taxa2tree command outputs the taxonomic tree for a given set of taxon IDs. By default, the NCBI taxon id, taxon name, taxonomic rank, count and self count of each node in the tree are returned in the json format. Consult the API documentation for a detailed list of output fields. By default, output is generated in json format. By using the --format parameter, the format can be changed into html or an url. The output can be written to a file or to standard output.

File output

Use the --output parameter to specify an output file. If the file aready exists, the output will be appended to the end of the file.

$ unipept taxa2tree --output output.txt 817 329854 1099853
$ cat output.txt
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]

Standard output

If no output file is specified, unipept taxa2tree will write its output to standard output.

Example
$ unipept taxa2tree 817 329854 1099853
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]
$ unipept taxa2lca 817 329854 1099853 > output.txt
$ cat output.txt
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]

Command-line options

--input / -i Specify an input file

All Unipept CLI commands can process input from 3 sources: command line arguments, a file, or standard input. The optional --input option allows you to specify an input file. The file should contain a single taxon per line, or a taxon and the associated count (comma delimited).

Example
$ cat input.txt
817,5
329854,4
1099853,78
$ unipept taxa2tree --input input.txt
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]

--output / -o Specify an output file

By default, the unipept commands write their output to standard output. Using the optional --output option allows you to specify a file to write the output to. If the file already exists, the output will be appended; if it doesn't, a new file will be created.

Example
$ unipept taxa2tree --output output.txt 817 329854 1099853
$ cat output.txt
[{"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]}]
        

--format / -f Specify the output format

By default, the Unipept CLI taxa2tree command returns its output in json format. The --format option allows you to select another format. Supported formats are json, html, and url.

Example
$ unipept taxa2tree --format url 817 329854 1099853
https://bl.ocks.org/2c8279c53874528aa3f1ddd018953e60
$ unipept taxa2lca --format html 817 329854 1099853
<!DOCTYPE html>
<html>
<head>
  <script src="https://code.jquery.com/jquery-3.5.0.slim.min.js" integrity="sha256-MlusDLJIP1GRgLrOflUQtshyP0TwT/RHXsI1wWGnQhs=" crossorigin="anonymous"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/d3/3.5.17/d3.min.js" integrity="sha256-dsOXGNHAo/syFnazt+KTBsCQeRmlcW1XKL0bCK4Baec=" crossorigin="anonymous"></script>
  <script src="https://cdn.jsdelivr.net/npm/unipept-visualizations@1.7.3/dist/unipept-visualizations.min.js" integrity="sha256-X40vVFfGbi55N33QuZEMmw3nxi7Swljq5OJ1UHWdBhQ=" crossorigin="anonymous"></script>
</head>
<body>
<div id="sunburst"></div>
<script>
    const data = {"id":1,"name":"Organism","rank":"root","data":{"count":3,"self_count":0},"children":[{"id":2,"name":"Bacteria","rank":"superkingdom","data":{"count":3,"self_count":0},"children":[{"id":976,"name":"Bacteroidetes","rank":"phylum","data":{"count":3,"self_count":0},"children":[{"id":200643,"name":"Bacteroidia","rank":"class_","data":{"count":3,"self_count":0},"children":[{"id":171549,"name":"Bacteroidales","rank":"order","data":{"count":3,"self_count":0},"children":[{"id":815,"name":"Bacteroidaceae","rank":"family","data":{"count":2,"self_count":0},"children":[{"id":816,"name":"Bacteroides","rank":"genus","data":{"count":2,"self_count":0},"children":[{"id":817,"name":"Bacteroides fragilis","rank":"species","data":{"count":1,"self_count":1},"children":[]},{"id":329854,"name":"Bacteroides intestinalis","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]},{"id":2005519,"name":"Barnesiellaceae","rank":"family","data":{"count":1,"self_count":0},"children":[{"id":1348911,"name":"Coprobacter","rank":"genus","data":{"count":1,"self_count":0},"children":[{"id":1099853,"name":"Coprobacter fastidiosus","rank":"species","data":{"count":1,"self_count":1},"children":[]}]}]}]}]}]}]}]};

    function tooltipContent(d) {
        return '<b>' + d.name + '</b> (' + d.rank + ')<br/>' +
            (!d.data.self_count ? '0' : d.data.self_count) +
            (d.data.self_count && d.data.self_count === 1 ? ' sequence' : ' sequences') + ' specific to this level<br/>' +
            (!d.data.count ? '0' : d.data.count) +
            (d.data.count && d.data.count === 1 ? ' sequence' : ' sequences') + ' specific to this level or lower';
    };

    const options = {
        getTooltip: tooltipContent
    };

    $("#sunburst").sunburst(data, options);
</script>
</body>
</html>

--help / -h Display help

This flag displays the help.