statistical 0.1.0

data/lib/statistical/distribution/two_point.rb

@@ -0,0 +1,144 @@
+require 'statistical/helpers'
+
+module Statistical
+  module Distribution
+    # Two-Point distribution implementation that uses generic labels for states
+    # that it's random variables can take. The assumptions made would be that
+    # the states are comparable and failure < success in whatever scheme of
+    # comparison that the state objects implement. This defaults to behaving as
+    # the bernoulli distribution
+    #
+    # @note The states used to represent success & failure must be Numeric.
+    #   Using it on generic state lables can cause strange outcomes!
+    #
+    # @note state_failure < state_sucesss, for the sake of sanity.
+    #
+    # @author Vaibhav Yenamandra
+    # @attr_reader [Float] p probability of the success state
+    # @attr_reader [Float] q probability of the failure state
+    # @attr_reader [Hash] states Hash with keys :failure, :success to hold
+    #   their respective state objects(defaults to 0, 1 respectively)
+    class TwoPoint
+      # This is probably the best but the least descriptive variable name
+      attr_reader :p, :q, :states, :support
+
+      # Returns a new instance of the TwoPoint distribution
+      #
+      # @note The states used to represent success & failure must be Numeric.
+      #   Using it on generic state lables can cause strange outcomes!
+      #
+      # @note state_failure < state_sucesss, required to have a sane CDF.
+      #
+      # @param [Float] prob_success The probability of success
+      # @param [Numeric] state_success An object to describe the 1-state of
+      #   success
+      # @param [Numeric] state_failure An object to describe the 0-state of
+      #   failure
+      def initialize(prob_success = 0.5, state_failure = 0, state_success = 1)
+        if state_failure == state_success
+          raise ArgumentError,
+                'Success & failure must be two distinct states'
+        end
+
+        if state_failure > state_success
+          raise ArgumentError,
+                'Failure state must be smaller that the success state!'
+        end
+
+        unless (state_failure + state_success).is_a?(Numeric)
+          raise ArgumentError,
+                "States must be Numeric! Found #{state_failure.class} and #{state_success.class}"
+        end
+
+        if prob_success > 1 || prob_success < 0
+          raise ArgumentError,
+                "Probabilty of success must be within [0, 1]. Found #{prob_success}"
+        end
+
+        @p = prob_success
+        @q = 1 - prob_success
+        @states = {
+          failure: state_failure,
+          success: state_success
+        }
+        @support = @states.values.sort
+        self
+      end
+
+      # Returns value of probability density function at a given state of the
+      # random variate X. Essentially: "what's P(X=x)?"
+      #
+      # @param x [Numeric] The state the the random variable takes. Can be 0, 1
+      # @return [Float] * p if state (x) is 1.
+      # @raise [ArgumentError] if x is not of the states this instance was
+      #   initialized with
+      def pdf(x)
+        return @p if @states[:success] == x
+        return @q if @states[:failure] == x
+        return 0
+      end
+
+      # Returns value of cumulative density function at a point. Calculated
+      #   using some technique that you might want to name
+      #
+      # @param x [Numeric] The state the the random variable takes. Can be 0, 1
+      # @return [Float] The cumulative probability over all of the random
+      #   variates states.
+      def cdf(x)
+        return 0 if x < @states[:failure]
+        return @q if x.between?(@states[:failure], @states[:success])
+        return 1 if x >= @states[:success]
+      end
+
+      # Returns value of inverse CDF for a given probability
+      #
+      # @see #p_value
+      #
+      # @param [Numeric] p a value within [0, 1]
+      # @return Inverse CDF for valid p
+      # @raise [RangeError] if p > 1 or p < 0
+      def quantile(p)
+        raise RangeError, "`p` must be in [0, 1], found: #{p}" if p < 0 || p > 1
+        return @states[:failure] if p <= @q
+        return @states[:success] if p > @q
+      end
+
+      # Returns the expected mean value for the calling instance.
+      #
+      # @return Mean of the distribution
+      def mean
+        return @p * @states[:success] + @q * @states[:failure]
+      end
+
+      # Returns the expected value of variance for the calling instance.
+      #
+      # @return Variance of the distribution
+      def variance
+        return @p * (@states[:success]**2) + @q * (@states[:failure]**2) -
+               (mean**2)
+      end
+
+      # Compares two distribution instances and returns a boolean outcome
+      #   Available publicly as #==
+      #
+      # @note This also compares the states over which the distribution exists
+      #   in addition to he other parameters
+      #
+      # @private
+      #
+      # @param other A distribution object (preferred)
+      # @return [Boolean] true if-and-only-if two instances are of the same
+      #   class and have the same parameters.
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               @p == other.p &&
+               @states == other.states
+      end
+
+      alias :== :eql?
+      alias :p_value :quantile
+
+      private :eql?
+    end
+  end
+end

