stat_c 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f63ee4a4e26bb9031d4eed9ea02cf02b63fb629
-  data.tar.gz: 4cb7709b9c16ddff13113495d0758533b6e96ec3
+  metadata.gz: e0e5819680b725e08009314b625cd71e806fd2bc
+  data.tar.gz: 707e936d379f538b9ac30661c3d7b8aa99a8d0ab
 SHA512:
-  metadata.gz: b2fe2a4aed50969143e634271e133e3459dc51390c45ee983372a818b46e388e6c4c8b34752c24ebcf832c1cc9606c841caeec32a189a6d92ce82ddfd8763f46
-  data.tar.gz: aa2763572a0a0111ac0a6a2c451573aee9432e6c1f2115b7e428be055f33c21f15b7b1c5bef843596003ded7fb201082651e68f94488e4ad6ec1bebcddd9f7bb
+  metadata.gz: 4a2338631efc5343c4181147bf65aa90e0306fb679772c676bbeeada9de57998f24467a012fe2d39cfde2ec1bc6e58ba2b419aa8adf853fd932dbbe7521bbd77
+  data.tar.gz: 70702b3acb197b3b35d6de33d733c00ac86ee11891f6994bb64f8751c0ffa0545f652b6e1e58f50a794848020d3c7358038a4afe7d9d48693cdf59226b3e28b0

data/README.md

