statistical 0.1.0

data/lib/statistical/helpers.rb

@@ -0,0 +1,132 @@
+module Statistical
+  # This class models a mathematical domain by basing it on Ruby's Range
+  # Does not allow for enumeration of the domain unless. The primary addition
+  # here is the addtion of an exclusion list which allows us to exclude specific
+  # points and ranges from within the domain.
+  #
+  # @note If the exclusion list contains points outside of the base range these
+  #   points are not validated. The user is expect to supply valid input, since
+  #   this is a helper class
+  # @note All instances of this class are returned frozen
+  #
+  # @author Vaibhav Yenamandra
+  #
+  # @attr_reader :exclusions The exclusion list of points and ranges to not
+  #   be included in the domain. The list must be homogenous
+  class Domain < Range
+    include Comparable
+
+    attr_reader :start, :finish, :exclusions, :domain_type
+
+    TYPES = [
+      :left_open,
+      :right_open,
+      :full_open,
+      :closed
+    ].freeze
+
+    # Creates a new domain instance which can be one of the following types
+    #   :left_open, :right_open, :full_open, :closed
+    #   An exclusion list is also maintained to capture undesired points, ranges
+    #
+    # @param [Fixnum, Bignum] start number where the range starts
+    # @param [Fixnum, Bignum] finish number where the range ends
+    # @param [Symbol] domain_type kind of domain to represent
+    # @param exclusions homogenous list of exclusions
+    def initialize(start, finish, domain_type, *exclusions)
+      exclusions ||= []
+      exclude_end = false
+
+      case domain_type
+      when :left_open
+        @exclusions = [start, exclusions].flatten
+        exclude_end = false
+      when :right_open
+        @exclusions = [exclusions, finish].flatten
+        exclude_end = true
+      when :full_open
+        @exclusions = [start, exclusions, finish].flatten
+        exclude_end = true
+      when :closed
+        @exclusions = [exclusions].flatten
+        exclude_end = false
+      else
+        raise ArgumentError,
+              "Invalid domain type, must be one of #{DOMAIN_TYPES}"
+      end
+      @start = start
+      @finish = finish
+      @domain_type = domain_type
+
+      super(@start, @finish, exclude_end)
+    end
+
+    # Returns a frozen new instance, overrides Range::new
+    # @return [Domain] a new instance of the Domain class
+    def new(*args)
+      super(*args).freeze
+    end
+
+    # Returns a frozen new instance
+    # @see #new
+    # @return [Domain] a new instance of the Domain class
+    def self.[](*args)
+      new(*args)
+    end
+
+    # Find if a point value is part of the instance's exclusion list
+    #
+    # @param val The numeric value to test for exclusion
+    # @return [Boolean] if the value is excluded from the current domain
+    def exclude?(val)
+      has_val = false
+      @exclusions.each do |e|
+        case e
+        when Fixnum, Bignum, Float
+          has_val = has_val || (e == val)
+        when Range
+          has_val ||= e.include?(val)
+        end
+      end
+      return has_val
+    end
+
+    # Find if a point value is part of the domain
+    #
+    # @param val The value to test for inclusion
+    # @return [Boolean] if the value is included in the current domain
+    def include?(val)
+      super(val) && !exclude?(val)
+    end
+
+    # Serialize the instance
+    #
+    # @see #to_s
+    # @return [String] string representation of the Domain object
+    def inspect
+      return "[#{super}] - #{@exclusions}" unless @exclusions.empty?
+      return super
+    end
+
+    # Compares Domain objects with Real numeric types (Fixnum, Bignum, Float)
+    #
+    # @param other the point to compare
+    # @return -1 if the value lies to the left of the domain
+    #   1 if the value lies to the right of domain
+    #   0 if the value is included in the range
+    #   nil if the two are not deemed comparable
+    def <=>(other)
+      case other
+      when Fixnum, Bignum, Float
+        return -1 if other <= @start && !include?(other)
+        return  1 if other >= @finish && !include?(other)
+        return  0 if include?(other)
+      else
+        # Not comparable
+        return nil
+      end
+    end
+
+    alias :to_s :inspect
+  end
+end

data/lib/statistical/rng.rb