data/lib/statistical/distribution/uniform.rb

@@ -0,0 +1,98 @@
+require 'statistical/helpers'
+
+module Statistical
+  module Distribution
+    # An abstraction of the common statistical properties of the uniform
+    # distribution. Provides a PDF, CDF, Inverse-CDF, mean, variance
+    #
+    # @note If initialized with lower and upper parameters in reverse order, it
+    #   swaps them. Eg. initializing with lower = 10 and upper = 2 is the same
+    #   as lower = 2 and upper = 10, due to the swap during call to new(,)
+    #
+    # @author Vaibhav Yenamandra
+    #
+    # @attr_reader [Numeric] lower The lower bound of the uniform distribution.
+    #   Defaults to 0.0.
+    # @attr_reader [Numeric] upper The upper bound of the uniform distrbution.
+    #   Defaults to 1.0.
+    class Uniform
+      attr_reader :lower, :upper, :support
+
+      # Returns a new `Statistical::Distribution::Uniform` instance
+      #
+      # @note if given lower > upper, it swaps them internally
+      #
+      # @param [Numeric] start lower bound of the distribution.
+      # @param [Numeric] finish upper bound of the distribution.
+      # @return `Statistical::Distribution::Uniform` instance
+      def initialize(start = 0.0, finish = 1.0)
+        @lower = [start, finish].min
+        @upper = [start, finish].max
+        @support = Domain[@lower, @upper, :closed]
+      end
+
+      # Returns value of probability density function at a point
+      #
+      # @param [Numeric] x A real valued point
+      # @return [Float] 1 if x is within [lower, upper], 0 otherwise
+      def pdf(x)
+        return [1.0 / (@upper - @lower),  0.0, 0.0][@support <=> x]
+      end
+
+      # Returns value of cumulative density function at a point
+      #
+      # @param [Numeric] x A real valued point
+      # @return [Float] 1 if x is within [lower, upper], 0 otherwise
+      def cdf(x)
+        return [(x - @lower).fdiv(@upper - @lower), 1.0, 0.0][@support <=> x]
+      end
+
+      # Returns value of inverse CDF for a given probability
+      #
+      # @see #p_value
+      #
+      # @param [Numeric] p a value within [0, 1]
+      # @return [Numeric] Inverse CDF for valid p
+      # @raise [RangeError] if p > 1 or p < 0
+      def quantile(p)
+        raise RangeError, "`p` must be in [0, 1], found: #{p}" if p < 0 || p > 1
+        return @lower + p * (@upper - @lower)
+      end
+
+      # Returns the expected value of mean value for the calling instance.
+      #
+      # @author Vaibhav Yenamandra
+      #
+      # @return [Float] Mean of the distribution
+      def mean
+        return 0.5 * (@upper + @lower)
+      end
+
+      # Returns the expected value of variance for the calling instance.
+      #
+      # @return [Float] Variance of the distribution
+      def variance
+        return ((@upper - @lower)**2) / 12.0
+      end
+
+      # Compares two distribution instances and returns a boolean outcome
+      #   Available publicly as #==
+      #
+      # @private
+      #
+      # @param other A distribution object (preferred)
+      # @return [Boolean] true if-and-only-if two instances are of the same
+      #   class and have the same parameters.
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               @lower == other.lower &&
+               @upper == other.upper
+      end
+
+      alias :== :eql?
+      alias :p_value :quantile
+
+      private :eql?
+    end
+  end
+end

