documentation + error handling

Author: e-oj

ada_model.py

@@ -7,9 +7,19 @@
 
 
 class AdaModel:
+    """
+    This class represents a model based on
+    adaboost.
+    """
     def __init__(self, train_file="./in/train.dat", test_file="./in/test.dat",
                  out_file="./out/ensemble.ab"):
+        """
+        Initialize the model.
 
+        :param train_file: training data
+        :param test_file: test data
+        :param out_file: output data
+        """
         files = (train_file, test_file)
         lines = parse(files)
 
@@ -19,6 +29,11 @@ def __init__(self, train_file="./in/train.dat", test_file="./in/test.dat",
         self.tree = None
 
     def train(self, ensemble_size=5):
+        """
+        Learns an ensemble using adaboost and
+        saves the model to a file.
+        """
+
         examples = self.data["train"]
         features = set(examples[0].features.keys())
         sample = WeightedSample(examples)
@@ -50,11 +65,16 @@ def train(self, ensemble_size=5):
         pickle.dump(self, f)
         f.close()
 
-    def test(self, h_file=None):
+    def test(self, test_file=None):
+        """
+        Tests the model.
+
+        :param test_file: test data
+        """
         if not self.ensemble:
             self.train()
 
-        examples = parse([h_file])[0] if h_file else self.data["test"]
+        examples = parse([test_file])[0] if test_file else self.data["test"]
         result = []
 
         for ex in examples:
@@ -65,6 +85,13 @@ def test(self, h_file=None):
         evaluate(result, examples)
 
     def vote(self, instance):
+        """
+        Classifies an instance by collecting
+        votes from the ensemble
+
+        :param instance: instance to classify
+        :return: classification
+        """
         count = {}
         max_count = 0
         winner = None
@@ -84,12 +111,18 @@ def vote(self, instance):
         return winner
 
 
-def evaluate(result, examples):
+def evaluate(results, examples):
+    """
+    Evaluates results from a model.
+
+    :param results: list of results
+    :param examples: test data
+    """
     correct = 0
 
     print()
 
-    for res in result:
+    for res in results:
         if res["result"] == res["goal"]:
             correct += 1
         else:
@@ -102,6 +135,9 @@ def evaluate(result, examples):
 
 
 def main():
+    """
+    Main function. (Test)
+    """
     model = AdaModel()
     model.train(5)
     model.test()

classify.py

@@ -6,6 +6,16 @@
 
 
 def train(examples, out_file, learner):
+    """
+    Train a learner on some examples and saves
+    the resulting model to a file.
+
+    :param examples: training data
+    :param out_file: output file
+    :param learner: "ada" or "dt"
+
+    :return:
+    """
     if learner == "dt":
         model = DecisionModel(train_file=examples, out_file=out_file)
     else:
@@ -15,17 +25,44 @@ def train(examples, out_file, learner):
 
 
 def predict(h_file, test_file):
+    """
+    Loads a hypothesis (model) from h_file and
+    uses it to predict the results of instances
+    in a test file.
+
+    :param h_file: model file
+    :param test_file: test file
+    """
     h_file = open(h_file, "rb")
     model = pickle.load(h_file)
 
     h_file.close()
     model.test(test_file)
 
 
+def usage(train_msg=True, predict_msg=True):
+    if train_msg:
+        print("Usage: python3 classify.py train <examples> <hypothesisOut> <learning-type>")
+
+    if predict_msg:
+        print("Usage: python3 classify.py predict <hypothesis> <file>")
+
+    exit(1)
+
+
 def main():
+    """
+    Main function. Accepts user input.
+    """
+    if len(sys.argv) < 2:
+        usage()
+
     action = sys.argv[1]
 
     if action == "train":
+        if len(sys.argv) < 5:
+            usage(predict_msg=False)
+
         examples = sys.argv[2]
         out_file = sys.argv[3]
         learner = sys.argv[4]
@@ -35,6 +72,9 @@ def main():
         print("Done.")
 
     elif action == "predict":
+        if len(sys.argv) < 4:
+            usage(train_msg=False)
+
         h_file = sys.argv[2]
         test_file = sys.argv[3]
 

d_model.py

@@ -5,8 +5,20 @@
 
 
 class DecisionModel:
+    """
+    This class represents a model based on
+    decision trees.
+    """
+
     def __init__(self, train_file="./in/train.dat", test_file="./in/test.dat",
                  out_file="./out/tree.dt"):
+        """
+        Initialize the model
+
+        :param train_file: training data
+        :param test_file: test data
+        :param out_file: output data
+        """
         files = (train_file, test_file)
         lines = parse(files)
 
@@ -15,6 +27,10 @@ def __init__(self, train_file="./in/train.dat", test_file="./in/test.dat",
         self.tree = None
 
     def train(self):
+        """
+        Learns a decision tree and saves
+        the model to a file.
+        """
         examples = self.data["train"]
         features = set(examples[0].features.keys())
 
@@ -24,11 +40,16 @@ def train(self):
         pickle.dump(self, f)
         f.close()
 
-    def test(self, h_file=None):
+    def test(self, test_file=None):
+        """
+        Tests the model.
+
+        :param test_file: test data
+        """
         if not self.tree:
             self.train()
 
-        examples = parse([h_file])[0] if h_file else self.data["test"]
+        examples = parse([test_file])[0] if test_file else self.data["test"]
         result = []
 
         for ex in examples:
@@ -39,12 +60,18 @@ def test(self, h_file=None):
         evaluate(result, examples)
 
 
-def evaluate(result, examples):
+def evaluate(results, examples):
+    """
+    Evaluates results from a model.
+
+    :param results: list of results
+    :param examples: test data
+    """
     correct = 0
 
     print()
 
-    for res in result:
+    for res in results:
         if res["result"] == res["goal"]:
             correct += 1
         else:
@@ -57,6 +84,9 @@ def evaluate(result, examples):
 
 
 def main():
+    """
+    Main function. (Test)
+    """
     model = DecisionModel()
     model.train()
     model.test()