@@ -0,0 +1,37 @@
+require 'statistical/rng/uniform'
+require 'statistical/rng/uniform_discrete'
+require 'statistical/rng/two_point'
+require 'statistical/rng/bernoulli'
+require 'statistical/rng/exponential'
+require 'statistical/rng/laplace'
+require 'statistical/rng/weibull'
+
+module Statistical
+  # Factory module to create instances of the various classes
+  # nested under itself
+  module Rng
+    # @private
+    # No need to document this
+    # Dynamically add constants when called
+    def self.const_missing(cname)
+      const_set(cname, make_classmap) if cname == :RNG_TYPES
+    end
+
+    # Creates a new instance of the give type if the type was found.
+    #
+    # @raise ArgumentError If the give type parameter was not found
+    def self.create(type = :uniform, *args, &block)
+      raise ArgumentError unless RNG_TYPES.include?(type)
+      RNG_TYPES[type].new(*args, &block)
+    end
+
+    def self.make_classmap
+      rng_klasses = constants.select { |k| const_get(k).is_a?(Class)}
+      keylist = rng_klasses.map { |k| k.to_s.snakecase.to_sym}
+      klasses = rng_klasses.map { |k| const_get(k)}
+      return Hash[keylist.zip(klasses)].freeze
+    end
+
+    private_class_method :make_classmap
+  end
+end

data/lib/statistical/rng/bernoulli.rb

@@ -0,0 +1,29 @@
+require 'statistical/distribution/bernoulli'
+require 'statistical/rng/two_point'
+
+module Statistical
+  module Rng
+    # This class models a bernoulli trial using the TwoPoint distribution as
+    # as base distribution / trial system.
+    class Bernoulli < TwoPoint
+      # Companion RNG class for the Bernoulli distribution. Requires a
+      # distrbution object of the same type. Defaults to standard bernoulli
+      # if arguments are unspecified
+      #
+      # @author Vaibhav Yenamandra
+      #
+      # @attr_reader [Float] p Probability of success state
+      # @attr_reader [Float] q Probability of failure state
+      # @attr_reader [Hash] states Possible states that the RNG can take up
+      # @attr_reader [Random] generator The PRNG being used for randomness
+      def initialize(dobj = nil, seed = Random.new_seed)
+        unless dobj.nil? || dobj.is_a?(Statistical::Distribution::Bernoulli)
+          raise TypeError,
+                "Expected Distribution object or nil, found #{dobj.class}"
+        end
+        dobj = Statistical::Distribution::Bernoulli.new if dobj.nil?
+        super(dobj, seed)
+      end
+    end
+  end
+end

data/lib/statistical/rng/exponential.rb

@@ -0,0 +1,56 @@
+require 'statistical/distribution/exponential'
+require 'statistical/distribution/uniform'
+require 'statistical/rng/uniform'
+
+module Statistical
+  module Rng
+    # Companion RNG class for the exponential distribution. Requires a
+    #   distrbution object of the corresponding distribution
+    #
+    # @author Vaibhav Yenamandra
+    #
+    # @attr_reader [Numeric] rate Rate parameter of the exponential distribution
+    # @attr_reader [Numeric] upper The upper bound of the uniform distribution
+    class Exponential
+      attr_reader :rate, :generator
+
+      def initialize(dobj = nil, seed = Random.new_seed)
+        unless dobj.nil? || dobj.is_a?(Statistical::Distribution::Exponential)
+          raise TypeError,
+                "Expected Distribution object or nil, found #{dobj.class}"
+        end
+        dobj = Statistical::Distribution::Exponential.new if dobj.nil?
+        @generator = Random.new(seed)
+        @rate = dobj.rate
+        @sdist = dobj
+      end
+
+      # Return the next random number from the sequence
+      #
+      # @return [Numeric] next random number in the sequence
+      def rand
+        return @sdist.quantile(@generator.rand)
+      end
+
+      # Compare against another rng to see if they are the same
+      #
+      # @return true if and only if, source distributions are the same and the
+      #   prng has the same initial state
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               @generator == other.generator &&
+               @rate = other.rate
+      end
+
+      # Return the type of the source distribution
+      #
+      # @return source distribution's type
+      def type
+        @sdist.class
+      end
+
+      alias :== :eql?
+      private :eql?
+    end
+  end
+end

data/lib/statistical/rng/laplace.rb

@@ -0,0 +1,57 @@
+require 'statistical/distribution/laplace'
+
+module Statistical
+  module Rng
+    # Companion RNG class for the continuous uniform distribution. Requires a
+    #   distrbution object of the corresponding distribution
+    #
+    # @author Vaibhav Yenamandra
+    #
+    # @attr_reader [Numeric] scale Scale parameter of the Laplace distribution.
+    # @attr_reader [Numeric] location Location parameter to determine where the
+    #   distribution is centered / where the mean lies at
+    class Laplace
+      attr_reader :generator, :scale, :location
+
+      def initialize(dobj = nil, seed = Random.new_seed)
+        unless dobj.nil? || dobj.is_a?(Statistical::Distribution::Laplace)
+          raise TypeError,
+                "Expected Distribution object or nil, found #{dobj.class}"
+        end
+        dobj = Statistical::Distribution::Laplace.new if dobj.nil?
+        @generator = Random.new(seed)
+        @scale = dobj.scale
+        @location = dobj.location
+        @sdist = dobj
+      end
+
+      # Return the next random number from the sequence
+      #
+      # @return next random number in the sequence
+      def rand
+        return @sdist.quantile(@generator.rand)
+      end
+
+      # Compare against another rng to see if they are the same
+      #
+      # @return true if and only if, source distributions are the same and the
+      #   prng has the same initial state
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               other.generator == @generator &&
+               other.location == @location &&
+               other.scale == @scale
+      end
+
+      # Return the type of the source distribution
+      #
+      # @return source distribution's type
+      def type
+        @sdist.class
+      end
+
+      alias :== :eql?
+      private :eql?
+    end
+  end
+end

