updated javadoc

Author: dvilaverde

src/main/java/rocks/vilaverde/classifier/Classifier.java

@@ -4,6 +4,11 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * Interface to be defined by classifier implementations. A classifier will provide a classification
+ * for a provided feature vector.
+ * @param <T>
+ */
 public interface Classifier<T> {
 
   /**

src/main/java/rocks/vilaverde/classifier/FeatureVector.java

@@ -8,32 +8,65 @@ public class FeatureVector {
     private final Features features;
     private final double[] vector;
 
+    /**
+     * Constructor
+     * @param features the features
+     */
     public FeatureVector(Features features) {
         this.features = features;
         this.vector = new double[features.getLength()];
     }
 
+    /**
+     * Add a feature by name.
+     * @param feature name of the feature
+     * @param value the feature value
+     * @return the FeatureVector
+     */
     public FeatureVector add(String feature, boolean value) {
         add(feature, value ? 1.0 : 0.0);
         return this;
     }
 
+    /**
+     * Add a feature by index.
+     * @param index index of the feature
+     * @param value the feature value
+     * @return the FeatureVector
+     */
     public FeatureVector add(int index, boolean value) {
         add(index, value ? 1.0 : 0.0);
         return this;
     }
 
+    /**
+     * Add a feature by index.
+     * @param index index of the feature
+     * @param value the feature value
+     * @return the FeatureVector
+     */
     public FeatureVector add(int index, double value) {
         this.vector[index] = value;
         return this;
     }
 
+    /**
+     * Add a feature by name.
+     * @param feature name of the feature
+     * @param value the feature value
+     * @return the FeatureVector
+     */
     public FeatureVector add(String feature, double value) {
         int index = this.features.getFeatureIndex(feature);
         add(index, value);
         return this;
     }
 
+    /**
+     * Get the feature value by index.
+     * @param index the feature index
+     * @return the double value
+     */
     public double get(int index) {
         if (index >= vector.length) {
             throw new IllegalArgumentException(String.format("index must be less than %d", index));
@@ -42,11 +75,21 @@ public double get(int index) {
         return vector[index];
     }
 
+    /**
+     * Get the feature value by name.
+     * @param feature the feature name
+     * @return the double value
+     */
     public double get(String feature) {
         int index = features.getFeatureIndex(feature);
         return get(index);
     }
 
+    /**
+     * Returns true when the feature name is present in this feature vector.
+     * @param feature feature name
+     * @return boolean
+     */
     public boolean hasFeature(String feature) {
         return this.features.getFeatureNames().contains(feature);
     }

src/main/java/rocks/vilaverde/classifier/Features.java

@@ -37,6 +37,11 @@ public static Features of(String ... features) {
         return new Features(features);
     }
 
+    /**
+     * Convert a Set of Strings to a Features object.
+     * @param features the Set of strings
+     * @return a Features
+     */
     public static Features fromSet(Set<String> features) {
         return new Features(features.toArray(new String[0]));
     }
@@ -56,6 +61,10 @@ FeatureVector newSample() {
         return new FeatureVector(this);
     }
 
+    /**
+     * Add a Feature to the set of features.
+     * @param feature Feature name
+     */
     public void addFeature(String feature) {
         if (!allowFeatureAdd) {
             throw new IllegalStateException("features are immutable");
@@ -72,10 +81,19 @@ public void addFeature(String feature) {
         }
     }
 
+    /**
+     * Get the number of features in this Features.
+     * @return the size of teh features.
+     */
     public int getLength() {
         return this.features.size();
     }
 
+    /**
+     * Get the index of a feature from the feature vector.
+     * @param feature the feature name
+     * @return the position in the array that will hold this feature
+     */
     public int getFeatureIndex(String feature) {
         Integer index = this.features.get(feature);
         if (index == null) {
@@ -85,6 +103,10 @@ public int getFeatureIndex(String feature) {
         return index;
     }
 
+    /**
+     * Get the names of the features in the model.
+     * @return Set of feature names
+     */
     public Set<String> getFeatureNames() {
         return Collections.unmodifiableSet(this.features.keySet());
     }

src/main/java/rocks/vilaverde/classifier/Operator.java

@@ -3,10 +3,15 @@
 import java.util.function.BiFunction;
 
 public enum Operator {
+  /** Less than */
   LT("<", (leftOperand, rightOperand) -> leftOperand < rightOperand),
+  /** Greater than */
   GT(">", (leftOperand, rightOperand) -> leftOperand > rightOperand),
+  /** Less than or Equal */
   LT_EQ("<=", (leftOperand, rightOperand) -> leftOperand <= rightOperand),
+  /** Greater than or equal */
   GT_EQ(">=", (leftOperand, rightOperand) -> leftOperand >= rightOperand),
+  /** Equal */
   EQ("=", (leftOperand, rightOperand) -> doubleIsSame(leftOperand, rightOperand, .0001));
 
   private final String operator;
@@ -42,10 +47,20 @@ private static boolean doubleIsSame(double d1, double d2, double delta) {
     }
   }
 
+  /**
+   * Apply this operation on the operands.
+   * @param leftOperand the value left of the operator
+   * @param rightOperand the value right of the operator
+   * @return result of the operation
+   */
   public boolean apply(Double leftOperand, Double rightOperand) {
     return this.operation.apply(leftOperand, rightOperand);
   }
 
+  /**
+   * For debugging
+   * @return String
+   */
   @Override
   public String toString() {
     return operator;

src/main/java/rocks/vilaverde/classifier/Prediction.java

@@ -5,7 +5,15 @@
  */
 public interface Prediction<T> {
 
+  /**
+   * Gets the prediction value.
+   * @return type T
+   */
   T get();
 
+  /**
+   * Gets the probability of the prediction.
+   * @return an array of double values
+   */
   double[] getProbability();
 }

src/main/java/rocks/vilaverde/classifier/dt/AbstractDecisionTreeVisitor.java

@@ -3,28 +3,48 @@
 import rocks.vilaverde.classifier.Visitor;
 
 /**
- * feature6 a {@link DecisionTreeClassifier} using Depth first traversal.
+ * Visits a {@link DecisionTreeClassifier} using Depth first traversal.
  */
 public abstract class AbstractDecisionTreeVisitor implements Visitor<TreeNode> {
 
+  /**
+   * Visit a generic TreeNode.
+   * @param object the the object being visited
+   */
   @Override
   public void visit(TreeNode object) {
     visitBase(object);
   }
 
+  /**
+   * Base method that is visited by all TreeNode objects.
+   * @param object
+   */
   protected void visitBase(TreeNode object) {
   }
 
+  /**
+   * Visit the EndNode, and by default will call visitBase first.
+   * @param object
+   */
   public void visit(EndNode object) {
     visitBase(object);
   }
 
+  /**
+   * Visit the ChoiceNode, and by default will call visitBase first.
+   * @param object
+   */
   public void visit(ChoiceNode object) {
     visitBase(object);
 
     object.getChild().accept(this);
   }
 
+  /**
+   * Visit the DecisionNode, and by default will call visitBase first.
+   * @param object
+   */
   public void visit(DecisionNode object) {
     visitBase(object);
 

src/main/java/rocks/vilaverde/classifier/dt/ChoiceNode.java

@@ -9,35 +9,66 @@
 public class ChoiceNode extends TreeNode {
   private final Operator op;
   private final Double value;
-
   private TreeNode child;
 
+  /**
+   * Creates a ChoiceNode from an Operator and a value to be used for evaluation.
+   * @param op the Operator
+   * @param value the value
+   * @return the ChoiceNode
+   */
   public static ChoiceNode create(Operator op, Double value) {
     return new ChoiceNode(op, value);
   }
 
+  /**
+   * Private constructor, use the creator static function.
+   * @param op the Operator
+   * @param value the value
+   */
   private ChoiceNode(Operator op, Double value) {
     this.op = op;
     this.value = value;
   }
 
+  /**
+   * Add a child node to the ChoiceNode.
+   * @param child the child to add
+   */
   public void addChild(TreeNode child) {
     this.child = child;
   }
 
+  /**
+   * Accessor for the child TreeNode
+   * @return the TreeNode
+   */
   public TreeNode getChild() {
     return child;
   }
 
+  /**
+   * Accepts a visitor and calls visit using this node.
+   * @param visitor the visitor
+   */
   @Override
   public void accept(AbstractDecisionTreeVisitor visitor) {
     visitor.visit(this);
   }
 
+  /**
+   * For debugging.
+   * @return The formatted String.
+   */
   public String toString() {
     return String.format("%s %s", op.toString(), value.toString());
   }
 
+  /**
+   * Evaluate this ChoiceNode against the provided value.
+   * @param featureValue the feature value this choice will be evaluated against.
+   * @return a boolean result of the evaluation.
+   */
   public boolean eval(double featureValue) {
     return op.apply(featureValue, value);
   }

src/main/java/rocks/vilaverde/classifier/dt/PredictionFactory.java

@@ -8,8 +8,17 @@
 @FunctionalInterface
 public interface PredictionFactory<T> {
 
+    /**
+     * The prediction class is of type boolean in the model.
+     */
     PredictionFactory<Boolean> BOOLEAN = value ->  Boolean.valueOf(value.toLowerCase());
+    /**
+     * The prediction class is of type Integer in the model.
+     */
     PredictionFactory<Integer> INTEGER = Integer::valueOf;
+    /**
+     * The prediction class is of type Double in the model.
+     */
     PredictionFactory<Double> DOUBLE = Double::parseDouble;
 
     /**

src/main/java/rocks/vilaverde/classifier/dt/TreeClassifier.java

@@ -9,5 +9,10 @@
  */
 public interface TreeClassifier<T> extends Classifier<T> {
 
+    /**
+     * Gets a Prediction for a provided FeatureVector.
+     * @param features the feature vector
+     * @return a Prediction
+     */
     Prediction<T> getClassification(FeatureVector features);
 }

src/main/java/rocks/vilaverde/classifier/dt/TreeNode.java

@@ -2,6 +2,9 @@
 
 import rocks.vilaverde.classifier.Visitable;
 
+/**
+ * Base class for all nodes in a Decision Tree.
+ */
 public abstract class TreeNode implements Visitable<TreeNode, AbstractDecisionTreeVisitor> {
 
   /**

src/main/java/rocks/vilaverde/classifier/dt/visitors/FeatureNameVisitor.java

@@ -24,6 +24,10 @@ public void visit(DecisionNode object) {
     super.visit(object);
   }
 
+  /**
+   * Get the Set of strings representing the features in the model.
+   * @return Set of String
+   */
   public Set<String> getFeatureNames() {
     return featureNames;
   }

src/main/java/rocks/vilaverde/classifier/ensemble/RandomForestClassifier.java

@@ -140,6 +140,11 @@ public double[][] predict_proba(FeatureVector ... samples) {
         return probabilities;
     }
 
+    /**
+     * Predict for a single sample.
+     * @param sample the FeatureVector
+     * @return the prediction
+     */
     protected T predictSingle(FeatureVector sample) {
         return getClassification(sample).get();
     }