@@ -1,8 +1,6 @@
 # StatC
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/stat_c`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Fast, well documented C stats extension for Ruby.
 
 ## Installation
 
@@ -22,7 +20,53 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+```ruby
+require "stat_c"
+
+ary = [-1.4, 0, 1, 2, 3.0]
+
+StatC::Array.mean(ary).round(2)  #=> 0.92
+
+# Stats based on sample variance
+StatC::Array.var(ary).round(2)  #=> 2.93
+StatC::Array.sd(ary).round(2)   #=> 1.71
+StatC::Array.se(ary).round(2)   #=> 0.77
+
+# Stats based on population variance
+StatC::Array.var(ary, pop=true).round(2)  #=> 2.35
+StatC::Array.sd(ary,  pop=true).round(2)  #=> 1.53
+StatC::Array.se(ary,  pop=true).round(2)  #=> 0.68
+```
+
+## Benchmark ##
+
+StatC is faster than pure Ruby (duh, it's a C extension {^_^} ). See `benchmark/benchmark.rb` for more info.
+
+    $ ruby benchmark/benchmark.rb
+
+    Rehearsal ----------------------------------------------
+    Ruby  mean   0.090000   0.000000   0.090000 (  0.085029)
+    StatC mean   0.010000   0.000000   0.010000 (  0.009604)
+    Ruby  var    0.350000   0.010000   0.360000 (  0.357243)
+    StatC var    0.020000   0.000000   0.020000 (  0.020343)
+    Ruby  sd     0.350000   0.000000   0.350000 (  0.355273)
+    StatC sd     0.020000   0.000000   0.020000 (  0.018590)
+    Ruby  se     0.340000   0.000000   0.340000 (  0.353170)
+    StatC se     0.030000   0.000000   0.030000 (  0.025813)
+    ------------------------------------- total: 1.220000sec
+
+                     user     system      total        real
+    Ruby  mean   0.080000   0.000000   0.080000 (  0.079849)
+    StatC mean   0.000000   0.000000   0.000000 (  0.009006)
+
+    Ruby  var    0.320000   0.010000   0.330000 (  0.322538)
+    StatC var    0.020000   0.000000   0.020000 (  0.018962)
+
+    Ruby  sd     0.330000   0.000000   0.330000 (  0.329038)
+    StatC sd     0.020000   0.000000   0.020000 (  0.020783)
+
+    Ruby  se     0.310000   0.000000   0.310000 (  0.319696)
+    StatC se     0.020000   0.000000   0.020000 (  0.019259)
 
 ## Development
 

data/benchmark/benchmark.rb

@@ -1,18 +1,36 @@
 require "stat_c"
 require "benchmark"
 
-def mean ary
+def ary_mean ary
   ary.reduce(:+) / ary.length.to_f
 end
 
+# sample variance
+def ary_var ary
+  mean = ary_mean ary
+  ary.map { |num| (num - mean) ** 2 }.reduce(:+) / (ary.length - 1)
+end
+
+def ary_sd ary
+  Math.sqrt(ary_var ary)
+end
+
+def ary_se ary
+  ary_sd(ary) / Math.sqrt(ary.length)
+end
+
 ary = (1..1_000_000).map(&:itself)
 
 Benchmark.bmbm do |x|
-  x.report("ruby mean") do
-    mean ary
-  end
+  x.report("Ruby  mean") { ary_mean ary }
+  x.report("StatC mean") { StatC::Array.mean ary }
+
+  x.report("Ruby  var") { ary_var ary }
+  x.report("StatC var") { StatC::Array.var ary }
+
+  x.report("Ruby  sd") { ary_sd ary }
+  x.report("StatC sd") { StatC::Array.sd ary }
 
-  x.report("c mean") do
-    StatC::Array.mean ary
-  end
+  x.report("Ruby  se") { ary_se ary }
+  x.report("StatC se") { StatC::Array.se ary }
 end

data/ext/stat_c/stat_c.c

@@ -21,6 +21,10 @@ along with StatC.  If not, see <http://www.gnu.org/licenses/>.
 *********************************************************************/
 
 #include <ruby.h>
+#include <math.h>
+
+/* based on NIL_P in ruby.h */
+#define FALSE_P(v) !((VALUE)(v) != Qfalse)
 
 /* classes and modules */
 VALUE sc_mStatC;
@@ -28,16 +32,42 @@ VALUE sc_mArray;
 VALUE sc_mError;
 VALUE sc_eError;
 
-static VALUE sc_mean(VALUE self, VALUE ary)
+/* @private */
+static size_t assert_array_not_empty(VALUE ary)
 {
-
-  unsigned long i = 0;
-  long double sum = 0;
   size_t len = RARRAY_LEN(ary);
 
   if (len <= 0) {
     rb_raise(sc_eError, "Array cannot be empty");
+  } else {
+    return len;
   }
+}
+
+/* @private */
+static long double sc_ary_entry(VALUE ary, long idx)
+{
+  return NUM2DBL(rb_ary_entry(ary, idx));
+}
+
+/* Calculate the mean of values in the given array.
+
+@param ary [Array<Numeric>] an array of Numerics
+
+@example Get mean of array
+  StatC::Array.mean([-1.4, 0, 1, 2, 3.0]).round(2)  #=> 0.92
+
+@raise [StatC::Error::Error] if array length is zero
+
+@return [Numeric] mean of values in the array
+
+*/
+static VALUE sc_mean(VALUE obj, VALUE ary)
+{
+
+  unsigned long i = 0;
+  long double sum = 0;
+  size_t len = assert_array_not_empty(ary);
 
   for (i = 0; i < len; ++i) {
     sum += NUM2DBL(rb_ary_entry(ary, i));
@@ -46,44 +76,162 @@ static VALUE sc_mean(VALUE self, VALUE ary)
   return DBL2NUM(sum / len);
 }
 
-/* static VALUE var(VALUE self, VALUE ary) */
-/* { */
+/* Calculate the variance of values in given array.
 
-/* } */
+If pop param is set to true, calculates the population variance of
+values in the array. Otherwise, the sample variance is calculated
+(default).
 
-/* static VALUE var(int argc, VALUE* argv, VALUE self) */
-/* { */
-/*   VALUE ary, sample; */
+@param ary [Array<Numeric>] an array of Numerics
+@param pop [Bool] pass true to calculate population variance,
+  default: false
 
-/*   /\* one required and one optional argument *\/ */
-/*   rb_scan_args(argc, argv, "11", &ary, &sample); */
+@example Get sample variance of array
+  StatC::Array.var([-1.4, 0, 1, 2, 3.0]).round(2)  #=> 2.93
+@example Get population variance of array
+  StatC::Array.var([-1.4, 0, 1, 2, 3.0], pop=true).round(2)  #=> 2.35
 
-/*   /\* if sample wasn't specified, set it to true *\/ */
-/*   if (NIL_P(sample)) { sample = 1; } */
-/* } */
+@raise [StatC::Error::Error] if array length is zero
 
-/* static VALUE var(int argc, VALUE* argv, VALUE self) */
-/* { */
-/*   VALUE ary, sample; */
+@return [Numeric] variance of values in the array
 
-/*   /\* one required and one optional argument *\/ */
-/*   rb_scan_args(argc, argv, "11", &ary, &sample); */
+*/
+static VALUE sc_var(int argc, VALUE* argv, VALUE obj)
+{
+  VALUE ary, calc_pop_var;
 
-/*   /\* if sample wasn't specified, set it to true *\/ */
-/*   if (NIL_P(sample)) { sample = 1; } */
-/* } */
+  /* one required and one optional argument */
+  rb_scan_args(argc, argv, "11", &ary, &calc_pop_var);
 
-void Init_stat_c(void)
+  unsigned long i = 0;
+  long double sum = 0;
+  size_t len = assert_array_not_empty(ary);
+
+  long double mean = NUM2DBL(sc_mean(obj, ary));
+
+  for (i = 0; i < len; ++i) {
+    sum += pow(sc_ary_entry(ary, i) - mean, 2);
+  }
+
+  if (NIL_P(calc_pop_var) || FALSE_P(calc_pop_var)) { /* sample variance */
+    return DBL2NUM(sum / (len - 1));
+  } else { /* population variance */
+    return DBL2NUM(sum / len);
+  }
+}
+
+/* Calculate the standard deviation of values in given array.
+
+If pop param is set to true, the standard deviation is based on
+population variance. Otherwise, sample variance is used (default).
+
+@param ary [Array<Numeric>] an array of Numerics
+@param pop [Bool] pass true to calculate population standard
+  deviation, default: false
+
+@example Get sample standard deviation of array
+  StatC::Array.sd([-1.4, 0, 1, 2, 3.0]).round(2)  #=> 1.71
+@example Get population standard deviation of array
+  StatC::Array.sd([-1.4, 0, 1, 2, 3.0], pop=true).round(2)  #=> 1.53
+
+@raise [StatC::Error::Error] if array length is zero
+
+@return [Numeric] standard deviation of values in the array
+
+*/
+static VALUE sc_sd(int argc, VALUE* argv, VALUE obj)
 {
-  sc_mStatC = rb_define_module("StatC");
+  VALUE ary, calc_pop_var;
 
+  /* one required and one optional argument */
+  rb_scan_args(argc, argv, "11", &ary, &calc_pop_var);
+
+  return DBL2NUM(sqrt(NUM2DBL(sc_var(argc, argv, obj))));
+}
+
+/* Calculate the standard deviation of values in given array.
+
+If pop param is set to true, the standard error of the mean is based
+on population variance. Otherwise, sample variance is used (default).
+
+@param ary [Array<Numeric>] an array of Numerics
+@param pop [Bool] pass true to calculate population standard
+  error of the mean, default: false
+
+@example Get sample standard error of array
+  StatC::Array.se([-1.4, 0, 1, 2, 3.0]).round(2)  #=> 0.77
+@example Get population standard error of array
+  StatC::Array.se([-1.4, 0, 1, 2, 3.0], pop=true).round(2)  #=> 0.68
+
+@raise [StatC::Error::Error] if array length is zero
+
+@return [Numeric] standard error of the mean for values in the array
+
+*/
+static VALUE sc_se(int argc, VALUE* argv, VALUE obj)
+{
+  VALUE ary, calc_pop_var;
+
+  /* one required and one optional argument */
+  rb_scan_args(argc, argv, "11", &ary, &calc_pop_var);
+
+  long double sd = NUM2DBL(sc_sd(argc, argv, obj));
+
+  size_t len = assert_array_not_empty(ary);
+
+  return DBL2NUM(sd / sqrt(len));
+}
+
+/* Document-module: StatC::Array
+
+Statistical methods operating on the values of an array
+
+*/
+static void sc_init_mArray(void)
+{
   sc_mArray = rb_define_module_under(sc_mStatC, "Array");
+
+  rb_define_singleton_method(sc_mArray, "mean", sc_mean, 1);
+  rb_define_singleton_method(sc_mArray, "var",  sc_var, -1);
+  rb_define_singleton_method(sc_mArray, "sd",   sc_sd,  -1);
+  rb_define_singleton_method(sc_mArray, "se",   sc_se,  -1);
+}
+
+/* Document-module: StatC::Error
+
+Module containing all error classes of the StatC module.
+
+ */
+static void sc_init_mError(void)
+{
   sc_mError = rb_define_module_under(sc_mStatC, "Error");
+}
 
-  sc_eError    = rb_define_class_under(sc_mError, "Error", rb_eStandardError);
 
-  rb_define_singleton_method(sc_mArray, "mean", sc_mean, 1);
-  /* rb_define_singleton_method(mArray, "var",  var,  1); */
-  /* rb_define_singleton_method(mArray, "sd",   sd,  -1); */
-  /* rb_define_singleton_method(mArray, "se",   se,  -1); */
+/* Document-class: StatC::Error::Error
+
+Error class from which all errors raised by StatC inherit. Thus, you
+can rescue from StatC::Error::Error to catch all errors specific to
+StatC.
+
+@note Inherits from StandardError
+
+*/
+static void sc_init_eError(void)
+{
+  sc_eError = rb_define_class_under(sc_mError, "Error", rb_eStandardError);
+}
+
+/* Document-module: StatC
+
+C stats module for Ruby.
+
+*/
+void Init_stat_c(void)
+{
+  sc_mStatC = rb_define_module("StatC");
+
+  sc_init_mArray();
+  sc_init_mError();
+  sc_init_eError();
 }

data/lib/stat_c/version.rb

@@ -1,3 +1,4 @@
 module StatC
-  VERSION = "0.1.0"
+  # module version number
+  VERSION = "0.2.0"
 end

data/stat_c.gemspec

@@ -10,8 +10,8 @@ Gem::Specification.new do |spec|
   spec.email         = ["moorer@udel.edu"]
   spec.license       = "GPLv3"
 
-  spec.summary       = %q{Fast statistics library. C extension.}
-  spec.description   = %q{Fast statistics library. C extension.}
+  spec.summary       = %q{Fast, well documented C stats extension for Ruby.}
+  spec.description   = %q{Fast, well documented C stats extension for Ruby.}
   spec.homepage      = "https://github.com/mooreryan/stat_c"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stat_c
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ryan Moore
@@ -114,7 +114,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.11
-description: Fast statistics library. C extension.
+description: Fast, well documented C stats extension for Ruby.
 email:
 - moorer@udel.edu
 executables: []
@@ -164,6 +164,6 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: Fast statistics library. C extension.
+summary: Fast, well documented C stats extension for Ruby.
 test_files: []
 has_rdoc: