BBGLab interface for an OncoTree
BGOncoTree is a Python package to standardize the use of the OncoTree within the BBGLab.
BGOncoTree works with Python 3.5+ and can be installed with pip:
pip install bgoncotree
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
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'): ...
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.
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
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.