Class: Hitimes::Stats

Inherits:
Object
  • Object
show all
Defined in:
lib/hitimes/stats.rb,
ext/hitimes/hitimes_stats.c

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

Direct Known Subclasses

MutexedStats

Constant Summary

STATS =

A list of the available stats

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

Instance Method Summary collapse

Instance Method Details

#countObject

*

call-seq:
   stat.count -> Integer

Return the number of values that have passed through the Stats object.


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_count( VALUE self )
{
    hitimes_stats_t *stats;

    Data_Get_Struct( self, hitimes_stats_t, stats );

    return LONG2NUM( stats->count );
}

#maxObject

*

call-seq:
   stat.max -> Float

Return the maximum value that has passed through the Stats object


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_max( VALUE self )
{
    hitimes_stats_t *stats;

    Data_Get_Struct( self, hitimes_stats_t, stats );

    return rb_float_new( stats->max );
}

#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;


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_mean( VALUE self )
{
hitimes_stats_t *stats;
long double      mean = 0.0;

Data_Get_Struct( self, hitimes_stats_t, stats );

if ( stats->count > 0 ) {
  mean = stats->sum / stats->count ;
}

#minObject

*

call-seq:
   stat.min  -> Float

Return the minimum value that has passed through the Stats object


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_min( VALUE self )
{
    hitimes_stats_t *stats;

    Data_Get_Struct( self, hitimes_stats_t, stats );

    return rb_float_new( stats->min );
}

#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.


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_rate( VALUE self )
{
hitimes_stats_t *stats;
long double      rate = 0.0;

Data_Get_Struct( self, hitimes_stats_t, stats );

if ( stats->sum > 0.0 ) {
  rate = stats->count / stats->sum;
}

#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;


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_stddev ( VALUE self )
{
hitimes_stats_t *stats;
long double     stddev = 0.0;

Data_Get_Struct( self, hitimes_stats_t, stats );
if ( stats->count > 1 ) {
  stddev = sqrt( ( stats->sumsq - ( stats->sum * stats->sum  / stats->count ) ) / ( stats->count - 1 ) );
}

#sumObject

*

call-seq:
   stat.sum -> Float

Return the sum of all the values that have passed through the Stats object.


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_sum( VALUE self )
{
    hitimes_stats_t *stats;

    Data_Get_Struct( self, hitimes_stats_t, stats );

    return rb_float_new( stats->sum );
}

#sumsqObject

*

call-seq:
  stat.sumsq -> Float

Return the sum of the squars of all the values that passed through the Stats
object.


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_sumsq( VALUE self )
{
    hitimes_stats_t *stats;

    Data_Get_Struct( self, hitimes_stats_t, stats );

    return rb_float_new( stats->sumsq );
}

#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.



24
25
26
27
28
29
30
31
32
# File 'lib/hitimes/stats.rb', line 24

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.



43
44
45
46
47
48
49
50
51
52
53
54
55
# File 'lib/hitimes/stats.rb', line 43

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

#updateObject

*

call-seq:
   stat.update( val ) -> val

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


# File 'ext/hitimes/hitimes_stats.c'

VALUE hitimes_stats_update( VALUE self, VALUE v )
{
long double      new_v;
hitimes_stats_t *stats;

Data_Get_Struct( self, hitimes_stats_t, stats );
new_v = NUM2DBL( v );

if ( 0 == stats->count ) {
  stats->min = new_v;
  stats->max = new_v;
}