data/lib/statistical/distribution/uniform_discrete.rb

@@ -0,0 +1,133 @@
+module Statistical
+  # Module to collect all abstractions of distributions
+  module Distribution
+    # This class abstracts the discrete uniform distribution over a given set
+    #   of elements
+    #
+    # @author Vaibhav Yenamandra
+    # @attr_reader [Array, Numeric] support The support set of valid values a
+    # random variate from the distribution can take. Must have at least 1 value
+    class UniformDiscrete
+      attr_reader :count, :support, :lower, :upper
+      # Returns a model for the discrete uniform distribution on all elements
+      # present in the given set of elemets `elems`
+      #
+      # @note The constructor sorts the array of elements given to it, as this
+      #   is a key assumption of the discrete uniform distribution. This set
+      #   must also be homogenous
+      #
+      # @param [Array] elems The elements over which the distribution exists
+      #   in [lower, upper]
+      # @raise [RangeError] if elems isn't one of Array, Range, Fixnum or
+      #   Bignum
+      def initialize(elems)
+        case elems
+        when Fixnum, Bignum
+          @support = [elems]
+        when Array
+          @support = elems.sort
+        when Range
+          @support = elems.to_a
+        else
+          raise ArgumentError,
+                "Expected Fixnum, Bignum, Array or Range, found #{elems.class}"
+        end
+        @count = @support.length
+        @lower = @support[0]
+        @upper = @support[-1]
+        self
+      end
+
+      # Returns value of probability density function at a point on the real
+      #   line
+      #
+      # @param [Fixnum, Bignum] k Point at which pdf is desired
+      # @return [Float] 0 if k doesn't belong to the elements over which the
+      #   current instance is distributed. 1/n otherwise where n is number
+      #   of elements
+      def pdf(k)
+        return 1.0 / @count if @support.include?(k)
+        return 0.0
+      end
+
+      # Returns value of cumulative density function at a point on the real line
+      # Uses a binary search on the support array internally.
+      #
+      # @note This suffers from some floating point comparison issues. Errors
+      #   start appearing when dealing with precision > 1E-18
+      #
+      # @param [Fixnum, Bignum] k Point at which cdf value is desired
+      # @return [Float]  0 if k is on the left of the support,
+      #   1 if k on the right support and the
+      #   evaluates CDF for any other legal value
+      def cdf(k)
+        return 0.0 if k < @lower
+        return 1.0 if k >= @upper
+
+        # Ruby has a Array#bsearch_index already but it supports find-min mode
+        # What we need is a find-max mode. This can be achieved by reversing
+        # and then searching, but reverse is O(N) so it defeats the purpose
+        low = 0
+        high = @count - 1
+        while low < high
+          mid = (low + high) / 2
+          if @support[mid] <= k
+            low = mid + 1
+          else
+            high = mid
+          end
+        end
+        # This should be true for all i > low
+        return low.fdiv(@count)
+      end
+
+      # Returns value of inverse CDF for a given probability.
+      #
+      # @see #p_value
+      #
+      # @param [Numeric] p a value within [0, 1]
+      # @return [Numeric]  Returns inverse CDF for valid p
+      # @raise [RangeError] if p > 1 or p < 0
+      def quantile(p)
+        raise RangeError, "`p` must be in [0, 1], found: #{p}" if p < 0 || p > 1
+        return @lower if p.zero?
+        return @upper if (p - 1).zero?
+        return @support[(p * count).ceil - 1]
+      end
+
+      # Returns the mean value for the calling instance. Calculated mean, and
+      #   not inferred from simulations
+      #
+      # @return [Float] Mean of the distribution
+      def mean
+        return @support.mean
+      end
+
+      # Returns the expected value of population variance for the calling
+      #   instance.
+      #
+      # @return [Float]  Variance of the distribution
+      def variance
+        return @support.variance
+      end
+
+      # Compares two distribution instances and returns a boolean
+      #   Available publicly as #==
+      #
+      # @private
+      #
+      # @param other A distribution object (preferred)
+      # @return [Boolean] true if-and-only-if two instances are of the same
+      #   class and have the same parameters.
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               @support == other.support
+      end
+
+      alias :== :eql?
+      alias :p_value :quantile
+
+      private :eql?
+    end
+  end
+end