data/lib/statistical/rng/two_point.rb

@@ -0,0 +1,70 @@
+require 'statistical/distribution/two_point'
+require 'statistical/distribution/uniform'
+
+module Statistical
+  module Rng
+    # Random number generator to model the two point distribution used for
+    # working with problem where the state space has only two points with
+    # distinct probabilities
+    class TwoPoint
+      attr_reader :generator, :p, :q, :states
+
+      # Companion RNG class for the two-point distribution. Requires a
+      # distrbution object of the corresponding type. Defaults to the standard
+      # bernoulli if no arguments are given
+      #
+      # @author Vaibhav Yenamandra
+      #
+      # @attr_reader [Float] p Probability of success state
+      # @attr_reader [Float] q Probability of failure state
+      # @attr_reader [Hash] states Possible states that the RNG can take up
+      # @attr_reader [Object] generator The PRNG being used for randomness
+      def initialize(dobj = nil, seed = Random.new_seed)
+        unless dobj.nil? || dobj.is_a?(Statistical::Distribution::TwoPoint)
+          raise TypeError,
+                "Expected Distribution object or nil, found #{dobj.class}"
+        end
+        dobj = Statistical::Distribution::TwoPoint.new if dobj.nil?
+        @generator = Random.new(seed)
+        @sdist = dobj
+        @p = dobj.p
+        @q = dobj.q
+        @states = dobj.states
+      end
+
+      # Return the next random number from the sequence following the given
+      # distribution
+      #
+      # @return next random number in the sequence
+      def rand
+        return @sdist.quantile(@generator.rand)
+      end
+
+      # Compare against another rng to see if they are the same
+      #
+      # @return [Boolean] true if and only if, source distributions are the same
+      #   and the prng has the same initial state
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               @p = other.p &&
+                    @states == other.states &&
+                    @generator == other.generator
+      end
+
+      # Return the type of the source distribution
+      #
+      # @return source distribution's type
+      def type
+        @sdist.class
+      end
+
+      # The support set over which the distribution exists
+      def support
+        @sdist.support
+      end
+
+      alias :== :eql?
+      private :eql?
+    end
+  end
+end

data/lib/statistical/rng/uniform.rb

@@ -0,0 +1,62 @@
+require 'statistical/distribution/uniform'
+
+module Statistical
+  module Rng
+    # Companion RNG class for the continuous uniform distribution. Requires a
+    #   distrbution object of the corresponding distribution
+    #
+    # @author Vaibhav Yenamandra
+    #
+    # @attr_reader [Numeric] lower The lower bound of the uniform distribution.
+    # @attr_reader [Numeric] upper The upper bound of the uniform distribution.
+    class Uniform
+      attr_reader :lower, :upper, :generator
+
+      def initialize(dobj = nil, seed = Random.new_seed)
+        unless dobj.nil? || dobj.is_a?(Statistical::Distribution::Uniform)
+          raise TypeError,
+                "Expected Distribution object or nil, found #{dobj.class}"
+        end
+        dobj = Statistical::Distribution::Uniform.new if dobj.nil?
+        @generator = Random.new(seed)
+        @lower = dobj.lower
+        @upper = dobj.upper
+        @sdist = dobj
+      end
+
+      # Return the next random number from the sequence
+      #
+      # @author Vaibhav Yenamandra
+      #
+      # @return next random number in the sequence
+      def rand
+        @lower + @generator.rand * (@upper - @lower)
+      end
+
+      # Compare against another rng to see if they are the same
+      #
+      # @author Vaibhav Yenamandra
+      #
+      # @return [Boolean] true if and only if, source distributions are the
+      #   same and the prng has the same initial state
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               @lower == other.lower &&
+               @upper == other.upper &&
+               @generator == other.generator
+      end
+
+      # Return the type of the source distribution
+      #
+      # @author Vaibhav Yenamandra
+      #
+      # @return [Statistical::Distribution::Uniform] source distribution's type
+      def type
+        @sdist.class
+      end
+
+      alias :== :eql?
+      private :eql?
+    end
+  end
+end