Package: mil
mil: multiple instance learning library for PythonWhen working on a research problem, I found myself with themultiple instance learning (MIL)framework, which I found quite interesting and unique. After carefully reviewing the literature, I decided to try few of the algorithms on the problem I was working on, but for my surprise, there was no standard, easy, and updated MIL library for any programming language. So... here we are.The mil library tries to achieve reproducible and productive research using the MIL framework.Table of ContentsInstallationFeaturesUsageContributingTo-do-listLicenseInstallationUse the package managerpipto install mil.pipinstallmilFeaturesThe overall implementation tries to be user-friendly as possible. That's why most of it constructed on top ofsklearnandtensorflow.keras.mil.datamil.bag_representationmil.dimensionality_reductionmil.metricsmil.modelsmil.preprocessingmil.utilsmil.validatorsmil.trainerdataVery well known datasets of the multiple instance learning framework have been added to the library. For each of the datasets a train and test split
has been done for reproducibility purposes. The API is similar to the tensorflow datasets in order to create and experiment in a fast and easy way.# importing all the datasets modulesfrommil.data.datasetsimportmusk1,musk2,protein,elephant,corel_dogs,\ucsb_breast_cancer,web_recommendation_1,birds_brown_creeper,\mnist_bags# load the musk1 dataset(bags_train,y_train),(bags_test,y_test)=musk1.load()Also, the mnist_bags dataset has been created. The principal reason of creating this dataset is to have a good benchmark to evaluate the instances predictions. Or more specifically, if we can classify correctly a bag, can we detect which instance/s caused this classification?
In the mnist_bags dataset, there are 3 different types of problems with their own dataset.The bag 'b' is positive if the instance '7' is contained in 'b'# importing all the datasets modulesfrommil.data.datasetsimportmnist_bags# load the mnist_bags(bags_train,y_train),(bags_test,y_test)=mnist_bags.load()The bag 'b' is positive if the instance '2' and '3' are contained in 'b'# importing all the datasets modulesfrommil.data.datasetsimportmnist_bags# load the mnist_bags 2 and 3(bags_train,y_train),(bags_test,y_test)=mnist_bags.load_2_and_3()The bag 'b' is positive if the instance '4' and '2' are located in consecutive instances in 'b'# importing all the datasets modulesfrommil.data.datasetsimportmnist_bags# load the mnist_bags 4 2(bags_train,y_train),(bags_test,y_test)=mnist_bags.load_42()bag_representationIn multiple instance learning, bag representation is the technique that consists in obtaining a unique vector representing all the bag.
The classes implemented in the mil.bag_representation inherit from BagRepresentation base class which is a wrapper to sklearn transformer which have to implement fit and transform method.MILESMappingDiscriminativeMappingArithmeticMeanBagRepresentationMedianBagRepresentationGeometricMeanBagRepresentationMinBagRepresentationMaxBagRepresentationMeanMinMaxBagRepresentationfrommil.bag_representationimportMILESMapping,DiscriminativeMapping,ArithmeticMeanBagRepresentation,\MedianBagRepresentation,GeometricMeanBagRepresentation,MinBagRepresentation,\MaxBagRepresentation,MeanMinMaxBagRepresentationdimensionality_reductionA wrapper to sklearn.decomposition and sklearn.feature_selection.# for example import sklearn PCAfrommil.dimensionality_reductionimportPCAmetricsIncludes a manager to handle all the metrics, some custom metric and a wrapper of tensorflow.keras.metrics. Custom metrics have to inherit from Metrics base class and implement methods update_state, result, and reset_states.# importing a custom metricfrommil.metricsimportSpecificity# importing a keras metricfrommil.metricsimportAUCmodelsIt contains all the end-to-end models. All the models implement a sklearn-like structure with fit, predict, and sometimes get_positive_instances when the method allows it.MILESAPRAttentionDeepPoolingMil# importing mil modelsfrommil.modelsimportAPR,AttentionDeepPoolingMil,MILES# importing sklearn modelsfrommil.modelsimportRandomForestClassifier,SVCIt is also a wrapper to sklearn.svm, sklearn.ensemble, sklearn.linear_model, and sklearn.neighbors.preprocessingIt contains few transformers to normalize and standarize bags of type list, and is also a wrapper to sklearn.preprocessing.# standarize bags of listsfrommil.preprocessingimportStandarizerBagsListutilsIt contains few utility functions, such as bags2instances, padding, progress bar ...# for example importing bags2instances functionfrommil.utils.utilsimportbags2instancesvalidatorsA wrapper to sklearn.model_selection. Includes all the validation strategies to be used in the training process.# for example importing sklearn KFoldfrommil.validatorsimportKFoldvalid=KFold(n_splits=10,shuffle=True)trainerIt is the central part of the library, it allows to train, and evaluate models in a very simple and intuitive way.
It has 4 principal methods.prepare(model, preprocess_pipeline=[], metrics=[]).Which is kind of what 'compile' method is for keras models. What it does is preparing the training and evaluation routine.
The 'model' parameter accepts any of the mil.models objects. The 'preprocess_pipeline' parameter is a list containing all the transforming operations we wish to do before inputing the data into the 'model' object, basically accepts any sklearn transformer. The 'metrics' accepts some strings of typical metrics, or the callables modules from the metrics.fit(X_train, y_train, X_val=None, y_val=None, groups=None, validation_strategy=None, sample_weights=None, verbose=1)Which is the method to train the model. It also handles a sample_weights parameters and mil.validators objects or custom validations splits.predict(X_train, y_train, X_val=None, y_val=None, groups=None, validation_strategy=None, sample_weights=None, verbose=1)Which is the method to train the model. It also handles a sample_weights parameters and mil.validators objects or custom validations splits.get_positive_instances(X)For the models who have implemented this method, it returns the result.Usage# importing datasetfrommil.data.datasetsimportmusk1# importing bag_representationfrommil.bag_representationimportMILESMapping# importing validation strategyfrommil.validatorsimportLeaveOneOut# importing final model, which in this case is the SVC classifier from sklearnfrommil.modelsimportSVC# importing trainerfrommil.trainerimportTrainer# importing preprocessingfrommil.preprocessingimportStandarizerBagsList# importing metrics, which in this case are from tf keras metricsfrommil.metricsimportAUC# loading dataset(bags_train,y_train),(bags_test,y_test)=musk1.load()# instantiate trainertrainer=Trainer()# preparing trainermetrics=['acc',AUC]model=SVC(kernel='linear',C=1,class_weight='balanced')pipeline=[('scale',StandarizerBagsList()),('disc_mapping',MILESMapping())]trainer.prepare(model,preprocess_pipeline=pipeline,metrics=metrics)# fitting trainervalid=LeaveOneOut()history=trainer.fit(bags_train,y_train,sample_weights='balanced',validation_strategy=valid,verbose=1)# printing validation results for each foldprint(history['metrics_val'])# predicting metrics for the test settrainer.predict_metrics(bags_test,y_test)For more examples, check examples subdirectory.ContributingPull requests are welcome. Priority things are onTo-do-list. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.To-do-listPending tasks to do:Implement other algorithms, such as the SVM based ones.Make C/C++ extension of the APR algorithm to run faster.Make C/C++ extension of the MILESMapping algorithm to run faster.MILESMapping generates a simetric matrix of bag instance similarity, optimize it to only calculate half matrix and apply other possible optimizations to reduce time and space complexity.Implement get_positive_instances for MILES model.Implement Tuner class for hyperparameter tuning.Implement Callbacks for using on Trainer.Add one cycle learning rate to use on optimizers of KerasClassifiers models.On trainer, implement to get the best validation loss for calculating the metrics, right now when evaluating a KerasClassifier model, the metrics are the ones from the last epoch.LicenseMIT license