stamina 0.4.0 → 0.5.0

data/lib/stamina/command/metrics.rb

@@ -1,51 +0,0 @@
-module Stamina
-  class Command
-    # 
-    # Prints metrics about an automaton or sample
-    #
-    # SYNOPSIS
-    #   #{program_name} #{command_name} [file.adl]
-    #
-    # OPTIONS
-    # #{summarized_options}
-    #
-    class Metrics < Quickl::Command(__FILE__, __LINE__)
-      include Robustness
-      
-      # Install options
-      options do |opt|
-      
-      end # options
-
-      # Command execution
-      def execute(args)
-        raise Quickl::Help unless args.size <= 1
-
-        # Loads the target automaton
-        input = if args.size == 1
-          File.read assert_readable_file(args.first)
-        else
-          $stdin.readlines.join("\n")
-        end
-        
-        # Flush metrics 
-        begin
-          target = Stamina::ADL::parse_automaton(input)
-          puts "Alphabet size:   #{target.alphabet_size}"
-          puts "State count:     #{target.state_count}"
-          puts "Edge count:      #{target.edge_count}"
-          puts "Degree (avg):    #{target.avg_degree}"
-          puts "Accepting ratio: #{target.accepting_ratio}"
-          puts "Depth:           #{target.depth}"
-        rescue ADL::ParseError 
-          sample = Stamina::ADL::parse_sample(input)
-          puts "Size:     #{sample.size}"
-          puts "Positive: #{sample.positive_count} (#{sample.positive_count.to_f / sample.size})"
-          puts "Negative: #{sample.negative_count} (#{sample.negative_count.to_f / sample.size})"
-        end
-      end
-      
-    end # class Metrics
-  end # class Command
-end # module Stamina
-

data/lib/stamina/command/robustness.rb

@@ -1,22 +0,0 @@
-module Stamina
-  class Command
-    module Robustness
-
-      # Checks that a given file is readable or raises a Quickl::IOAccessError
-      def assert_readable_file(file)
-        raise Quickl::IOAccessError, "File #{file} does not exists" unless File.exists?(file)
-        raise Quickl::IOAccessError, "File #{file} cannot be read"  unless File.readable?(file)
-        file
-      end
-      
-      # Checks that a given file is writable or raises a Quickl::IOAccessError
-      def assert_writable_file(file)
-        raise Quickl::IOAccessError, "File #{file} cannot be written" \
-          unless not(File.exists?(file)) or File.writable?(file)
-        file
-      end
-      
-    end # module Robustness
-  end # class Command
-end # module Stamina
-

data/lib/stamina/command/score.rb

@@ -1,35 +0,0 @@
-module Stamina
-  class Command
-    # 
-    # Scores the labelling of a sample by an automaton
-    #
-    # SYNOPSIS
-    #   #{program_name} #{command_name} sample.adl automaton.adl
-    #
-    # OPTIONS
-    # #{summarized_options}
-    #
-    class Score < Quickl::Command(__FILE__, __LINE__)
-      include Robustness
-
-      # Install options
-      options do |opt|
-
-      end # options
-
-      # Command execution
-      def execute(args)
-        raise Quickl::Help unless args.size == 2
-        sample    = Stamina::ADL::parse_sample_file assert_readable_file(args.first)
-        automaton = Stamina::ADL::parse_automaton_file assert_readable_file(args.last)
-
-        classified_as = automaton.signature(sample)
-        reference = sample.signature
-        scoring = Scoring.scoring(classified_as, reference)
-        puts scoring.to_s
-      end
-      
-    end # class Score
-  end # class Command
-end # module Stamina
-

data/lib/stamina/errors.rb

@@ -1,23 +0,0 @@
-module Stamina
-  
-  # Raised when an algorithm explicitely abords something
-  class Abord < StandardError; end
-
-  # Main class of all stamina errors.
-  class StaminaError < StandardError; end
-  
-  # Raised by samples implementations and other induction algorithms
-  # when a sample is inconsistent (same string labeled as being both 
-  # positive and negative)
-  class InconsistencyError < StaminaError; end
-  
-  # Specific errors of the ADL module.
-  module ADL
-    
-    # Raised by the ADL module when an automaton, string or sample
-    # format is violated at parsing time.
-    class ParseError < StaminaError; end
-  
-  end
-
-end # module Stamina

