Package: portia-grn
PORTIALightning-fast Gene Regulatory Network (GRN) inference tool.
This repository also hosts our graph-theoretical Normalised Discounted Cumulative Gain (gtNDCG) score metric for evaluating inferred GRNs. Usage of both PORTIA and gtNDCG is explained below.PORTIA builds on power transforms and covariance matrix inversion to approximate GRNs, and is orders of magnitude faster than other existing tools (as of August 2021).How to use itInstall the dependencies:pip3-rrequirements.txtFor using the end-to-end inference algorithm, install dependencies fromrequirements-etel.txtinstead.Install the package:python3setup.pyinstallPORTIA and gtNDCG can be run either:From Python, using the library directlyAs standalone scriptsUsing the libraryIn Python, create an empty dataset:importportiaasptdataset=pt.GeneExpressionDataset()Gene expression measurements can be added with theGeneExpressionDataset.addmethod.datamust be an iterable (list, NumPy array, etc) of lengthn_genescontaining floating point numbers.exp_id=1data=[0,0,...,1.03424,1.28009]dataset.add(pt.Experiment(exp_id,data))forexp_id,datainenumerate(your_data):dataset.add(pt.Experiment(exp_id,data))Gene knock-out experiments can be encoded using theknockoutoptional parameter.dataset.add(pt.Experiment(exp_id,data,knockout=[gene_idx]))wheregene_idxis the (0-based) index of the gene being knocked out. Dual/multiple knock-out experiments are supported, but won't help in the inference process in any way.Run PORTIA on your dataset:M_bar=pt.run(dataset,method='fast')The outputM_baris a matrix, where each elementM_bar[i, j]is a score in the range [0, 1] reflecting the confidence about geneibeing a regulator for target genej. A whitelist of putative transcription factors can be specified with thetf_idxargument.tf_idxmust be a (0-based) list of gene indices.M_bar=pt.run(dataset,tf_idx=tf_idx,method='fast')The mode of regulation (sign of regulatory link) can be retrieved by passing thereturn_signargument. When set to True, both inferred network and sign matrix will be returned. Sign matrixSis a matrix of same shape asM_bar, where 1 stands for activition, -1 stands for inhibition, and 0 stands for no (self-)regulation.M_bar,S=pt.run(dataset,tf_idx=tf_idx,method='fast',return_sign=True)Finally, rank and store the results in a text file.gene_namesis the list of your genes, provided in the correct order.withopen('your_destination/results.txt','w')asf:forgene_a,gene_b,scoreinpt.rank_scores(M_bar,gene_names,limit=10000):f.write(f'{gene_a}\t{gene_b}\t{score}\n')Scoring of the inferred GRN using our gtNDCG metric is done as follows:tf_mask=np.zeros(n_genes,dtype=bool)tf_mask[tf_idx]=Trueres=graph_theoretic_evaluation(tmp_filepath,G_target,G_pred,tf_mask=tf_mask)wheretmp_filepathis the name of the temporary file where to store accessibility matrices, in case the same goldstandard network is used multiple times in a row (e.g. to compare GRN inference methods). IfNoneis provided, no temporary file will be written.G_predandG_predare NumPy matrices. NaN elements correspond to missing values. For the goldstandard network, a missing value means that there is no experimental evidence for a given gene pair (even for the absence of regulation). For the inferred network, a missing value means the absence of prediction. ForG_target, 1 corresponds to a regulatory relationship and 0 the absence of such relation. Scores inG_predare real-valued.Run standalone scripts (command line)test-datafolder contains in silico-generated data meant for testing PORTIA and the gtNDCG metric scoring algorithm. The following command line infers a GRN from a gene expression dataset, and stores it intest-data/out1.txt:python3 run.py test-data/dataset1.expression.txt --out test-data/out1.txtA list of putative TFs and knock-out experiments can be pointed out in separate files:python3 run.py test-data/dataset2.expression.txt --kos test-data/dataset2.kos.txt --tfs test-data/dataset2.tfs.txt --out test-data/out2.txtShrinkage parameters can be specified with the arguments--lambda1 0.8and--lambda2 0.05. Providing the--signedargument will make the predictions signed, and will thus contain negative values. For more information on the other arguments, you can access the help by running therun.pyscript without argument.Scoring the inferred network with the gtNDCG metric requires a goldstandard network:python3 run_gt_ndcg.py test-data/out1.txt test-data/dataset1.goldstandard.txt --out test-data/results1Results will be placed in foldertest-data/results1.When a list of TFs is available, it should be provided to the script as well:python3 run_gt_ndcg.py test-data/out2.txt test-data/dataset2.goldstandard.txt --tfs test-data/dataset2.tfs.txt --out test-data/results1