Package: bicon
BiCoN: network-constrained biclustering of patients and multi-omics dataTable of contentsGeneral infoInstallationData inputMain functionsExampleQuality controlCiteContactGeneral infoUnsupervised learning approaches are frequently employed to identify patient subgroups and biomarkers such as disease-associated genes. Biclustering is a powerful technique often used with expression data to cluster genes along with patients. However, the genes forming biclusters are often not functionally related, complicating interpretation of the results.To alleviate this, we developed the network-constrained biclustering approach BiCoN which(i)restricts biclusters to functionally related genes connected in molecular interaction networks and(ii)maximizes the expression difference between two subgroups of patients.InstallationTo install the package from PyPI please run:pip install biconTo install the package from git:git clone https://github.com/biomedbigdata/BiCoNpython setup.py installData inputThe algorithm needs as an input a matrix with gene expression/methylation/any other numerical data and one file with a network.Any gene IDs can be used (see results processing)Numerical dataNumerical data is accepted in the following format:genes as rows.patients as columns.first column - genes IDs (can be any IDs).For instance:Unnamed: 0GSM748056GSM748059...GSM748278GSM748279GSM146598914540.0537690.117412...-0.392363-1.870838-1.432554201931-0.6182790.278637...0.803541-0.5149472.36192587610.215820-0.343865...0.7004300.073281-0.9776562703-0.5047011.295049...1.8619720.6018080.19101326207-0.626415-0.646977...2.3317242.339122-0.100924There are 2 examples of gene expression datasets that can be placed in the "data" folderGSE30219 - a Non-Small Cell Lung Cancer dataset from GEO for patients with either adenocarcinoma or squamous cell carcinoma.TCGA pan-cancer dataset with patients that have luminal or basal breast cancer.
Both can be foundhereNetworkAn interaction network should be present as a table with two columns that represent two interacting genes.Without a header!For instance:6416231864165371641635164164096416593264161956There is an example of a PPI network from BioiGRID with experimentally validated interactionshere.Main functionsHere we give a general description of the main functions provided. Please note, that all functions are annotated with dockstrings and therefore the full information can be found withhelp()method, e.g.help(results.save).1.data_preprocessing(path_expr, path_net, log2 = False, zscores = True, size = 2000, no_zero = None, formats = [])Parameters:path_to_expr:string, path to the numerical datapath_to_net:string, path to the network filelog2:bool, (default = False), indicates if log2 transformation should be applied to the datasize:int, optional (default = 2000)determines the number of genes that should be pre-selected by variance for the analysis. Shouldn't be higher than 5000.no_zero: (default - none) indicate the fraction of allowed non-zero values for each patient. For instance no_zero = 0.8 means that all genes which have no expression for at least 80% of patients will be removed from the analysisformats:list(defailt - determined automatically), list of formats for gene expression matrix and PPI table. It is advisable to provide formats to avoid mistakes in files reading. For example, if the gene expression matrix is given in .csv format and PPI in .tsv format, then format = ["csv", "tsv"]Returns:GE:pandas data frame, processed expression dataG:networkX graph, processed network datalabels:dict, for mapping between real genes/patients IDs and the internal onesrev_labels:dict, additional dictionary for mapping between real genes/patients IDs and the internal onesBiCoN*(GE,G,L_g_min,L_g_max) creates a model for the given data:Parameters:GE:pandas dataframe, processed expression dataG:networkX graph, processed network dataL_g_min:int, minimal solution subnetwork sizeL_g_max:int, maximal solution subnetwork sizeMethods:BiCoN.run(self, n_proc = 1, K = 20, evaporation = 0.5, show_plot = False)K:int, default = 20, number of ants. Fewer ants - less space exploration. Usually set between 20 and 50n_proc:int, default = 1, number of processes that should be used(can not be more than K)evaporation,float, default = 0.5, the rate at which pheromone evaporatesshow_plot:bool, default = False, set true if convergence plots should be shown during the iterationsExampleImport the package:frombiconimportdata_preprocessingfrombiconimportBiCoNfrombiconimportresults_analysisSet the paths to the expression matrix and the PPI network:path_expr,path_net='/data/gse30219_lung.csv','/data/biogrid.human.entrez.tsv'Load and process the data:GE,G,labels,_=data_preprocessing(path_expr,path_net)Set the size of subnetworks:L_g_min=10L_g_max=15Set the model and run the search:model=BiCoN(GE,G,L_g_min,L_g_max)solution,scores=model.run_search()Results analysisBiCoN package also allows a user to save the results and perform an initial analysis.
The examples below show the basic usage, for more details please use python help() method, e.g.help(results.save).First, the object for results analysis must be created:results=results_analysis(solution,labels)This will allow to easily access the resulting biclusters and their initial IDs as well as perform a more complicated analysis.To access IDs of patients in the first bicluster:results.patients1To access IDs of genes IDs in the first bicluster:results.genes1Same logic applies to the second bicluster.If in the further analysis you would like to use gene names, please set 'convert' to True and specify the original gene IDs, i.e.:results=results_analysis(solution,labels,convert=True,origID='entrezgene')Some other options for the original gene ID: ensembl.gene', 'symbol', 'refseq', 'unigene', etc
For all possibe option please check  the reference for MyGene.info gene queryweb serviceTo save the solution:results.save(output="results/results.csv")Visualise the resulting networks colored with respect to their difference in expression patterns in patients clusters:results.show_networks(GE,G,output="results/network.png")Visualise a clustermap of the achieved solution alone or also along with the known patients' groups.
Just with the BiCoN results:results.show_clustermap(GE,G,output="results/clustermap.png")If you have a patient's phenotype you would like to use for comparison, please make sure that patients IDs are exactly (!) matching the IDs that were used as an input. The IDs should be represented as a list of two lists, e.g.:true_classes=[['GSM748056','GSM748059',..],['GSM748278','GSM748279','GSM1465989']]results.show_clustermap(GE,G,output="results/clustermap.png",true_labels=true_classes)Given a known phenotype in a format described above, BiCoN can also return Jaccard index of the achieved patients clustering with a given phenotype:results.jaccard_index(true_labels=true_classes)BiCoN is usinggseapymodule to provide a user with a python wrapper forEnrichrdatabase.results.enrichment_analysis(library='GO_Biological_Process_2018',output="results")After the execution of the given above code, in the/resultsdirectory a user can find a table with enriched pathways as well as enrichment plots. Other available libraries can be used as well, e.g. 'GO_Molecular_Function_2018' and 'GO_Cellular_Component_2018'. In total there are 159 libraries available at the moment and the full list can be found by typing:importgseapygseapy.get_library_name()Quality controlAlgorithm convergenceThe best way to check if the algorithm produced high-quality results and there are no issues with the parameters is to analyse the convergence plot:results.convergence_plot(scores)The algorithm converged:If the maximum score has stabilised for several iterations in a row (default is 6).ORIf the average score became equal (or nearly equal) to the maximal score:The algorithm did not converge:If the average and the maximal score improve over the iterations but do not stabilize then just increase the number of maximally allowed iterations:If the scores do not stabilize even after 60-100 iterations, please contact us.Bad probability updateIf you got the following error message:AssertionError:badprobabilityupdateIt can mean one of the following issues:The setting of the algorithm is way to restrictive for your problem. You can try to fix it by repeating the analysis with th = 0, or even th = -1 e.g.:model=BiCoN(GE,G,L_g_min,L_g_max)solution,scores=model.run_search(th=0)Otherwise, the problem might be related to the way you have processed your data. Please make sure that you do not have not expressed genes for the magority of the patients.CiteBiCoN was developed by theBig Data in BioMedicine groupandComputational Systems Medicine groupatChair of Experimental Bioinformatics.If you use BiCoN in your research, we kindly ask you to cite the following manuscript:Lazareva, O., Van Do, H., Canzar, S., Yuan, K., Tieri, P.,Baumbach, J., Kacprowski, T., List, M.: BiCoN: Network-constrained biclustering of patients and omics data. [Submitted]ContactIf you have difficulties using BiCoN, please open an issue at outGitHubrepository. Alternatevely, you can write an email to:Olga LazarevaMarkus ListTim Kacprowski