Package: ingotdr
INGOT-DRINGOT-DR(INterpretableGrOupTesting forDrugResistance) is an interpretable rule-based
predictive model base onGroup TestingandBoolean Compressed Sesing. For more details and citation please see the
INGOT-DRpaper. To access scripts used to produce the results in the paper please visitINGOT-DR Project. To access the data used in the paper
please visit/citeM.tuberculosis dataset for drug resistant.##Table of contentInstallationUsageArgumentsMethodsTraining and evaluationHyper-parameter tuningOptimizing for different target metricChoosing the solverCitationInstallationINGOT-DR can be installed fromPyPI.pipinstallingotdrUsageINGOT-DR is implemented as ascikit-learnclassifier. As a result, this classifier is compatible with most of scikit-learn
tools (e.g. cross validation and hyper-parameter tuning tools). In the following section, we provide some usage examples:Argumentsingot.INGOTClassifier(w_weight=1,lambda_p=1,lambda_z=1,lambda_e=1,false_positive_rate_upper_bound=None,false_negative_rate_upper_bound=None,max_rule_size=None,rounding_threshold=1e-5,lp_relaxation=False,only_slack_lp_relaxation=False,lp_rounding_threshold=0,is_it_noiseless=False,solver_name='PULP_CBC_CMD',solver_options=None)NameTypeDescriptionDefaultw_weightvector, floatA vector, float to provide prior weight tow.1.0lambda_pfloatRegularization coefficient for positive labels.1.0lambda_zfloatRegularization coefficient for negative/zero labels.1.0lambda_efloatRegularization coefficient for all slack variables.1.0false_positive_rate_upper_boundfloatFalse positive rate (FPR) upper bound.Nonefalse_negative_rate_upper_boundfloatFalse negative rate(FNR) upper bound.Nonemax_rule_sizeintMaximum rule size.Nonerounding_thresholdfloatThreshold for ILP solutions for Rounding to 0 and 1.1e-5lp_relaxationboolA flag to use the lp relaxed version.Falseonly_slack_lp_relaxationboolA flag to only use the lp relaxed slack variables.Falselp_rounding_thresholdfloatThreshold for lp solutions for Rounding to 0 and 1. Range from 0 to 1.0.0is_it_noiselessboolA flag to specify whether the problem is noisy or noiseless.Falsesolver_namestrSolver'snameprovided by Pulp.'PULP_CBC_CMD'solver_optionsdictSolver'soptionsprovided by Pulp.NoneMethodsMethodDescriptionfit(X,y)Fit the model with respect to the given data.get_params_dictionary(variable_type='w')Provide a dictionary of individuals with their status obtained by decoder. Type of the variable.e.g. 'w', 'ep' or 'en'solution()Provide a vector of binary features importance. i.e. 1 if feature was used in the model 0 otherwise.predict(X)Provide a predicted labels for X.score(X,y)Provide the accuracy ofself.predict(X)with respect toylearned_rule(return_type='feature_name')Return a list of rules. return_type can be 'feature_name' or 'feature_id'.write(fileType='mps', **kwargs)Create a file from the problem.fileTypecan be 'mps', 'lp', 'json' or 'display'. 'display' shows the ILP/LP problem on screen.Training and evaluationExample:The following is an example of training a classifier to predict resistance to second line drugCiprofloxacinin TB isolates. In this example the
feature matrix indicates presence/absence of SNPs in TB isolates, and the label vector represents the drug resistance phenotype.
Sample data is availablehere.fromsklearn.model_selectionimporttrain_test_splitfromsklearn.metricsimportbalanced_accuracy_scoreimportpandasaspdimportingotfeature_matrix='SNPsMatrix_ciprofloxacin.csv'label_vector='ciprofloxacinLabel.csv'X=pd.read_csv(feature_matrix,index_col=0)y=pd.read_csv(label_vector,index_col=0).to_numpy().ravel()X_train,X_test,y_train,y_test=train_test_split(X,y,random_state=33,test_size=0.2,stratify=y)clf=ingot.INGOTClassifier(lambda_p=10,lambda_z=0.01,false_positive_rate_upper_bound=0.1,max_rule_size=20,solver_name='CPLEX_PY')clf.fit(X_train,y_train)y_pred=clf.predict(X_test)print("Balanced accuracy:{}".format(balanced_accuracy_score(y_test,y_pred)))print("Accuracy:{}".format(clf.score(X_test,y_test)))print("Features in the learned rule:{}".format(clf.learned_rule()))Output:Note:Results may slightly vary for different solvers. Please seeChoosing the solver.Balancedaccuracy:0.8449477351916377
Accuracy:0.9550561797752809
Featuresinthelearnedrule:['7570, C, T','7572, T, C','7581, G, T','7582, A, C','7582, A, G']Hyper-parameter tuningHyper-parameter tuning via scikit-learnGrid Search CV:Example:fromsklearn.model_selectionimporttrain_test_splitfromsklearn.metricsimportbalanced_accuracy_scoreimportpandasaspdimportingotfromsklearn.model_selectionimportGridSearchCVfromsklearn.metricsimportmake_scorerfeature_matrix='SNPsMatrix_ciprofloxacin.csv'label_vector='ciprofloxacinLabel.csv'X=pd.read_csv(feature_matrix,index_col=0)y=pd.read_csv(label_vector,index_col=0).to_numpy().ravel()X_train,X_test,y_train,y_test=train_test_split(X,y,random_state=33,test_size=0.2,stratify=y)clf=ingot.INGOTClassifier(false_positive_rate_upper_bound=0.1,max_rule_size=20,solver_name='CPLEX_PY',solver_options={'timeLimit':1800})scoring=dict(Accuracy='accuracy',balanced_accuracy=make_scorer(balanced_accuracy_score))param_grid={'lambda_p':[1,10,100],'lambda_z':[0.01,0.1,1]}grid=GridSearchCV(estimator=clf,param_grid=param_grid,scoring=scoring,cv=5,refit='balanced_accuracy',n_jobs=-1,verbose=3)grid.fit(X_train,y_train)y_pred=grid.predict(X_test)print("Balanced accuracy:{}".format(balanced_accuracy_score(y_test,y_pred)))print('Best params:{}'.format(grid.best_params_))Output:Balancedaccuracy:0.8449477351916377
Bestparams:{'lambda_p':10,'lambda_z':0.01}Optimizing for different target metricNote:w_weightandlambda_eare not part of the main ILP (Eq (11)) defined in the INGOT-DR paper. These two variables
are defined to provide freedom whenOptimizing for different target metric(section 1.4) is needed. The
complete objective function with these two variables would be:Example:Classifier corresponding toEq (16)with maximum rule size k=20 and specificity lower bound t= 90% can be defined as following:clf=ingot.INGOTClassifier(w_weight=0,lambda_z=0,false_positive_rate_upper_bound=0.1,max_rule_size=20,solver_name='CPLEX_PY')The following table shows the combination of arguments needed to define some of ILPs in thepaperlp_relaxationonly_slack_lp_relaxationis_it_noiselessEquation number in thepaperFalseFalseFalseEq (11)FalseTrueTrueEq (3)FalseTrueFalseEq (4) with objective function of Eq (11)FalseFalseTrueEq (3)TrueTrueFalseLP relaxation of Eq (4) with objective function of Eq (11)TrueFalseFalseLP relaxation of Eq (4) with objective function of Eq (11)TrueFalseTrueLP relaxation of Eq (3)TrueTrueTrueLP relaxation of Eq (3)Note:True value oflp_relaxationoris_it_noiselesswith overrideonly_slack_lp_relaxation. i.e. if one of them is True
then value ofonly_slack_lp_relaxationis not important.Note:To recreate and work withEq (4), you only need to use combination in row 3 and use or tunelambda_einstead oflambda_pandlambda_z. For example:param_grid={'lambda_e':[0.01,0.1,1,10,100]}grid=GridSearchCV(estimator=clf,param_grid=param_grid,scoring=scoring,cv=5,refit='balanced_accuracy',n_jobs=-1,verbose=3)Choosing the solverINGOT-DR supports a variety of solvers through thePuLPapplication programming interface (API).
Solvers such asGLPK,COIN-OR CLP/CBC,CPLEX,GUROBI,MOSEK,XPRESS,CHOCO,MIPCL,SCIP.List of available solvers on your machine:importpulpasplsolver_list=pl.listSolvers(onlyAvailable=True)Name and properties of the solver can be specified viasolver_nameandsolver_options. e.g:clf=ingot.INGOTClassifier(solver_name='CPLEX_PY',solver_options={'timeLimit':1800})In theINGOT-DRpaper,'CPLEX_PY'is the main solver. Results may slightly vary for different solvers. IBM CPLEX for academic use is availablehere.Citation:For general use please cite our paper:INGOT-DR: an interpretable classifier forpredicting drug resistance in M. tuberculosis.
(bibtex)