jplace format (skbio.io.format.jplace)#

The jplace format (jplace) stores the results of a phylogenetic placement: the assignment of query sequences (e.g., metagenomic reads) onto the edges of a fixed reference tree [1]. It is a JSON document produced by placement tools such as pplacer, EPA-ng, and APPLES.

Format Support#

Has Sniffer: Yes

Reader

Writer

Object Class

Yes

Yes

skbio.tree.BPTree

Format Specification#

A jplace file is a JSON object with the following top-level members [1]:

  • tree: a Newick string in which each edge is annotated with an integer edge number, delimited by {}. ([] is treated as a standard Newick comment and ignored.)

  • placements: a list of placement records. Each record has a p member (a list of placement rows, each row a list matching fields) and an n member (a list of query/fragment names).

  • fields: the column names for the rows in p (must include edge_num).

  • version: the jplace format version.

  • metadata: free-form metadata (e.g., the invocation command line).

Reading a jplace file yields the reference tree as a BPTree, the succinct balanced-parentheses representation that carries the {} edge numbers and scales to the large reference trees typical of placement studies. The placement records themselves are dropped; only the reference tree is returned.

Writing a BPTree produces a jplace document containing the reference tree (with its {} edge numbers) and an empty placements list – a BPTree holds a reference tree but no placements. The tree parse and serialization run in scikit-bio’s compiled backend, so throughput is preserved for large files.

Caveats#

  • Edge numbers use {} only. [] is treated as a standard Newick comment.

  • A jplace document written from an edge-number-less BPTree repeats {0} on every edge; the round trip is only meaningful when the tree carries edge numbers (as a tree read from jplace does).

Examples#

Read the reference tree of a jplace file into a BPTree (placements are dropped):

from skbio.tree import BPTree
tree = BPTree.read("placement.jplace", format="jplace")

Write a BPTree back out as a (placement-less) jplace file:

tree.write("reference.jplace", format="jplace")

References#

[1] (1,2)

Matsen FA, Hoffman NG, Gallagher A, Stamatakis A. (2012). A format for phylogenetic placements. PLoS ONE 7(2): e31009.