stamina 0.4.0 → 0.5.0

data/lib/stamina/input_string.rb

@@ -1,123 +0,0 @@
-module Stamina
-  #
-  # An input string is a sequence of input symbols (symbols being letters appearing 
-  # on automaton edges) labeled as positive, negative or unlabeled (provided for test 
-  # samples and query strings).
-  #
-  # This class include the Enumerable module, that allows reasoning about
-  # ordered symbols. 
-  #
-  # == Detailed API
-  class InputString
-    include Enumerable
-  
-    #
-    # Creates an input string from symbols and positive or negative labeling.
-    #
-    # Arguments:
-    # - symbols: When an array is provided, it is duplicated by default to be kept 
-    #   internally. Set dup to false to avoid duplicating it (in both cases, the 
-    #   internal array will be freezed). When a String is provided, symbols array 
-    #   is created using <tt>symbols.split(' ')</tt> and then freezed. _dup_ is 
-    #   ignored in the case.
-    # - The positive argument may be true (positive string), false (negative one)
-    #   or nil (unlabeled).
-    #
-    # Raises:
-    # - ArgumentError if symbols is not an Array nor a String.
-    #
-    def initialize(symbols, positive, dup=true)
-      raise(ArgumentError,
-            "Input string expects an Array or a String: #{symbols} received",
-            caller) unless Array===symbols or String===symbols
-      @symbols = case symbols
-                   when String
-                     symbols.split(' ').freeze
-                   when Array
-                     (dup ? symbols.dup : symbols).freeze
-                 end
-      @positive = positive
-    end
-  
-    # 
-    # Checks if this input string is empty (aka lambda, i.e. contains no symbol). 
-    #
-    def empty?() @symbols.empty? end
-    alias :lambda? :empty?
-  
-    #
-    # Returns the string size, i.e. number of its symbols.
-    #
-    def size() @symbols.size end
-  
-    # 
-    # Returns the exact label of this string, being true (positive string)
-    # false (negative string) or nil (unlabeled)
-    #
-    def label() @positive end
-  
-    #
-    # Returns true if this input string is positively labeled, false otherwise.
-    #
-    def positive?() @positive==true end
-    
-    #
-    # Returns true if this input string is negatively labeled, false otherwise.
-    #
-    def negative?() @positive==false end
-    
-    #
-    # Returns true if this input string unlabeled.
-    #
-    def unlabeled?() @positive.nil? end
-  
-    # Copies and returns the same string, but switch the positive flag. This
-    # method returns self if it is unlabeled.
-    def negate
-      return self if unlabeled?
-      InputString.new(@symbols, !@positive, false)
-    end
-  
-    #
-    # Returns an array with symbols of this string. Returned array may not be 
-    # modified (it is freezed).
-    #
-    def symbols() @symbols end
-  
-    #
-    # Yields the block with each string symbol, in order. Has no effect without
-    # block.
-    #
-    def each() @symbols.each {|s| yield s if block_given? } end
-
-    #
-    # Checks equality with another InputString. Returns true if strings have same
-    # sequence of symbols and same labeling, false otherwise. Returns nil if _o_ 
-    # is not an InputString.
-    #
-    def ==(o)
-      return nil unless InputString===o
-      label == o.label and @symbols == o.symbols
-    end
-    alias :eql? :==
-  
-    #
-    # Computes a hash code for this string.
-    #
-    def hash
-      @symbols.hash + 37*positive?.hash
-    end
-  
-    #
-    # Prints this string in ADL.
-    #
-    def to_adl
-      str = (unlabeled? ? '?' : (positive? ? '+ ' : '- '))
-      str << @symbols.join(' ')
-      str
-    end
-    alias :to_s :to_adl
-    alias :inspect :to_adl
-    
-  end # class InputString
-end # module Stamina

data/lib/stamina/loader.rb

@@ -1 +0,0 @@
-require "quickl"

data/lib/stamina/markable.rb

@@ -1,42 +0,0 @@
-module Stamina
-  #
-  # Allows any object to be markable with user-data.
-  #
-  # This module is expected to be included by classes that want to implement the
-  # Markable design pattern. Moreover, if the instances of the including class
-  # respond to <tt>state_changed</tt>, this method is automatically invoked when
-  # marks change. This method is used by <tt>automaton</tt> in order to make it
-  # possible to track changes and check modified automata for consistency.
-  #
-  # == Detailed API
-  module Markable
-
-    # 
-    # Returns user-value associated to _key_, nil if no such key in user-data.
-    #
-    def [](key) @data[key] end
-
-    # 
-    # Associates _value_ to _key_ in user-data. Overrides previous value if 
-    # present.
-    #
-    def []=(key,value)
-      oldvalue = @data[key]
-      @data[key] = value
-      state_changed(:loaded_pair, [key,oldvalue,value]) if self.respond_to? :state_changed
-    end
-
-    # Removes a mark
-    def remove_mark(key)
-      oldvalue = @data[key]
-      @data.delete(key)
-      state_changed(:loaded_pair, [key,oldvalue,nil]) if self.respond_to? :state_changed
-    end
-
-    # Extracts the copy of attributes which can subsequently be modified.
-    def data
-      @data.nil? ? {} : @data.dup
-    end
-
-  end # module Markable
-end # module Stamina

