Factor Tutorial

package cc.factorie.tutorial
object TutorialFactors extends App {
  import org.junit.Assert._
  import cc.factorie._
  import cc.factorie.la._
  import cc.factorie.variable._
  import scala.Tuple2
  import cc.factorie.model._
  import scala.Tuple2
    
    // First we'll create some variables for us as Factor neighbors. 
    val v1 = new IntegerVariable(1)
    val v2 = new DoubleVariable(2.0)
    val v3 = new IntegerVariable(3)
    

    // Here is a factor with one neighbor.
    val f1 = new Factor1(v1) {
      def score(i:Int) = if (i == 1) 0.0 else -1.0
    }

    // Naturally, then we can get the factor's score for particular values of the neighboring variable(s).
    println("First factor score for value 0 is "+f1.score(0))
    assertEquals(-1.0, f1.score(0), 0.01)
    
    // We can also ask for the score resulting from the neighbors current values.
    println("First factor score for current neighbor value is "+f1.currentScore)
    assertEquals(0.0, f1.currentScore, 0.1)
    
    // Here is a Factor with two neighbors.
    // The second neighbor is a DoubleVariable and has value type Double.
    val f2 = new Factor2(v1, v2) {
      def score(i:Int, j:Double) = i * j
    }
    println("Second factor score is "+f2.currentScore)
    assertEquals(2.0, f2.currentScore, 0.01)

    // Given a factor I can get its list of neighbors, or individual neighbors
    println("Second factor neighbors are "+f2.variables)
    println("Second factor first neighbor is "+f2.variable(0))
    assert(f2.variable(0) == v1)
    
    // We can also ask if a Factor has a variable among its neighbors
    if (f2.touches(v3)) println("Second factor has v3 as a neighbor.")
    assert(!f2.touches(v3))
    
    // Factors can be given a customized named used in their toString method
    val f2b = new Factor2(v1, v2) {
      def score(i:Int, j:Double) = i * j
      override def factorName = "Factor2B"
    }
    println("Factor with custom name "+f2b)
    assertEquals("Factor2B", f2b.factorName)
    
    // We can get an Assignment object that captures the current values of the neighbors.
    val a2: Assignment2[IntegerVariable,DoubleVariable] = f2.currentAssignment
    v2 := 4.4 // Here we give v2 a new value.
    println("Second neighbor of second factor had value "+a2(v2))
    assertEquals(2.0, a2(v2), 0.01)
    
    // We can ask for a factor's score using the values in an Assignment
    // rather than the neighbors current values
    println("Second factor's score from old assignment is "+f2.assignmentScore(a2))
    assertEquals(2.0, f2.assignmentScore(a2), 0.01)
    
    // The Assignment object could contain values for more variables than the neighbors
    val as = new HashMapAssignment(v1, v2, v3)
    as.update[IntegerVariable](v1, 44)
    println("Second factor's score from a new assignment is "+f2.assignmentScore(as))
    assertEquals(44*4.4, f2.assignmentScore(as), 0.01)
    
    // All factors also have "statistics"
    // This is some arbitrary object that holds information sufficient to obtain a score.
    // (Although this sufficiency is not enforced.)
    val s2 = f2.statistics(77,8.8)
    
    // As with "score" we can get the statistics corresponding to the neighbors current values
    val s2c = f2.currentStatistics
    
    // The default statistics are a Tuple containing the values of the neighbors.
    // However the known return type is Any, so it must be cast to use.
    // (This lack of typing is because we want the method to be flexibly override-able in subclasses.)
    if (s2.asInstanceOf[(Int, Double)]._2 == 4.4)
      println("The second factor's second value is 4.4")
    assertEquals(8.8, s2.asInstanceOf[(Int, Double)]._2, 0.01)

    // Some subclasses of Factor override the method to return more specific types.
    // If the Tuple statistics are sufficient for your needs, 
    // and you want the "statistics" method's return type to be the correct Tuple
    // use the classes TupleFactor*
    val f3 = new TupleFactorWithStatistics3(v1, v2, v3) {
      def score(i:Int, j:Double, k:Int) = if (i == k) j else 0.0
    }
    println("The current value of the third neighbor is "+f3.currentStatistics._3)
    assertEquals(3.0, f3.currentStatistics._3, 0.01)
    
    // The various Factor subclasses containing "WithStatistics" in the class name
    // all contain a new final definition of the "statistics" method.
    // For example, if I subclass TupleFactorWithStatistics3, I cannot redefine the "statistics" method.
    val f3b = new TupleFactorWithStatistics3(v1, v2, v3) {
      def score(i:Int, j:Double, k:Int) = if (i == k) j else 0.0
      // If uncommented, the next line would cause a compilation error:
      //def statistics(i:Int, j:Double, k:Int) = Tuple(i, k)
    }
    
    // In the plain "Factor1-4" classes you can override statistics to return any type you like,
    // but you have to set the type member StatisticsType to match.
    val f4 = new Factor2(v1, v3) {
      type StatisticsType = Boolean
      override def statistics(i:Int, j:Int): Boolean = i == j
      def score(i:Int, j:Int) = if (statistics(i, j)) 1.0 else -1.0
    }
    
