bgoncotree 0.5

BBGLab interface for an OncoTree

BGOncoTree is a Python package to standardize the use of the OncoTree within the BBGLab.

Installation

BGOncoTree works with Python 3.5+ and can be installed with pip:

pip install bgoncotree

Usage

Any use of BGOncoTree requires to initialize the tree:

from bgoncotree.main import BGOncoTree

tree = BGOncoTree()

BGOncoTree accepts a file as argument if you want to provide your own tree.

Each node is composed by:

• id: short identifier of the node (e.g. ALL)

• parent: ancestor node

• children: list of descendent nodes

• synonyms: list of alternative names that can be used to search for this node

• name: first provided synonym or node id

Python

The first thing to do is initialize the BGOncoTree object:

tree = BGOncoTree()

The BGOncoTree object is a dictionary that you can query to get each node:

node = tree['CANCER']

Using the ID of the node or any synonym you can find the node:

node = tree.find('clear cell sarcoma')

To explore the tree, you can use the iter_from method:

for node, level in tree.iter_from(tree['ALL'], descending=True):
        ...

The level is simply an integer indicating the level of nested with respect to the starting_node. If you want to explore the full tree, you can get the root node as:

root_node = tree.root

The methods descendants and ancestors do the same as iter_from but you do not need to indicate the descending flag, the level is not returned and node can also be a string. E.g.:

for node in tree.descendants('ALL'):
        ...

Important

iter_from`, descendants and ancestors methods return the starting node.

There are two other methods that you can make use of. search can be used to search for all nodes containing a word in their names. E.g.:

for node in tree.search('acute'):
        ...

The get method is useful if you expect only one result from a search. E.g.:

node = tree.get('Cholangiocarcinoma')

This method will raise an exception if none or more than 1 items are found.

Command line

The command line provides two utilities to explore the tree bgoncotree ancestors and bgoncotree descendants. Output can be formatted in json, and you can also set a recursion limit.

See first one level of childs of HEMATO node:

bgoncotree descendants --node HEMATO --json --limit 2

In addition, the same search function as in Python can be called from the command line as:

bgoncotree search acute

Tab completion can be enabled adding eval "$(_BGONCOTREE_COMPLETE=source bgoncotree)" to your .bashrc file as explained in the bash completion section of Click

Defining your own tree

BGOncoTree uses bgdata to get the most recent version of the oncotree used in the lab. However, you can pass a file with your own oncotree:

from bgoncotree.main import BGOncoTree

tree = BGOncoTree(file)

If you are interested in creating your own oncotree, you need a tsv file with 2 columns: ID and PARENT. Each node can only have 1 parent, and there must but one node without a parent: the root node.

You can provide an additional extra column NAMES with a comma separated list of synonyms for each node. The first name will be used as the name to display.

You can validate your tree using the command line:

bgoncotree validate my_tree.tsv