Class: Hitimes::Stats

Inherits:
Object
  • Object
show all
Defined in:
lib/hitimes/stats.rb

Overview

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

Constant Summary collapse

STATS =

A list of the available stats

%w[ count max mean min rate stddev sum sumsq ]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeStats

Returns a new instance of Stats.


42
43
44
45
46
47
48
49
# File 'lib/hitimes/stats.rb', line 42

def initialize
  @mutex = Mutex.new
  @min = Float::INFINITY
  @max = -Float::INFINITY
  @count = 0
  @sum = 0.0
  @sumsq = 0.0
end

Instance Attribute Details

#countObject (readonly)

Returns the value of attribute count


38
39
40
# File 'lib/hitimes/stats.rb', line 38

def count
  @count
end

#maxObject (readonly)

Returns the value of attribute max


37
38
39
# File 'lib/hitimes/stats.rb', line 37

def max
  @max
end

#minObject (readonly)

Returns the value of attribute min


36
37
38
# File 'lib/hitimes/stats.rb', line 36

def min
  @min
end

#sumObject (readonly)

Returns the value of attribute sum


39
40
41
# File 'lib/hitimes/stats.rb', line 39

def sum
  @sum
end

#sumsqObject (readonly)

Returns the value of attribute sumsq


40
41
42
# File 'lib/hitimes/stats.rb', line 40

def sumsq
  @sumsq
end

Instance Method Details

#meanObject

call-seq:

stat.mean -> Float

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;


74
75
76
77
# File 'lib/hitimes/stats.rb', line 74

def mean
  return 0.0 if @count.zero?
  return @sum / @count
end

#rateObject

call-seq:

stat.rate -> Float

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.


92
93
94
95
# File 'lib/hitimes/stats.rb', line 92

def rate
  return 0.0 if @sum.zero?
  return @count / @sum
end

#stddevObject

call-seq:

stat.stddev -> Float

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;


105
106
107
108
# File 'lib/hitimes/stats.rb', line 105

def stddev
  return 0.0 unless @count > 1
  Math.sqrt((@sumsq - ((@sum * @sum)/@count)) / (@count - 1))
end

#to_hash(*args) ⇒ Object

call-seq:

stat.to_hash   -> Hash
stat.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.


122
123
124
125
126
127
128
129
130
# File 'lib/hitimes/stats.rb', line 122

def to_hash( *args )
  h = {}
  args = [ args ].flatten
  args = STATS if args.empty?
  args.each do |meth|
    h[meth] = self.send( meth )
  end
  return h
end

#to_json(*args) ⇒ Object

call-seq:

stat.to_json  -> String
stat.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.


141
142
143
144
145
146
147
148
149
150
151
152
153
# File 'lib/hitimes/stats.rb', line 141

def to_json( *args )
  h = to_hash( *args )
  a = []
  s = StringIO.new

  s.print "{ "
  h.each_pair do |k,v|
    a << "\"#{k}\": #{v}"
  end
  s.print a.join(", ")
  s.print "}"
  return s.string
end

#update(value) ⇒ Object

call-seq:

stat.update( val ) -> val

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


56
57
58
59
60
61
62
63
64
65
66
67
# File 'lib/hitimes/stats.rb', line 56

def update(value)
  @mutex.synchronize do
    @min = (value < @min) ? value : @min
    @max = (value > @max) ? value : @max

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

  return value
end