data/lib/stamina/ext/math.rb

@@ -1,20 +0,0 @@
-if RUBY_VERSION < "1.9"
-
-  def Math.log2( x )
-    Math.log( x ) / Math.log( 2 )
-  end
- 
-  def Math.logn( x, n )
-    Math.log( x ) / Math.log( n )
-  end
-
-end
-
-def Math.max(i, j)
-  i > j ? i : j
-end
-
-def Math.min(i, j)
-  i < j ? i : j
-end
-

data/lib/stamina/induction/blue_fringe.rb

@@ -1,265 +0,0 @@
-module Stamina
-  module Induction
-    
-    #
-    # Implementation of the BlueFringe variant of the RPNI algorithm (with the blue-fringe
-    # heuristics).
-    #
-    # See Lang, K., B. Pearlmutter, andR. Price. 1998. Results of the Abbadingo One DFA
-    # Learning Competition and a New Evidence-Driven State Merging Algorithm, In Grammatical 
-    # Inference, pp. 1–12. Ames, IO: Springer-Verlag.
-    #
-    # Example:
-    #   # sample typically comes from an ADL file
-    #   sample = Stamina::ADL.parse_sample_file('sample.adl')
-    #
-    #   # let BlueFringe build the smallest dfa
-    #   dfa = Stamina::Induction::BlueFringe.execute(sample, {:verbose => true})
-    #
-    # Remarks:
-    # - Constructor and instance methods of this class are public but not intended 
-    #   to be used directly. They are left public for testing purposes only.
-    # - Having read the Stamina::Induction::BlueFringe base algorithm may help undertanding
-    #   this variant.
-    # - This class intensively uses the Stamina::Induction::UnionFind class and 
-    #   methods defined in the Stamina::Induction::Commons module which are worth
-    #   reading to understand the algorithm implementation.
-    #
-    class BlueFringe
-      include Stamina::Induction::Commons
-      
-      # Union-find data structure used internally
-      attr_reader :ufds
-      
-      # Creates an algorithm instance with given options.
-      def initialize(options={})
-        raise ArgumentError, "Invalid options #{options.inspect}" unless options.is_a?(Hash)
-        @options = DEFAULT_OPTIONS.merge(options)
-        @score_cache = {}
-      end
-
-      #
-      # Computes the score of a single (group) merge. Returned value is 1 if both are 
-      # accepting states or both are error states and 0 otherwise. Note that d1 and d2
-      # are expected to be merge compatible as this method does not distinguish this 
-      # case.  
-      #
-      def merge_score(d1, d2)
-        # Score of 1 if both accepting or both error
-        ((d1[:accepting] and d2[:accepting]) or (d1[:error] and d2[:error])) ? 1 : 0
-      end
-      
-      #
-      # Merges a state of rank j with a state of lower rank i. This merge method 
-      # includes merging for determinization. It returns nil if the merge is 
-      # incompatible, a merge score otherwise.
-      #
-      # Preconditions:
-      # - States denoted by i and j are expected leader states (non merged ones)
-      # - States denoted by i and j are expected to be different
-      #
-      # Postconditions:
-      # - Union find is refined, states i and j having been merged, as well as all
-      #   state pairs that need to be merged to ensure the deterministic property
-      #   of the quotient automaton.
-      # - If the resulting quotient automaton is consistent with the negative sample, 
-      #   this method returns the number of accepting pairs + the number of error pairs 
-      #   that have been merged. The refined union-find correctly encodes the quotient 
-      #   automaton. Otherwise, the method returns nil and the union-find information 
-      #   must be considered inaccurate.
-      #
-      def merge_and_determinize(i, j)
-        # Make the union (keep merging score as well as additional merges to be performed
-        # in score and determinization, respectively). Recompute the user data attached to 
-        # the new state group (new_data)
-        determinization, score = [], nil
-        @ufds.union(i, j) do |d1, d2|
-          # states are incompatible if new_data cannot be created because it would
-          # lead to merge and error and an accepting state. We simply return nil in this
-          # case...
-          return nil unless (new_data = merge_user_data(d1, d2, determinization))
-          # otherwise, we score
-          score = merge_score(d1, d2)
-          # and we let the union find keep the new_data for the group
-          new_data
-        end
-        
-        # Merge for determinization starts here, based on the determinization array
-        # computed as a side effect of merge_user_data
-        determinization.each do |pair|
-          # we take the leader states of the pair to merge
-          pair = pair.collect{|i| @ufds.find(i)} 
-          # do nothing if already the same leader state
-          next if pair[0]==pair[1]
-          # otherwise recurse and keep subscore
-          subscore = merge_and_determinize(pair[0], pair[1]) 
-          # failure if merging for determinization led to merge error and accepting 
-          # states
-          return nil if subscore.nil?
-          # this is the new score
-          score += subscore
-        end
-
-        score
-      end
-      
-      #
-      # Evaluates the score of merging states i and j. Returns nil if the states are
-      # cannot be merged, a positive score otherwise.
-      #
-      # Preconditions:
-      # - States denoted by i and j are expected leader states (non merged ones)
-      # - States denoted by i and j are expected to be different
-      #
-      # Postconditions:
-      # - Returned value is nil if the quotient automaton would be incompatible with 
-      #   the sample. Otherwise a positive number is returned, encoding the number of
-      #   interresting pairs that have been merged (interesting = both accepting or both
-      #   error)
-      # - The union find is ALWAYS restored to its previous value after merging has 
-      #   been evaluated and is then seen unchanged by the caller.
-      #
-      def merge_and_determinize_score(i, j)
-        score = @score_cache[[i,j]] ||= begin
-          # score the merging, always rollback the transaction
-          score = nil
-          @ufds.transactional do
-            score = merge_and_determinize(i, j)
-            false
-          end
-          score || -1
-        end
-        score == -1 ? nil : score
-      end
-
-      #
-      # Computes the fringe given the current union find. The fringe is returned as an
-      # array of state indices.
-      #
-      # Postconditions:
-      # - Returned array contains indices of leader states only.
-      # - Returned array is disjoint with the kernel.
-      #
-      def fringe
-        fringe = []
-        @kernel.each do |k1|
-          delta = @ufds.mergeable_data(k1)[:delta]
-          delta.each_pair{|symbol, target| fringe << @ufds.find(target)}
-        end
-        (fringe - @kernel).sort
-      end
-      
-      #
-      # Main method of the algorithm. Refines the union find passed as first argument 
-      # by merging well chosen state pairs. Returns the refined union find.
-      #
-      # Preconditions:
-      # - The union find _ufds_ is correctly initialized (contains :initial, :accepting,
-      #   and :error boolean flags as well as a :delta sub hash)
-      #
-      # Postconditions:
-      # - The union find has been refined. It encodes a quotient automaton (of the PTA
-      #   it comes from) such that all positive and negative strings of the underlying
-      #   sample are correctly classified by it.
-      #
-      def main(ufds)
-        info("Starting BlueFringe (#{ufds.size} states)")
-        @ufds, @kernel, @score_cache = ufds, [0], {}
-        
-        # we do it until the fringe is empty (compute it only once each step)
-        until (the_fringe=fringe).empty?
-          # state to consolidate (if any)
-          to_consolidate = nil
-          # best candidate [source index, target index, score]
-          best = [nil, nil, -1]
-          
-          # for each state on the fringe as merge candidate
-          the_fringe.each do |candidate|
-            to_consolidate = candidate
-            
-            # evaluate score of merging candidate with each kernel state
-            @kernel.each do |target|
-              score = merge_and_determinize_score(candidate, target)
-              unless score.nil?
-                # if a score has been found, the candidate will not be 
-                # consolidated. We keep it as best if its better than the
-                # previous one
-                to_consolidate = nil
-                best = [candidate, target, score] if score > best[2]
-              end
-            end
-            
-            # No possible target, break the loop (will consolidate right now)!
-            break unless to_consolidate.nil?
-          end
-          
-          # If not found, the last candidate must be consolidated. Otherwise, we 
-          # do the best merging
-          unless to_consolidate.nil?
-            info("Consolidation of #{to_consolidate}")
-            @kernel << to_consolidate
-          else
-            @score_cache.clear
-            info("Merging #{best[0]} and #{best[1]} [#{best[2]}]")
-            # this one should never fail because its score was positive before
-            raise "Unexpected case" unless merge_and_determinize(best[0], best[1])
-          end
-          
-          # blue_fringe does not guarantee that it will not merge a state of lower rank
-          # with a kernel state. The kernel should then be update at each step to keep
-          # lowest indices for the whole kernel, and we sort it
-          @kernel = @kernel.collect{|k| @ufds.find(k)}.sort
-        end
-        
-        # return the refined union find now
-        @ufds
-      end
-      
-      #
-      # Build the smallest DFA compatible with the sample given as input.
-      #
-      # Preconditions:
-      # - The sample is consistent (does not contains the same string both labeled as
-      #   positive and negative) and contains at least one string.
-      # 
-      # Postconditions:
-      # - The returned DFA is the smallest DFA that correctly labels the learning sample
-      #   given as input.
-      #
-      # Remarks:
-      # - This instance version of BlueFringe.execute is not intended to be used directly and
-      #   is mainly provided for testing purposes. Please use the class variant of this 
-      #   method if possible.
-      #
-      def execute(sample)
-        # create union-find
-        info("Creating PTA and UnionFind structure")
-        ufds = sample2ufds(sample)
-        # refine it
-        ufds = main(ufds)
-        # compute and return quotient automaton
-        ufds2dfa(ufds)
-      end
-      
-      #
-      # Build the smallest DFA compatible with the sample given as input.
-      #
-      # Options (the _options_ hash):
-      # - :verbose can be set to true to trace algorithm execution on standard output.
-      #
-      # Preconditions:
-      # - The sample is consistent (does not contains the same string both labeled as
-      #   positive and negative) and contains at least one string.
-      # 
-      # Postconditions:
-      # - The returned DFA is the smallest DFA that correctly labels the learning sample
-      #   given as input.
-      #
-      def self.execute(sample, options={})
-        BlueFringe.new(options).execute(sample)
-      end
-      
-    end # class BlueFringe
-    
-  end # module Induction
-end # module Stamina