data/lib/stamina/sample.rb

@@ -1,267 +0,0 @@
-module Stamina
-
-  #
-  # A sample as an ordered collection of InputString labeled as positive or negative.
-  #
-  # == Tips and tricks
-  # - loading samples from disk is easy thanks to ADL ! 
-  #
-  # == Detailed API
-  class Sample
-    include Enumerable
-  
-    # Number of strings in the sample
-    attr_reader :size
-  
-    # Number of positive strings in the sample
-    attr_reader :positive_count
-  
-    # Number of negative strings in the sample
-    attr_reader :negative_count
-  
-    #
-    # Creates an empty sample and appends it with args, by calling Sample#<< on
-    # each of them.
-    #
-    def self.[](*args) Sample.new << args end
-  
-    #
-    # Creates an empty sample.
-    #
-    def initialize(strings = nil)
-      @strings = []
-      @size, @positive_count, @negative_count = 0, 0, 0
-      strings.each{|s| self << s } unless strings.nil?
-    end
-    
-    #
-    # Returns true if this sample does not contain any string, 
-    # false otherwise.
-    #
-    def empty?() 
-      @size==0 
-    end
-  
-    #
-    # Adds a string to the sample. The _str_ argument may be an InputString instance,
-    # a String (parsed using ADL), a Sample instance (all strings are added) or an 
-    # Array (recurses on each element).
-    #
-    # Raises an InconsistencyError if the same string already exists with the 
-    # opposite label. Raises an ArgumentError if the _str_ argument is not recognized.
-    #
-    def <<(str)
-      case str
-        when InputString
-          #raise(InconsistencyError, "Inconsistent sample on #{str}", caller) if self.include?(str.negate)
-          @size += 1 
-          str.positive? ? (@positive_count += 1) : (@negative_count += 1)
-          @strings << str
-        when String
-          self << ADL::parse_string(str)
-        when Sample
-          str.each {|s| self << s}
-        when Array
-          str.each {|s| self << s}
-        else
-          raise(ArgumentError, "#{str} is not a valid argument.", caller)   
-      end
-      self
-    end
-    
-    #
-    # Returns true if a given string is included in the sample, false otherwise.
-    # This method allows same flexibility as << for the _str_ argument. 
-    #
-    def include?(str)
-      case str
-        when InputString
-          @strings.include?(str)
-        when String
-          include?(ADL::parse_string(str))
-        when Array
-          str.each {|s| return false unless include?(s)}
-          true
-        when Sample
-          str.each {|s| return false unless include?(s)}
-          true
-        else
-          raise(ArgumentError, "#{str} is not a valid argument.", caller)   
-      end
-    end
-    
-    #
-    # Compares with another sample _other_, which is required to be a Sample 
-    # instance. Returns true if the two samples contains the same strings (including 
-    # labels), false otherwise.
-    #
-    def ==(other)
-      include?(other) and other.include?(self)
-    end
-    alias :eql? :==
-    
-    # 
-    # Computes an hash code for this sample.
-    #
-    def hash
-      self.inject(37){|memo,str| memo + 17*str.hash}
-    end
-    
-    #
-    # Yields the block with each string. This method has no effect if no
-    # block is given.
-    #
-    def each
-      return unless block_given?
-      @strings.each {|str| yield str}
-    end
-    
-    #
-    # Yields the block with each positive string. This method has no effect if no
-    # block is given.
-    #
-    def each_positive
-      return unless block_given?
-      each {|str| yield str if str.positive?}
-    end
-    
-    # 
-    # Returns an enumerator on positive strings.
-    #
-    def positive_enumerator
-		  if RUBY_VERSION >= "1.9"
-        Enumerator.new(self, :each_positive)
-      else
-        Enumerable::Enumerator.new(self, :each_positive)
-			end
-    end
-  
-    # 
-    # Yields the block with each negative string. This method has no effect if no
-    # block is given.
-    #
-    def each_negative
-      each {|str| yield str if str.negative?}
-    end
-    
-    # 
-    # Returns an enumerator on negative strings.
-    #
-    def negative_enumerator
-		  if RUBY_VERSION >= "1.9"
-        Enumerator.new(self, :each_negative)
-      else
-        Enumerable::Enumerator.new(self, :each_negative)
-			end
-    end
-  
-    #
-    # Checks if the sample is correctly classified by a given classifier
-    # (expected to include the Stamina::Classfier module).
-    # Unlabeled strings are simply ignored.
-    #
-    def correctly_classified_by?(classifier)
-      classifier.correctly_classify?(self)
-    end
-      
-    #
-    # Computes and returns the binary signature of the sample. The signature
-    # is a String having one character for each string in the sample. A '1'
-    # is used for positive strings, '0' for negative ones and '?' for unlabeled.
-    #
-    def signature
-      signature = ''
-      each do |str|
-        signature << (str.unlabeled? ? '?' : str.positive? ? '1' : '0')
-      end
-      signature
-    end
-
-    #
-    # Takes only a given proportion of this sample and returns it as a new Sample.
-    #
-    def take(proportion = 0.5)
-      taken = Stamina::Sample.new
-      each_positive{|s| taken << s if Kernel.rand < proportion}
-      each_negative{|s| taken << s if Kernel.rand < proportion}
-      taken
-    end
-    
-    # 
-    # Prints an ADL description of this sample on the buffer.
-    #
-    def to_adl(buffer="")
-      self.inject(buffer) {|memo,str| memo << "\n" << str.to_adl}
-    end
-    alias :to_s :to_adl
-    alias :inspect :to_adl
-
-    #
-    # Converts a Sample to an (augmented) prefix tree acceptor. This method ensures 
-    # that the states of the PTA are in lexical order, according to the <code><=></code>
-    # operator defined on symbols. States reached by negative strings are tagged as
-    # non accepting and error.
-    #
-    def self.to_pta(sample)
-      thepta = Automaton.new do |pta|
-        initial_state = add_state(:initial => true, :accepting => false)
-
-        # Fill the PTA with each string
-        sample.each do |str|
-          # split string using the dfa
-          parsed, reached, remaining = pta.dfa_split(str, initial_state)
-    
-          # remaining symbols are not empty -> build the PTA
-          unless remaining.empty?
-            remaining.each do |symbol|
-              newone = pta.add_state(:initial => false, :accepting => false, :error => false)
-              pta.connect(reached, newone, symbol)
-              reached = newone
-            end
-          end
-    
-          # flag state      
-          str.positive? ? reached.accepting! : reached.error!
-          
-          # check consistency, should not arrive as Sample does not allow
-          # inconsistencies. Should appear only if _sample_ is not a Sample
-          # instance but some other enumerable.
-          raise(InconsistencyError, "Inconsistent sample on #{str}", caller)\
-            if (reached.error? and reached.accepting?)
-        end
-
-        # Reindex states by applying BFS
-        to_index, index = [initial_state], 0
-        until to_index.empty?
-          state = to_index.shift
-          state[:__index__] = index
-          state.out_edges.sort{|e,f| e.symbol<=>f.symbol}.each{|e| to_index << e.target} 
-          index += 1 
-        end
-      end
-
-      # Now we rebuild a fresh one with states in order.
-      # This look more efficient that reordering states of the PTA
-      Automaton.new do |ordered|
-        ordered.add_n_states(thepta.state_count)
-        thepta.each_state do |pta_state|
-          source = ordered.ith_state(pta_state[:__index__])
-          source.initial!   if pta_state.initial?
-          source.accepting! if pta_state.accepting?
-          source.error!     if pta_state.error?
-          pta_state.out_edges.each do |e| 
-            target = ordered.ith_state(e.target[:__index__])
-            ordered.connect(source, target, e.symbol)
-          end
-        end
-      end
-
-    end
-
-    # Convenient shortcut for Sample.to_pta(sample_instance)
-    def to_pta
-      Sample.to_pta(self)
-    end
-    
-  end # class Sample
-end # module Stamina

data/lib/stamina/scoring.rb

@@ -1,213 +0,0 @@
-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
-
-      MEASURES = [
-        :false_positive, :false_negative,
-        :true_positive, :true_negative,
-        :accuracy, :error_rate,
-        :precision, :recall, :f_measure,
-        :false_positive_rate, :false_negative_rate,
-        :true_positive_rate, :true_negative_rate,
-        :positive_predictive_value, :negative_predictive_value,
-        :sensitivity, :specificity,
-        :positive_likelihood, :negative_likelihood,
-        :balanced_classification_rate, :balanced_error_rate, :harmonic_bcr
-      ]
-
-      def to_h
-        h = {}
-        MEASURES.each do |m|
-          h[m] = self.send(m.to_sym)
-        end
-        h
-      end
-
-      def to_s
-        s = ""
-        MEASURES.each do |m|
-          vals = case val = self.send(m.to_sym)
-            when Integer
-              "%s" % val
-            when Float
-              "%.5f" % val
-            else
-              "%s" % val
-          end
-          s += "%30s: %10s\n" % [m.to_s, vals]
-        end
-        s
-      end
-    
-  end # module Scoring
-end # module Stamina