Check out the preprint!

BIONIC (Biological Network Integration using Convolutions) is a deep-learning based biological network integration algorithm that extends the graph convolutional network (GCN) to learn integrated features for genes or proteins across input networks. BIONIC produces high-quality gene features and is scalable both in number of networks and network size.

An overview of BIONIC can be seen below.

1. Multiple networks are input into BIONIC
2. Each network is passed through its own graph convolutional encoder where network-specific gene features are learned based the network topologies. These features are summed to produce integrated gene features which capture salient topological information across input networks. The integrated features can then be used for downstream tasks, such as gene-gene functional linkage prediction, module detection (clustering) and gene function prediction.
3. In order to train and optimize the integrated gene features, BIONIC first decodes the integrated features into a reconstruction of the input networks.
4. BIONIC then minimizes the difference between this reconstruction and the input networks (i.e. reconstruction error) by updating its weights to learn gene features that capture relevant topological information.

• BIONIC is implemented in Python 3.8 and uses PyTorch and PyTorch Geometric.

• BIONIC can run on the CPU or GPU. The CPU distribution will get you up and running quickly, but the GPU distributions are significantly faster for large models (when run on a GPU).

• Currently, we provide wheels for CPU, CUDA 9.2, CUDA 10.1 and CUDA 10.2 on Linux, and CPU, CUDA 10.1 and CUDA 10.2 on Windows.

NOTE: If you run into any problems with installation, please don't hesitate to open an issue.

If you are installing a CUDA capable BIONIC wheel (i.e. not CPU), first ensure you have a CUDA capable GPU and the drivers for your GPU are up to date. Then, if you don't have CUDA installed and configured on your system already, download, install and configure a BIONIC compatible CUDA version. Nvidia provides detailed instructions on how to do this for both Linux and Windows.

1. Before installing BIONIC, it is recommended you create a virutal Python 3.8 environment using tools like the built in venv command, or Anaconda.

2. Make sure your virtual environment is active, then install BIONIC by running

   $ pip install bionic_model==${VERSION}+${CUDA} -f https://bowang-lab.github.io/BIONIC/wheels.html
   

   where ${VERSION} is the version of BIONIC you want to install (currently 0.1.0) and ${CUDA} is one of cpu, cu92, cu101, cu102, corresponding to the CPU, CUDA 9.2, CUDA 10.1 and CUDA 10.2 versions, respectively. Note, as above, that cu92 is not available on Windows. NOTE: There is a known bug in certain versions of pip which may result in a No matching distribution error. If this occurs, install pip==19.3.1 and try again.

3. Test BIONIC is installed properly by running

   $ bionic --help
   

   You should see a help message.

1. If you don't already have it, install Poetry.

2. Create a virtual Python 3.8 environment using tools like the built in venv command, or Anaconda. Make sure your virutal environment is active for the following steps.

3. Install PyTorch 1.6.0 for your desired CUDA version as follows:

   $ pip install torch==1.6.0+${CUDA} -f https://download.pytorch.org/whl/torch_stable.html
   

   where ${CUDA} is the one of the options listed in step 2 of installing from wheel above.

4. Install PyTorch 1.6.0 compatible PyTorch Geometric dependencies for your desired CUDA version as follows:

   $ pip install torch-scatter==2.0.6 torch-sparse==0.6.9 torch-cluster==1.5.9 -f https://pytorch-geometric.com/whl/torch-1.6.0+${CUDA}.html
   $ pip install torch-geometric==1.6.1
   

   where ${CUDA} is the one of the options listed in step 2 of installing from wheel above.

5. Clone this repository by running

   $ git clone https://github.com/bowang-lab/BIONIC.git
   

6. Make sure you are in the BIONIC root directory and run

   $ poetry install
   

7. Test BIONIC is installed properly by running

   $ bionic --help
   

   You should see a help message.

BIONIC runs by passing in a configuration file - a JSON file containing all the relevant model file paths and hyperparameters. You can have a uniquely named config file for each integration experiment you want to run. An example config file can be found here.

The configuration keys are as follows:

By default, only the names key is required, though it is recommended you experiment with different hyperparameters so BIONIC suits your needs.

Input networks are text files in edgelist format, where each line consists of two gene identifiers and (optionally) the weight of the edge between them, for example:

geneA geneB 0.8
geneA geneC 0.75
geneB geneD 1.0

If the edge weight column is omitted, the network is considered binary (i.e. all edges will be given a weight of 1). The gene indentifiers and edge weights are delimited with spaces by default. If you have network files that use different delimiters, this can be specified in the config file by setting the delimiter key. BIONIC assumes all networks are undirected and enforces this in its preprocessing step.

To run BIONIC, do

$ bionic path/to/your_config_file.json

Results will be saved in the out_name directory as specified in the config file.

The configuration parameters table provides usage tips for many parameters. Additional suggestions are listed below. If you have any questions at all, please open an issue.

• learning_rate and epochs have the largest effect on training time and performance.
• learning_rate should generally be reduced as you integrate more networks. If the model loss suddenly increases by an order of magnitude or more at any point during training, this is a sign learning_rate needs to be lowered.
• epochs should be increased as you integrate more networks. 10000-15000 epochs is not unreasonable for 50+ networks.
• The reconstruction loss may look like it's bottoming out early on but the model will continue improving feature quality for an unintuitively long time afterward.
• embedding_size directly affects the quality of learned features. We found the default 512 works for most networks, though it's worth experimenting with different sizes for your application. In general, higher embedding_size will encode more information present in the input networks but at the risk of also encoding noise.
• gat_shapes.dimension should be increased for networks with many nodes. We found 128 - 256 is a good size for human networks, for example.

• BIONIC runs faster and performs better with sparser networks - as a general rule, try to keep the average node degree below 50 for each network.

Supplementary files can be found here.