BioPathAI 0.1.0

Description:

BioPathAI 0.1.0

BioPathAI
A Python tool for the analysis of biological pathways with machine learning techniques
Requirements
We developed BioPathAI as a Python 3.6 package with the following requirements:

pandas (version >=1.3.5)
scikit-learn (version >=0.22.1)
tabulate (version >=0.9.0)

Install
The tool is available through pip on The Python Package Index at https://pypi.org/project/BioPathAI/.
It can be installed by running the following command on your terminal:
pip install biopathai

Input
BioPathAI takes two different types of data in input.
Pathways definition file
The first one is a tab-separated-values file with the list of patways with their ID, source, and genes, as shown in the following example:
#pathway external_id source hgnc_symbol_ids
Rosiglitazone Pharmacokinetic Pathway PA165816969 PharmGKB SLCO1B1,CYP2C8,CYP2C9
spermine biosynthesis ARGSPECAT-PWY HumanCyc SMS,AMD1
Plasma lipoprotein assembly, remodeling, and clearance WP4129 Wikipathways APOA4,APOA5,APOC2,CIDEC,FGF21
Signaling by Overexpressed Wild-Type EGFR in Cancer R-HSA-5638302 Reactome EGFR,EGF
...


Note
The previous example is part of the Consensus Pathway Database available at http://cpdb.molgen.mpg.de/.
Please note that, since there could be multiple pathways with the same name but from different sources, all the four columns are required by BioPathAI in order to build a unique identifier for each pathway.

Links to the expression data
BioPathAI also takes in input another tab-separated-values file with the list of links to the actual data with the gene expression values and their class (e.g., case or control), like in the example below:
#path class
~/acf1ec71-46a5-4e7b-84b1-55203bca29d8.bed tumoral
~/429b50eb-316f-459c-bc3a-0aca6e6dba46.bed tumoral
~/eb9e415f-0545-4e97-ad35-b56b0f3db79b.bed normal
~/827431d3-e25a-45b6-9b0f-5732501e2a5b.bed tumoral
~/09f570eb-a751-41db-9511-300be228f24e.bed normal
...


Note
The files listed in the first colum of the previous example must contains at least two columns, one with the gene names in the same format as reported in the pathways definition file (i.e., Gene Symbols in this particular example), the other one with the actual gene expression values.
In this example we reported a few free-BED files retrieved from the OpenGDC public FTP repository at ftp://geco.deib.polimi.it/opengdc/.

Usage
Here is a list of available options:



Option
Default
Mandatory
Description




--classifier-nproc
1

Make the execution of the classification algorithms parallel


--classifier
randomforest

Select a classification algorithm. Possible values: decisiontree, gaussianprocess, nearestneighbors, neuralnet, randomforest, and svm


--evaluate-in-memory
False

Do not dump results on file during the evaluation process


--folds
10

Number of folds for the cross-validation


--how-many
1000

Number of random pathways


--in-file

⚑
Path to the input tab-separated-values file with the list of paths to the data files and classes (e.g. control/case)


--in-key-pos

⚑
Position of keys in the input data files (e.g., column with the Gene Symbols)


--in-sep
\t

Field separator of input data files


--in-value-pos

⚑
Position of values in the input data files (e.g., column with the expression values)


--nproc
1

Make it parallel


--out-folder

⚑
Path to the output folder


--pathways

⚑
Path to the pathways definition file in tsv format


--prepare-in-memory
False

Do not dump the pathways matrices on file and keep them in memory


--random-classes
False

Shuffle classes


--random-pathways
False

Generate random pathways


--verbose
False

Print results on the stdout



This is an example of command line:
biopathai --pathways ~/<pathways-file>.tsv --in-file ~/<data-files>.tsv --in-key-pos 0 --in-value-pos 1 --prepare-in-memory --evaluate-in-memory --out-folder ~/<output-folder>


Note
Please note that this command will produce a table with the accuracies reached by the specified classification algorithm on the real pathway matrices with gene expression values. In order to produce the same table for the random pathway matrices, you can simply add the following arguments to the command line --random-classes --how-many 1000. This will shuffle the classes a thousand times. If you want to generate pathways with a random combination of genes, you can replace --random-classes with --random-pathways.

Output
BioPathAI produces a CSV file with the list of pathways IDs with the accuracy reached by the specified machine learning algorithm on the cross-validated models built on the gene expression values.
In order to produce the p-values and rank the pathways according to their relevance in relation to a specific disease or condition, BioPathAI provides a subroutine called biopathai_pvalue that can be executed with the following command:
python biopathai_pvalue.py --real-accuracies ~/<biopathai-real-results>.csv --random-accuracies ~/<biopathai-random-results>.csv --dump ~/<output-pvalues-file>.csv

Please note that you have to run BioPathAI twice. The first time on the real pathways, then on the random pathways matrices (by specifying --random-classes or --random-pathways as explained above).
Credits
Please credit out work in your manuscript by citing:

Manuscript in preparation

Support and contributions
Long-term discussion and bug reports are maintained via GitHub Issues, while code review is managed via GitHub Pull Requests.
Please, (i) be sure that there are no existing issues/PR concerning the same bug or improvement before opening a new issue/PR; (ii) write a clear and concise description of what the bug/PR is about; (iii) specifying the list of steps to reproduce the behavior in addition to versions and other technical details is highly recommended.