data/lib/stamina/induction/commons.rb

@@ -1,156 +0,0 @@
-module Stamina
-  module Induction
-    
-    #
-    # Defines common utilities used by rpni and blue_fringe. About acronyms: 
-    # - _pta_ stands for Prefix Tree Acceptor
-    # - _ufds_ stands for Union-Find Data Structure
-    #
-    # Methods pta2ufds and sample2ufds are simply conversion methods used when the induction 
-    # algorithm starts (executed on a sample, it first built a pta then convert it to a union 
-    # find). Method ufds2dfa is used when the algorithm ends, to convert refined union find to 
-    # a dfa.
-    #
-    # The merge_user_data method is probably the most important as it actually computes 
-    # the merging of two states and build information about merging for determinization.
-    #
-    module Commons
-      
-      DEFAULT_OPTIONS = {
-        :verbose    => false,
-        :verbose_io => $stderr
-      }
-
-      # Additional options of the algorithm
-      attr_reader :options
-      
-      # Is the verbose mode on ?
-      def verbose?
-        @verbose ||= !!options[:verbose]
-      end
-
-      def verbose_io
-        @verbose_io ||= options[:verbose_io] || $stderr
-      end
-      
-      # Display an information message (when verbose)
-      def info(msg)
-        if verbose?
-          verbose_io << msg << "\n"
-          verbose_io.flush
-        end
-      end
-
-      #
-      # Factors and returns a UnionFind data structure from a PTA, keeping natural order 
-      # of its states for union-find elements. The resulting UnionFind contains a Hash as 
-      # mergeable user data, presenting the following keys:
-      # - :initial, :accepting and :error flags of each state
-      # - :master indicating the index of the state in the PTA
-      # - :delta a delta function through a Hash {symbol => state_index}
-      #
-      # In this version, other user data attached to PTA states is lost during the 
-      # conversion.
-      #
-      def pta2ufds(pta)
-        Stamina::Induction::UnionFind.new(pta.state_count) do |i|
-          state = pta.ith_state(i)
-          data = {:initial => state.initial?,
-                  :accepting => state.accepting?,
-                  :error => state.error?,
-                  :master => i,
-                  :delta => {}}
-          state.out_edges.each {|edge| data[:delta][edge.symbol] = edge.target.index}
-          data
-        end
-      end
-      
-      #
-      # 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 sample2pta(sample)
-        sample.to_pta
-      end
-
-      #
-      # Converts a Sample instance to a 'ready to refine' union find data structure.
-      # This method is simply a shortcut for <code>pta2ufds(sample2pta(sample))</code>.
-      #
-      def sample2ufds(sample)
-        pta2ufds(sample2pta(sample))
-      end
-
-      # 
-      # Computes the quotient automaton from a refined UnionFind data structure.
-      #
-      # In this version, only accepting and initial flags are taken into account
-      # when creating quotient automaton states. Other user data is lost during 
-      # the conversion.
-      #
-      def ufds2dfa(ufds)
-        Automaton.new(false) do |fa|
-          mergeable_datas = ufds.mergeable_datas
-          mergeable_datas.each do |data|
-            state_data = data.reject {|key,value| [:master, :count, :delta].include?(key)}
-            state_data[:name] = data[:master].to_s
-            state_data[:error] = false
-            fa.add_state(state_data)
-          end
-          mergeable_datas.each do |data|
-            source = fa.get_state(data[:master].to_s)
-            data[:delta].each_pair do |symbol, target|
-              target = fa.get_state(ufds.find(target).to_s)
-              fa.connect(source, target, symbol)
-            end
-          end
-        end
-      end
-      
-      #
-      # Merges two user data hashes _d1_ and _d2_ according to rules defined
-      # below. Also fills a _determinization_ array with pairs of state indices
-      # that are reached from d1 and d2 through the same symbol and should be 
-      # merged for determinization. This method does NOT ensure that those pairs
-      # correspond to distinguish states according to the union find. In other
-      # words state indices in these pairs do not necessarily corespond to master
-      # states (see UnionFind for this term).
-      #
-      # Returns the resulting data if the merge is successful (does not lead to
-      # merging an error state with an accepting one), nil otherwise.
-      #
-      # The merging procedure for the different hash keys is as follows:
-      # - result[:initial]   =  d1[:initial]   or d2[:initial]
-      # - result[:accepting] =  d1[:accepting] or d2[:accepting]
-      # - result[:error]     =  d1[:error]     or d2[:error]
-      # - result[:master]    =  min(d1[:master], d2[:master])
-      # - result[:delta]     =  merging of delta hashes, keeping smaller target index 
-      #   on key collisions.
-      #
-      def merge_user_data(d1, d2, determinization)
-        # we compute flags first
-        new_data = {:initial => d1[:initial] || d2[:initial], 
-                    :accepting => d1[:accepting] || d2[:accepting],
-                    :error => d1[:error] || d2[:error],
-                    :master => d1[:master] < d2[:master] ? d1[:master] : d2[:master]}
-                
-        # merge failure if accepting and error states are merged
-        return nil if new_data[:accepting] and new_data[:error]
-                
-        # we recompute the delta function of the resulting state
-        # keeping merging for determinization as pairs in _determinization_
-        new_data[:delta] = d1[:delta].merge(d2[:delta]) do |symbol, t1, t2|
-          determinization << [t1, t2]
-          t1 < t2 ? t1 : t2
-        end
-        
-        # returns merged data
-        new_data
-      end
-      
-    end # module Commons
-    
-  end # module Induction
-end # module Stamina