data/lib/statistical/distribution/weibull.rb

@@ -0,0 +1,99 @@
+require 'statistical/helpers'
+
+module Statistical
+  module Distribution
+    # Say something useful about this class.
+    #
+    # @note Any caveats you want to talk about go here...
+    #
+    # @author Vaibhav Yenamandra
+    # @attr_reader [Float] scale The distribution's scale parameter
+    # @attr_reader [Float] shape The distribution's shape parameter
+    class Weibull
+      attr_reader :scale, :shape, :support
+
+      # Returns a new `Statistical::Distribution::Weibull` instance
+      #
+      # @param [Numeric] scale The distribution's scale parameter
+      # @param [Numeric] shape The distribution's shape parameter
+      # @return `Statistical::Distribution::Weibull` instance
+      def initialize(scale = 1, shape = 1)
+        @scale = scale.to_f
+        @shape = shape.to_f
+        @support = Domain[0.0, Float::INFINITY, :right_open]
+        self
+      end
+
+      # Returns value of probability density function at a point. Calculated
+      #   using some technique that you might want to name
+      #
+      # @param [Numeric] x A real valued point
+      # @return
+      def pdf(x)
+        return [(@shape / @scale) * ((x / @scale)**(@shape - 1)) *
+                Math.exp(-((x / @scale)**@shape)),
+                0.0,
+                0.0
+        ][@support <=> x]
+      end
+
+      # Returns value of cumulative density function at a point. Calculated
+      #   using some technique that you might want to name
+      #
+      # @param [Numeric] x A real valued point
+      # @return
+      def cdf(x)
+        return [1 - Math.exp(-((x / @scale)**@shape)),
+                1.0,
+                0.0
+        ][@support <=> x]
+      end
+
+      # Returns value of inverse CDF for a given probability
+      #
+      # @see #p_value
+      #
+      # @param [Numeric] p a value within [0, 1]
+      # @return Inverse CDF for valid p
+      # @raise [RangeError] if p > 1 or p < 0
+      def quantile(p)
+        raise RangeError, "`p` must be in [0, 1], found: #{p}" if p < 0 || p > 1
+        return @scale * ((-Math.log(1 - p))**(1 / @shape))
+      end
+
+      # Returns the expected value of mean for the calling instance.
+      #
+      # @return Mean of the distribution
+      def mean
+        return @scale * Math.gamma(1 + 1 / @shape)
+      end
+
+      # Returns the expected value of variance for the calling instance.
+      #
+      # @return Variance of the distribution
+      def variance
+        m = mean
+        (@scale * @scale) * Math.gamma(1 + 2 / @shape) - (m * m)
+      end
+
+      # Compares two distribution instances and returns a boolean outcome
+      #   Available publicly as #==
+      #
+      # @private
+      #
+      # @param other A distribution object (preferred)
+      # @return [Boolean] true if-and-only-if two instances are of the same
+      #   class and have the same parameters.
+      def eql?(other)
+        return other.is_a?(self.class) &&
+               other.shape == @shape &&
+               other.scale == @scale
+      end
+
+      alias :== :eql?
+      alias :p_value :quantile
+
+      private :eql?
+    end
+  end
+end