    // Factors with Tensor-valued statistics are widely-used.
    
    // First let's make some Tensor-valued variables.
    object LabelDomain extends CategoricalDomain(List("politics", "sports", "arts"))
    class Label(initialValue:String) extends CategoricalVariable(initialValue) { def domain = LabelDomain }
    val label1 = new Label("arts")
    val label2 = new Label("arts")
    val label3 = new Label("arts")
    // Remember, BooleanVariables have value BooleanValue, which inherits from SingletonBinaryTensor1
    val flag1 = new BooleanVariable(false) 
    val flag2 = new BooleanVariable(true)
    
    // Here is a factor whose statistics are an outer product of the Tensor values of both neighbors.
    // The score is the dot product between this tensor an a Tensor of "weightsSet" parameters.
    val f5 = new Factor2(label1, label2) {
      type StatisticsType = Tensor
      val weights = new DenseTensor2(Array(Array(2.0, 1.0, 0.0), Array(1.0, 2.0, 1.0), Array(0.0, 1.0, 2.0)))
      // Label#Value is a CategoricalValue[String], and a subclass of SingletonBinaryTensor1
      override def statistics(lv1:Label#Value, lv2:Label#Value): Tensor = lv1 outer lv2
      def score(lv1:Label#Value, lv2:Label#Value): Double = weights dot statistics(lv1, lv2) 
    }

    val f6 = new TensorFactor2(flag1, flag2) {
      val weights = new DenseTensor2(Array(Array(3.0, 1.0), Array(2.0, 4.0)))
      override def statistics(fv1:BooleanValue, fv2:BooleanValue): Tensor = fv1 outer fv2
      def statisticsScore(tensor:Tensor): Double = weights dot tensor
    }
    

    val f7 = new TensorFactorWithStatistics2(flag1, flag2) {
      val weights = new DenseTensor2(Array(Array(3.0, 1.0), Array(2.0, 4.0)))
      def statisticsScore(tensor:Tensor): Double = weights dot tensor
    }
    

    val f8 = new DotFactorWithStatistics2(flag1, flag2) {
      val weights = new DenseTensor2(Array(Array(3.0, 1.0), Array(2.0, 4.0)))
    }
    

    val f9 = new DotFactor4(label1, label2, label3, flag1) {
      val weights = new DenseTensor2(Array(Array(2.0, 1.0, 0.0), Array(1.0, 2.0, 1.0), Array(0.0, 1.0, 2.0)))
      override def statistics(lv1:Label#Value, lv2:Label#Value, lv3:Label#Value, fv2:BooleanValue): Tensor = 
        if (flag1.booleanValue) lv1 outer lv2 else lv1 outer lv3
    }
   
    // Naturally, we can define a class of Factors all sharing the same "score" method
    class MyFactor(n1:IntegerVariable, n2:IntegerVariable) extends Factor2(n1, n2) {
      def score(i:Int, j:Int) = if (i == j) 1.0 else -1.0
    }
    

    val mf1 = new MyFactor(v1, v3)
    val mf2 = new MyFactor(v1, v3)
    if (mf1 == mf2) println("Two factors are equal.")
    assert(mf1 == mf2)

    object WordDomain extends CategoricalDomain(List("beat", "beautiful", "election"))
    // TODO Consider interface improvements to CategoricalVectorDomain initialization.
    object ArticleDomain extends CategoricalVectorDomain[String] { override def dimensionDomain = WordDomain }
    class Article(ws:Iterable[String]) extends BinaryFeatureVectorVariable[String](ws) {
      def domain = ArticleDomain
    }

    class MyClassifier(label:Label, article:Article) extends DotFactorWithStatistics2(label, article) {
      val weights = new DenseTensor2(LabelDomain.size, WordDomain.size)
      weights(LabelDomain.index("politics"), WordDomain.index("beat")) = 3.0
      weights(LabelDomain.index("politics"), WordDomain.index("beautiful")) = 2.0
      weights(LabelDomain.index("politics"), WordDomain.index("election")) = 5.0
      weights(LabelDomain.index("sports"), WordDomain.index("beat")) = 4.0
      weights(LabelDomain.index("sports"), WordDomain.index("beautiful")) = 1.0
      weights(LabelDomain.index("sports"), WordDomain.index("election")) = -1.0
      weights(LabelDomain.index("arts"), WordDomain.index("beat")) = -2.0
      weights(LabelDomain.index("arts"), WordDomain.index("beautiful")) = 5.0
      weights(LabelDomain.index("arts"), WordDomain.index("election")) = 1.0
    }
    
    val a1 = new Article("beat election".split(" "))
    val l1 = new Label("politics")
    val cf = new MyClassifier(l1, a1)
    
    // Any now we can do simple exhaustive inference
    var maxScore = Double.NegativeInfinity
    var maxLabeling = LabelDomain.head
    for (labeling <- LabelDomain) {
      l1.set(labeling)(null)
      val score = cf.currentScore
      if (score > maxScore) {
        maxScore = score
        maxLabeling = labeling
      }
    }
    println("When scoring "+a1+" the highest scoring label value is "+maxLabeling)
}