module Stamina
  #
  # Provides utility methods for scoring binary classifiers from signatures
  #
  module Scoring

      #
      # From the signatures of a learned model and a actual, returns an object 
      # responding to all instance methods defined in the Scoring module.
      #
      def self.scoring(learned, actual, max_size=nil)
        unless learned.size==actual.size
          raise ArgumentError, "Signatures must be of same size (#{learned.size} vs. #{actual.size})"
        end
        max_size ||= learned.size
        max_size = learned.size if max_size > learned.size
        tp, fn, fp, tn = 0, 0, 0, 0
        (0...max_size).each do |i|
          positive, labeled_as = actual[i..i]=='1', learned[i..i]=='1'
          if positive==labeled_as
            positive ? (tp += 1) : (tn += 1)
          else
            positive ? (fn += 1) : (fp += 1)
          end
        end
        measures = { :true_positive  => tp,
                     :true_negative  => tn,
                     :false_positive => fp,
                     :false_negative => fn }
        measures.extend(Scoring)
        measures
      end

      #
      # Returns the number of positive strings correctly labeled as positive
      #
      def true_positive
        self[:true_positive]
      end

      #
      # Returns the number of negative strings correctly labeled as negative.
      #
      def true_negative
        self[:true_negative]
      end

      #
      # Returns the number of negative strings incorrectly labeled as positive.
      #
      def false_positive
        self[:false_positive]
      end

      #
      # Returns the number of positive strings incorrectly labeled as negative.
      #
      def false_negative
        self[:false_negative]
      end

      #
      # Returns the percentage of positive predictions that are correct
      #
      def precision
        true_positive.to_f/(true_positive + false_positive)
      end
      alias :positive_predictive_value :precision

      #
      # Returns the percentage of true negative over all negative
      # 
      def negative_predictive_value
        true_negative.to_f / (true_negative + false_negative)
      end

      #
      # Returns the percentage of positive strings that were predicted as being
      # positive
      #
      def recall
        true_positive.to_f / (true_positive + false_negative)
      end
      alias :sensitivity :recall
      alias :true_positive_rate :recall

      #
      # Returns the percentage of negative strings that were predicted as being
      # negative
      #
      def specificity
        true_negative.to_f / (true_negative + false_positive)
      end
      alias :true_negative_rate :specificity

      #
      # Returns the percentage of false positives
      #
      def false_positive_rate
        false_positive.to_f / (false_positive + true_negative)
      end

      #
      # Returns the percentage of false negatives
      #
      def false_negative_rate
        false_negative.to_f / (true_positive + false_negative)
      end

      #
      # Returns the likelihood that a predicted positive is an actual positive
      # 
      def positive_likelihood
        sensitivity / (1.0 - specificity)
      end

      #
      # Returns the likelihood that a predicted negative is an actual negative
      # 
      def negative_likelihood
       (1.0 - sensitivity) / specificity
      end

      #
      # Returns the percentage of predictions that are correct
      #
      def accuracy
        num = (true_positive + true_negative).to_f
        den = (true_positive + true_negative + false_positive + false_negative)
        num / den
      end

      #
      # Returns the error rate
      # 
      def error_rate
        num = (false_positive + false_negative).to_f
        den = (true_positive + true_negative + false_positive + false_negative)
        num / den
      end

      #
      # Returns the harmonic mean between precision and recall
      #
      def f_measure 
        2.0 * (precision * recall) / (precision + recall)
      end

      #
      # Returns the balanced classification rate (arithmetic mean between 
      # sensitivity and specificity)
      # 
      def balanced_classification_rate
        0.5 * (sensitivity + specificity)
      end
      alias :bcr :balanced_classification_rate

      #
      # Returns the balanced error rate (1 - bcr)
      # 
      def balanced_error_rate
        1.0 - balanced_classification_rate
      end
      alias :ber :balanced_error_rate

      #
      # Returns the harmonic mean between sensitivity and specificity
      # 
      def harmonic_balanced_classification_rate
        2.0 * (sensitivity * specificity) / (sensitivity + specificity)
      end
      alias :hbcr :harmonic_balanced_classification_rate
      alias :harmonic_bcr :harmonic_balanced_classification_rate
    
  end # module Scoring
end # module Stamina