Merge Grammar-Checked README and Fixed File Names

README.md

@@ -41,23 +41,24 @@
 - [Make your PyTorch Model compatible with DISTIL](#make-your-pytorch-model-compatible-with-distil)
 - [Demo Notebooks](#demo-notebooks)
 - [Evaluation of Active Learning Strategies](#evaluation-of-active-learning-strategies)
-- [Testing Individual strategy and Running Examples](#testing-individual-strategy-and-running-examples)
+- [Testing Individual Strategies and Running Examples](#testing-individual-strategies-and-running-examples)
 - [Mailing List](#mailing-list)
 - [Publications](#publications)
 - [Acknowledgement](#acknowledgement)
 
 ## What is DISTIL?
-DISTIL is an active learning toolkit, which implements a number of state of art active learning strategies, with a particular focus for active learning in the deep learning setting. DISTIL is built on pyTorch and decouples the training loop from the active learning algorithms, thereby providing flexibility to the user to control the training procedures and models. It allows users to incorporate new active learning algorithms easily with minimal changes to the existing code. DISTIL also provides support for incorporating active learning with your custom dataset as well as experimentation on well known datasets. We are continuously incorporating newer and better selection strategies into DISTIL.
+DISTIL is an active learning toolkit that implements a number of state-of-the-art active learning strategies with a particular focus for active learning in the deep learning setting. DISTIL is built on PyTorch and decouples the training loop from the active learning algorithm, thereby providing flexibility to the user by allowing them to control the training procedure and model. It allows users to incorporate new active learning algorithms easily with minimal changes to their existing code. DISTIL also provides support for incorporating active learning with your custom dataset and allows you to experiment on well-known datasets. We are continuously incorporating newer and better active learning selection strategies into DISTIL.
 
 ## Key Features of DISTIL
-- Decouples the active learning strategy from the training loop there allowing the users to modify the training and/or the active learning strategy.
-- Faster and efficient implementation of several active learning strategies.
-- Implements most state-of-the-art active learning algorithms.
-- Run the basic experiments with just one command. Access to various active learning strategies with just one line of code.
-- Minimal changes in configuration files to run your own experiments.
-- Achieving similar test accuracy with less amount of training data. Huge reduction in labelling cost and time.
-- Minimal changes to add it to the existing training structure.
-- Recipies, tutorials and benchmarks of all active learning algorithms on many deep learning datasets.
+- Decouples the active learning strategy from the training loop, allowing users to modify the training and/or the active learning strategy
+- Implements faster and more efficient versions of several active learning strategies
+- Contains most state-of-the-art active learning algorithms
+- Allows running basic experiments with just one command
+- Presents interface to various active learning strategies through only a couple lines of code
+- Requires only minimal changes to the configuration files to run your own experiments
+- Achieves higher test accuracies with less amount of training data, admitting a huge reduction in labeling cost and time
+- Requires minimal change to add it to existing training structures
+- Contains recipes, tutorials, and benchmarks for all active learning algorithms on many deep learning datasets
 
 ## Starting with DISTIL
 ```
@@ -67,7 +68,7 @@ python train.py --config_path=/content/distil/configs/config_svhn_resnet_randoms
 ```
 For making your custom configuration file for training, please refer to [Distil Configuration File Documentation](https://decile-team-distil.readthedocs.io/en/latest/configuration.html)
 
-Some of the algorithms currently implemented with DISTIL include:
+Some of the algorithms currently implemented in DISTIL include the following:
 
 - [Uncertainty Sampling [1]](https://decile-team-distil.readthedocs.io/en/latest/ActStrategy/distil.active_learning_strategies.html#module-distil.active_learning_strategies.entropy_sampling)
 - [Margin Sampling [2]](https://decile-team-distil.readthedocs.io/en/latest/ActStrategy/distil.active_learning_strategies.html#module-distil.active_learning_strategies.margin_sampling)
@@ -85,7 +86,7 @@ Some of the algorithms currently implemented with DISTIL include:
 - [Baseline Sampling](https://decile-team-distil.readthedocs.io/en/latest/ActStrategy/distil.active_learning_strategies.html#module-distil.active_learning_strategies.baseline_sampling)
 
 ## Where can DISTIL be used?
-DISTIL is a toolkit which provides support for various active learning algorithms. Presently it only works in the supervised learning setting for classification. We will be adding extensions to active semi-supervised learning and active learning for object detection. It can be used in scenarios where you only want to label few data points which can provide maximum information to the ML model and thus reduce labeling cost and time.
+DISTIL is a toolkit which provides support for various active learning algorithms. Presently, it only works in the supervised learning setting for classification. We will be adding extensions to active semi-supervised learning and active learning for object detection. It can be used in scenarios where you want to reduce labeling cost and time by labeling only the few most informative points for your ML model.
 
 ## Installation
 The latest version of  DISTIL package can be installed using the following command:
@@ -95,7 +96,7 @@ pip install --extra-index-url https://test.pypi.org/simple/ decile-distil
 ```
 ### NOTE
 ```
-Please make sure to enter the space between simple/ and decile-distil in the above command while installing DISTIL package
+Please make sure to enter the space between simple/ and decile-distil in the above command while installing the DISTIL package!
 ```
 
 ## Package Requirements
@@ -107,24 +108,26 @@ Please make sure to enter the space between simple/ and decile-distil in the abo
 6) "apricot-select >= 0.6.0"
 
 ## Documentation
-Learn more about distil at our [documentation](https://decile-team-distil.readthedocs.io/en/latest/).
+Learn more about DISTIL by reading our [documentation](https://decile-team-distil.readthedocs.io/en/latest/).
 
 ## Make your PyTorch Model compatible with DISTIL
 DISTIL provides various models and data handlers which can be used directly.
-DISTIL makes it extremely easy to integrate your custom models with active learning. There are two main things that needs to be incorporated in the code before using DISTIL.
+DISTIL makes it extremely easy to integrate your custom models with active learning. There are two main things that need to be incorporated in your code before using DISTIL.
 
 * Model
-    * The model should have a function get_embedding_dim which returns the number of hidden units in the last layer.
-    * The forward function should have a boolean flag “last” where:
-        * if True: It should return the model output and the output of the second last layer
-        * if False: It should only return the model output.
+    * Your model should have a function get_embedding_dim() which returns the number of hidden units in the last layer.
+    * Your forward() function should have an optional boolean parameter “last” where:
+        * If True: It should return the model output and the output of the second last layer
+        * If False: It should return only the model output.
+    * Check the models included in DISTIL for examples!
 
 * Data Handler
-    * The data handler class should have a boolean parameter “select”:
-        * if True: It should return only X and not Y (used by active learning strategies)
-        * if False: It should return both X and Y (used while training the model)
+    * Your DataHandler class should have a boolean attribute “select”:
+        * If True: Your __getitem__(self, index) method should return (input, index)
+        * If False: Your __getitem__(self, index) method should return (input, label, index)
+    * Check the DataHandler classes included in DISTIL for examples!
 
-To get a more clearer idea about how to incorporate DISTIL with your own models, refer to [Getting Started With DISTIL & Active Learning Blog](https://decile-research.medium.com/getting-started-with-distil-active-learning-ba7fafdbe6f3)
+To get a clearer idea about how to incorporate DISTIL with your own models, refer to [Getting Started With DISTIL & Active Learning Blog](https://decile-research.medium.com/getting-started-with-distil-active-learning-ba7fafdbe6f3)
 
 ## Demo Notebooks
 1. https://colab.research.google.com/drive/10WkyKlOxSixrMHvA9wEHcd0l5HugnChN?usp=sharing
@@ -135,7 +138,7 @@ To get a more clearer idea about how to incorporate DISTIL with your own models,
 
 ## Evaluation of Active Learning Strategies
 ### Experimentation Method
-The model was first trained on randomly selected n points where n is the budget of the experiment. For each set of new points added, the model was trained from scratch till the training accuracy crossed the max accuracy threshold.
+The models used below were first trained on n randomly selected points, where n is the budget of the experiment. For each set of new points added, the model was trained from scratch until the training accuracy crossed the max accuracy threshold. The test accuracy was then reported before the next selection round.
 
 ### CIFAR10
 Budget: 5000, Model: Resnet18, Number of rounds: 10, Total Points: 50,000
@@ -146,7 +149,7 @@ Test Accuracy              |  Label Efficiency
 ![CIFAR10 Plot](./experiment_plots/cifar10_plot_50k.png?raw=true)  |  ![CIFAR10 LE](./experiment_plots/cifar10_label_efficiency.png?raw=true)
 
 
-The label efficiency plot indicates that for reaching testing accuracy of 92% on CIFAR10, random sampling requires 35000 labeled points, whereas entropy and badge acheives same accuracy levels at 20000 points.
+The label efficiency plot indicates that, when reaching a test accuracy of 92% on CIFAR10, random sampling requires 35,000 labeled points, whereas entropy sampling and BADGE achieve the same test accuracy at 20,000 points.
 
 ### MNIST
 Budget: 1000, Model: Resnet18, Number of rounds: 11, Total Points: 12,000 (20%)
@@ -158,7 +161,7 @@ Test Accuracy(Zoomed)      |  Label Efficiency(Finer Budget)
 
 
 
-The label efficiency plot indicates that for reaching testing accuracy of 96% on MNIST, random sampling requires 860 labeled points, whereas entropy requires 460 and badge acheives same accuracy levels at 500 points. The label efficiency graph is on a finer budget.
+The label efficiency plot indicates that, when reaching a test accuracy of 96% on MNIST, random sampling requires 860 labeled points, whereas entropy sampling requires only 460 points while BADGE requires only 500 points. The label efficiency graph is on a finer budget.
 
 Zoomed out training plot.
 
@@ -173,7 +176,7 @@ Test Accuracy              |  Label Efficiency
 ![FMNIST Plot](./experiment_plots/fmnist_plot.png?raw=true)  |  ![FMNIST LE](./experiment_plots/fmnist_label_efficiency.png?raw=true)
 
 
-The label efficiency plot indicates that for reaching testing accuracy of 94% on Fashion MNIST, random sampling requires 35000 labeled points, whereas entropy and badge acheives same accuracy levels at 12000 points.
+The label efficiency plot indicates that, when reaching a test accuracy of 94% on Fashion MNIST, random sampling requires 35,000 labeled points, whereas entropy sampling and BADGE achieve the same test accuracy at 12,000 points.
 
 ### SVHN
 Budget: 1000, Model: Resnet18, Number of rounds: 10, Total Points: 11,000 (15%)
@@ -184,15 +187,15 @@ Test Accuracy              |  Label Efficiency
 ![SVHN Plot](./experiment_plots/svhn_plot.png?raw=true)  |  ![SVHN LE](./experiment_plots/svhn_label_efficiency.png?raw=true)
 
 
-The label efficiency plot indicates that for reaching testing accuracy of 95% on SVHN, random sampling requires 52000 labeled points, whereas entropy and badge acheives same accuracy levels at 16000 points.
+The label efficiency plot indicates that, when reaching a test accuracy of 95% on SVHN, random sampling requires 52,000 labeled points, whereas entropy sampling and BADGE achieve the same test accuracy at 16,000 points.
 
 ### OPENML-6
 Budget: 400, Model: Two Layer Net, Number of rounds: 11, Total Points: 4800 (30%)
 
 ![OPENML6 Plot](./experiment_plots/openml6_plot.png?raw=true)
 
-## Testing Individual strategy and Running Examples
-Before running the examples or test, please clone the dataset repository, along with this one. The default data path expects the repository in the same root directory as that of distil. If you change the location, the data paths in the exmples or tests needs to be changed accordingly.
+## Testing Individual Strategies and Running Examples
+Before running the examples or test script, please clone the dataset repository in addition to this one. The default data path expects the repository in the same root directory as that of DISTIL. If you change the location, the data paths in the examples and test scripts need to be changed accordingly.
 
 Dataset repository:
 ```
@@ -215,7 +218,7 @@ python test_strategy.py -h
 ```
 
 ## Mailing List
-To receive updates about distil and be a part of the community, join the Decile_DISTIL_Dev group.
+To receive updates about DISTIL and to be a part of the community, join the Decile_DISTIL_Dev group.
 ```
 https://groups.google.com/forum/#!forum/Decile_DISTIL_Dev/join 
 ```
@@ -243,4 +246,4 @@ https://groups.google.com/forum/#!forum/Decile_DISTIL_Dev/join
 [10] Gal, Yarin, Riashat Islam, and Zoubin Ghahramani. "Deep bayesian active learning with image data." International Conference on Machine Learning. PMLR, 2017.
 
 ## Acknowledgement
-This library takes inspiration and also uses pieces of code from [Kuan-Hao Huang's deep active learning repository](https://github.com/ej0cl6/deep-active-learning) and [JordanAsh's Badge repository](https://github.com/JordanAsh/badge).
+This library takes inspiration and also uses pieces of code from [Kuan-Hao Huang's deep active learning repository](https://github.com/ej0cl6/deep-active-learning), [Jordan Ash's Badge repository](https://github.com/JordanAsh/badge), and [Andreas Kirsch's and Joost van Amersfoort's BatchBALD repository](https://github.com/BlackHC/batchbald_redux).

distil/active_learning_strategies/__init__.py

@@ -1,23 +1,4 @@
 # __init__.py
 # Author: Apurva Dani <apurvadani@gmail.com>
 
-from .fass import FASS
-from .entropy_sampling import EntropySampling
-from .entropy_sampling_dropout import EntropySamplingDropout
-from .random_sampling import RandomSampling
-from .least_confidence import LeastConfidence
-from .least_confidence_dropout import LeastConfidenceDropout
-from .margin_sampling import MarginSampling
-from .margin_sampling_dropout import MarginSamplingDropout
-from .core_set import CoreSet
-from .glister import GLISTER
-from .badge import BADGE
-from .gradmatch_active import GradMatchActive
-from .adversarial_bim import AdversarialBIM
-from .adversarial_deepfool import AdversarialDeepFool
-from .kmeans_sampling import KMeansSampling
-from .baseline_sampling import BaselineSampling
-from .bayesian_active_learning_disagreement_dropout import BALDDropout
-from .submod_sampling import SubmodSampling
-
 __version__ = '0.0.1'

distil/active_learning_strategies/submod_sampling.py

@@ -3,9 +3,9 @@
 import torch
 
 from ..utils.submodular import SubmodularFunction
-from ..utils.Disparty_functions import DisparityFunction
-from ..utils.Similarity_mat import SimilarityComputation
-from ..utils.DPP import dpp
+from ..utils.disparity_functions import DisparityFunction
+from ..utils.similarity_mat import SimilarityComputation
+from ..utils.dpp import dpp
 
 class SubmodSampling(Strategy):
     """

distil/utils/ConfigHelper.py → distil/utils/config_helper.py

@@ -1,16 +1,16 @@
-import json
-import os
-
-def read_config_file(filename):
-	
-	print(filename.split('.')[-1])
-	if filename.split('.')[-1] not in ['json']:
-		raise IOError('Only json type are supported now!')
-	
-	if not os.path.exists(filename):
-		raise FileNotFoundError('Config file does not exist!')
-
-	with open(filename, 'r') as f:
-		config = json.load(f)
-
+import json
+import os
+
+def read_config_file(filename):
+
+	print(filename.split('.')[-1])
+	if filename.split('.')[-1] not in ['json']:
+		raise IOError('Only json type are supported now!')
+
+	if not os.path.exists(filename):
+		raise FileNotFoundError('Config file does not exist!')
+
+	with open(filename, 'r') as f:
+		config = json.load(f)
+
 	return config	

distil/utils/Disparty_functions.py → distil/utils/disparity_functions.py

@@ -3,7 +3,7 @@
 
 from scipy.sparse import csr_matrix
 
-from .Similarity_mat import SimilarityComputation
+from .similarity_mat import SimilarityComputation
 
 class DisparityFunction(SimilarityComputation):
 

distil/utils/submodular.py

@@ -5,7 +5,7 @@
 
 from scipy.sparse import csr_matrix
 
-from .Similarity_mat import SimilarityComputation
+from .similarity_mat import SimilarityComputation
 
 
 class SubmodularFunction(SimilarityComputation):