Package: bn2vec
bn2vecBoolean Networks' embedding techniques & ML based Boolean Networks' classification.0. Introduction:bn2vec is the result of an earlier research which has been conducted in 2021 (Mar-Sept) as part of a larger project namedBNediction, the goal of the research was fixated on developing new embedding techniques specifically built for dealing with Boolean Networks, the aim though was to use these techniques to help classifiy Boolean Networks and develop a solid set of features which would be able to explain the performance of a given BN.the full master's thesis report which wraps the work done in this package could be found inMaster's Thesis, any details regarding how the embedding or the classification work are discussed in the report.for a walk through example please checktest.ipynb.1. Setting up:step 1. creating a new virtual env.python-mvenvenvfor a manual setup we should install the packages from the requirements.txt file and then install bn2vec using pip.pipinstall-rrequirements.txtpipinstall-e.3. Config:when creating a ConfigParser object you will be asked to feed the path for your configuration file, the file should be a yaml type and it should conform to the validation rules for it to be used, in case of abscense of the config file a default file (allow-all) would be used, seeDefault Config File.under sectionMemory6 options are allowed:memorize_dnf_graphs (resp. _bn_graphs): if set to true it allows for remembering graphs' data generated from DNFs (resp. BNs).memorize_dnf_sequences (resp. _bn_sequences): if set to true it allows for remembering sequences' data generated from DNFs (resp. BNs).hard_memory: if set to true it allows for storing the generated data from an ensemble of BNs into the desk.hard_memory_loc: the path folder for hard_memory.under sectionEmbeddingswe can specify any of the following options:rsf: stands forRelaxed Structural Features, if specified the system generates RSF features of the given ensemble of BNs.lsf: stands forLossy Structural Features, if specified the system generates LSF features of the given ensemble of BNs.ptnrs: acronym ofPatterns, if specified the system generates PTRNS features of the given ensemble of BNs.igf: stands forInfluence Graph Features, if specified the system generates IGF features of the given ensemble of BNs.for more details about the rest of the file please have a look at theDefault Fileand theFull Report.4. Embeddings:let us have a look at the different ways of using the feature engineering module.necessary imports:fromcolomotoimportminibnfrombn2vec.feature_engineeringimportDnf2Vec,Bn2Vec,Ens2Matfrombn2vec.utilsimportConfigParserin the case of usingDnf2Vec(embedding a single DNF) orBn2Vec(embedding a single BN, ensemble of DNFs), we have to tell the system to parse the config file ourselves.ConfigParser.parse("path/to/configfile")we use minibn.BooleanNetwork to parse Boolean Networks' files.bn=minibn.BooleanNetwork("path/to/boolean_network")BN=list(bn.items())then when usingDnf2Vecwe can perform the embedding to one of the BN's DNFs this way.gen=Dnf2Vec(dnf=BN[0][1],comp_name=BN[0][0])graphs,seqs,features=gen.generate_features()the generate_features method returns three objects:graphs (resp. seqs): is a dictionary containing the graphs' (res. sequences') data of the given DNF.(if asked for).features: is a pandas Series object containing the final features extracted from the given DNF.likewise we can embed the whole BN.gen=Bn2Vec(BN)bn_graphs,bn_seqs,dnfs_data,bn_features=gen.generate_features()this time we have more complicated semi-structed data to look at:bn_graphs (resp. bn_seqs): is a dictionary containing the graphs' (res. sequences') data of the given BN.(if asked for).dnfs_data: contains dnf graphs, sequences and features generated by Dnf2Vec for all dnfs in the given BN.bn_features: is a pandas Series object containing the final features extracted from the given BN.if we want to embed an ensemble of BNs we simply useEns2Mat(ensemble to matrix).gen=Ens2Mat(config_path='path/to/config_file',master_model_src='path/to/master_model')X,Y=gen.vectorize_BNs('path/to/base_directory','',# bundle file name (under base_directory)size='all'# or an integer (the number of BNs to embed))5. Features Selector:in order to useBnFeaturesSelectorwe should import one extra module:frombn2vec.feature_selectionimportBnFeaturesSelectorthis module has 3 main methods:drop_zero_variance_features: literally removes features without any flactuations.cluster_collinear_features_leiden: uses the leiden algorithm to cluster features based on their collinearities, then the method selects the best representative feature from each cluster, this method is only useful in the case of LSF and RSF (mostly LSF where elminiating collinearities is important but also deciding which to remove is more important).correct_collinearity: takes a set of features and then returns another set of features (with high collinearity with the input features) which are better explainable than the originals.selector=BnFeaturesSelector(X,mode='lsf')X=selector.drop_zero_variance_features()X,clusters=selector.cluster_collinear_features_leiden(thresh=0.8)the argument thresh is the threshold (minimal value) to decide that two features are correlated, it is calulated as the absolute value of the correlation value between the two features.6. Rules Extractor:necessary imports for using the rules extraction module:frombn2vec.utilsimportBnDatasetfrombn2vec.rules_extractionimportDTC,RulesExtractorcreating a BnDataset object is necessary:base_dir='path/to/base_directory'BN=BnDataset(dataset_X=os.path.join(base_dir,'path/to/X_file'),dataset_Y=os.path.join(base_dir,'path/to/Y_file'),score_threshold=1)then we can create ourDTC(stands for Decision Tree Classifier) object:dtc=DTC(dataset=BN,save_dir="path/to/saving_directory",ensemble="ens1",embedding="ptrns")the arguments 'ensemble' and 'embedding' are there just for naming conventions, to train deep decision tree classifiers we use the train_deep_dtcs method:dtc.train_deep_dtcs(test_size=0.3)this well train a balanced and an unbalanced version of the tree, it will save the trees and the metrics in the save_dir folder and it will print the metrics for visual inspection.in order to extract useful rules from these trees we should use theRulesExtractorclass:rule_extractor=RulesExtractor(dataset=BN,dtc="path/to/dtc",)rules=rule_extractor.extract_rules(thresh=0,tpr_weight=0.5,# importance of the true positive ratetnr_weight=0.5# importance of the true negative rate)for training singleton decision trees (trees with a single split) we use train_singleton_dtcs:rules=dtc.train_singleton_dtcs(test_size=0.3,balanced=False,thresh=0.5,tpr_weight=0.5,tnr_weight=0.5)