class Hitimes::Stats

The Stats class encapulsates capturing and reporting statistics. It is modeled after the RFuzz::Sampler class, but implemented in C. For general use you allocate a new Stats object, and then update it with new values. The Stats object will keep track of the min, max, count, sum and sumsq and when you want you may also retrieve the mean, stddev and rate.

this contrived example shows getting a list of all the files in a directory and running stats on file sizes.

s = Hitimes::Stats.new
dir = ARGV.shift || Dir.pwd
Dir.entries( dir ).each do |entry|
  fs = File.stat( entry )
  if fs.file? then
    s.update( fs.size )
   end
end

%w[ count min max mean sum stddev rate ].each do |m|
  puts "#{m.rjust(6)} : #{s.send( m ) }"
end

Constants

STATS

A list of the available stats

Attributes

count[R]
max[R]
min[R]
sum[R]
sumsq[R]

Public Class Methods

new() click to toggle source
# File lib/hitimes/stats.rb, line 39
def initialize
  @mutex = Mutex.new
  @min = Float::INFINITY
  @max = -Float::INFINITY
  @count = 0
  @sum = 0.0
  @sumsq = 0.0
end

Public Instance Methods

mean → Float click to toggle source

Return the arithmetic mean of the values put into the Stats object. If no values have passed through the stats object then 0.0 is returned;

# File lib/hitimes/stats.rb, line 71
def mean
  return 0.0 if @count.zero?

  @sum / @count
end
rate → Float click to toggle source

Return the count divided by sum.

In many cases when Stats#update( value ) is called, the value is a unit of time, typically seconds or microseconds. rate is a convenience for those times. In this case, where value is a unit if time, then count divided by sum is a useful value, i.e. +something per unit of time+.

In the case where value is a non-time related value, then the value returned by rate is not really useful.

# File lib/hitimes/stats.rb, line 90
def rate
  return 0.0 if @sum.zero?

  @count / @sum
end
stddev → Float click to toggle source

Return the standard deviation of all the values that have passed through the Stats object. The standard deviation has no meaning unless the count is > 1, therefore if the current stat.count is < 1 then 0.0 will be returned;

# File lib/hitimes/stats.rb, line 104
def stddev
  return 0.0 unless @count > 1

  Math.sqrt((@sumsq - ((@sum * @sum) / @count)) / (@count - 1))
end
to_hash → Hash click to toggle source
to_hash( %w[ count max mean ]) → Hash

return a hash of the stats. By default this returns a hash of all stats but passing in an array of items will limit the stats returned to only those in the Array.

If passed in an empty array or nil to to_hash then STATS is assumed to be the list of stats to return in the hash.

# File lib/hitimes/stats.rb, line 122
def to_hash(*args)
  result = {}
  fields = [args].flatten
  fields = STATS if fields.empty?
  fields.each do |meth|
    result[meth] = send(meth)
  end
  result
end
to_json → String click to toggle source
to_json( *args ) → String

return a json string of the stats. By default this returns a json string of all the stats. If an array of items is passed in, those that match the known stats will be all that is included in the json output.

# File lib/hitimes/stats.rb, line 141
def to_json(*args)
  stats = to_hash(*args)
  slugs = []
  out = StringIO.new

  out.print "{ "
  stats.each_pair do |key, val|
    slugs << "\"#{key}\": #{val}"
  end
  out.print slugs.join(", ")
  out.print "}"
  out.string
end
update( val ) → val click to toggle source

Update the running stats with the new value. Return the input value.

# File lib/hitimes/stats.rb, line 53
def update(value)
  @mutex.synchronize do
    @min = (value < @min) ? value : @min
    @max = (value > @max) ? value : @max

    @count += 1
    @sum   += value
    @sumsq += (value * value)
  end

  value
end