histogram 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4fd1f4a522ac61d4364bc6ae948e472131c14ad0
+  data.tar.gz: b70e61b7811b3db4aa1d69e398debd20c651bc53
+SHA512:
+  metadata.gz: 9874a30f356f636e94e879f1149a20b6fe9449a0e1f4c42ae21be6dca79f531df0103d2408b0429dd5542fd0e5e1e3248648cdba0c2c9a6ebeacb5a0b2daf896
+  data.tar.gz: 7999236e1ba6ebaad1bcdb29ff1791e0397d3f7b08ed8f7824e007b63bdc37fbc31cf765b4a7ba206c40b2a303189085468488db37efb4035a490d62348af4b9

data/.gitignore

@@ -0,0 +1,3 @@
+/*.swp
+/pkg
+/coverage

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in histogram.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2006, 2007, 2008 The University of Texas at Austin
+Copyright (c) 2009, University of Colorado at Boulder and Howard Hughes
+Copyright (c) 2013, Brigham Young University
+
+The above copyright holders are collectively designated "COPYRIGHT HOLDER"
+
+Software by John T. Prince
+
+By using this software the USER indicates that he or she has read, understood and will comply with the following:
+
+COPYRIGHT HOLDER hereby grants USER permission to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of this software and its documentation for any purpose and without fee, provided that a full copy of this notice is included with the software and its documentation.
+
+Title to copyright this software and its associated documentation shall at all times remain with COPYRIGHT HOLDER. No right is granted to use in advertising, publicity or otherwise any trademark, service mark, or the name of COPYRIGHT HOLDER.
+
+This software and any associated documentation are provided "as is," and COPYRIGHT HOLDER MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING THOSE OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THAT USE OF THE SOFTWARE, MODIFICATIONS, OR ASSOCIATED DOCUMENTATION WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER INTELLECTUAL PROPERTY RIGHTS OF A THIRD PARTY. COPYRIGHT HOLDER and associated Regents, officers, and employees shall not be liable under any circumstances for any direct, indirect, special, incidental, or consequential damages with respect to any claim by USER or any third party on account of or arising from the use, or inability to use, this software or its associated documentation, even if COPYRIGHT HOLDER has been advised of the possibility of those damages.

data/README.md

@@ -0,0 +1,67 @@
+[![Gem Version](https://badge.fury.io/rb/histogram.png)](http://badge.fury.io/rb/histogram)
+
+# histogram
+
+Generates histograms similar to R's hist and numpy's histogram functions.
+Inspired somewhat by [Richard Cottons's matlab implementation](http://www.mathworks.com/matlabcentral/fileexchange/21033-calculate-number-of-bins-for-histogram)
+and the wikipedia [histogram article](http://en.wikipedia.org/wiki/Histogram).
+
+## NOTE
+
+versions <= 0.1.0 had a stupid bug in the Freedman-Diaconis method for finding
+bins.  So, if you weren't specifying your own number of bins or bin sizes,
+then you may not have been getting the optimal bin size by default.
+
+### Typical usage:
+
+    require 'histogram/array'  # enables Array#histogram
+
+    data = [0,1,2,2,2,2,2,3,3,3,3,3,3,3,3,3,5,5,9,9,10]
+    # by default, uses Scott's method to calculate optimal number of bins
+    # and the bin values are midpoints between the bin edges 
+    (bins, freqs) = data.histogram 
+    # equivalent to:  data.histogram(:scott, :bin_boundary => :avg)  
+
+### Multiple types of binning behavior:
+
+    # :scott, :fd, :sturges, or :middle  
+    data.histogram(:fd)  # use Freedman-Diaconis method to calc num bins
+    data.histogram(:middle) # (median value between the three methods)
+    (bins, freqs) = data.histogram(20)                         # use 20 bins
+    (bins, freqs) = data.histogram([-3,-1,4,5,6])              # custom bins
+
+    (bins, freqs) = data.histogram(10, :min => 2, :max => 12)  # 10 bins with set min and max
+
+    # bins are midpoints, but can be set as minima
+    (bins, freqs) = data.histogram([-3,-1,4,5,6], :bin_boundary => :min) # custom bins with :min
+
+    # can also set the bin_width (which interpolates between the min and max of the set)
+    (bins, freqs) = data.histogram(:bin_width => 0.5)
+
+### Multiple Datasets:
+      
+Sometimes, we want to create histograms where the bins are calculated based on
+all the data sets.  That way, the resulting frequencies will all line up:
+
+    # returns [bins, freq1, freq2 ...]
+    (bins, *freqs) = set1.histogram(30, :other_sets => [[3,3,4,4,5], [-1,0,0,3,3,6]])
+
+### Histograms with weights/fractions:
+  
+    # histogramming with weights
+    data.histogram(20, :weights => [3,3,8,8,9,9,3,3,3,3])
+
+### Works with NArray objects
+  
+    require 'histogram/narray'    # enables NArray#histogram
+    # if the calling object is an NArray, the output is two NArrays:
+    (bins, freqs) = NArray.float(20).random!(3).histogram(20)
+    # bins and freqs are both NArray.float objects
+
+## Installation
+
+    gem install histogram
+
+## See Also
+
+[aggregate](http://github.com/josephruscio/aggregate), [rserve-client](http://rubygems.org/gems/rserve-client), [rsruby](http://github.com/alexgutteridge/rsruby)

data/Rakefile

@@ -0,0 +1,19 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rubabel #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/bin/histogram

@@ -0,0 +1,379 @@
+#!/usr/bin/ruby
+
+
+raise NotImplementedError, "this executable still needs some work"
+
+require 'optparse'
+require 'rubygems'
+require 'histogram'
+
+class Array
+  include Histogram
+end
+
+opt = {}
+opt[:type] = 'avg'
+opt[:bins] = 5
+opt[:help] = false
+opt[:plot] = false
+opt[:labels] = false
+opt[:with] = 'b'
+
+progname = File.basename(__FILE__)
+opts = OptionParser.new do |op|
+  op.banner = "usage: #{progname} [OPTIONS] val val ..."
+  op.separator ""
+  op.separator "  outputs bins and frequencies in two rows (space delimited)"
+  #op.separator "  of the bins.  The number of bins is given by:"
+  #op.separator "  ??? 10**(log10(#vals) - 1) ????"
+  op.separator ""
+  op.separator "    -                               ' - ' to separate multiple datasets"
+  op.on("-t", "--type <min|avg>", "binning style  [default: #{opt[:type]}]") {|v| opt[:type] = v }
+  op.on("-b", "--bins <num>", "number of bins [default: #{opt[:bins]}]") {|v| opt[:bins] = v }
+  op.separator "        --bins <start,stop,[step]>   user specified range for bins (*)"
+  op.separator "        --bins <num num ...>         user specified custom bins (**)"
+  op.on("-l", "--labels <set1,set2,...>", "label the datasets") {|v| opt[:labels] = v }
+  op.on("-c", "--cols", "prints 2 cols instead of rows (tab delim.)") {|v| opt[:cols] = v }
+  op.on("-i", "--input_cols", "interactively write or paste cols") {|v| opt[:input_cols] = v }
+  op.on("-r", "--input_rows", "interactively write or paste rows") {|v| opt[:input_rows] = v }
+  op.on("--file_rows <filename>", "rows inside of a file") {|v| opt[:file_rows] = v }
+  op.on("--yml-ar <filename>", "one array of data in yml") {|v| opt[:yml_ar] = v }
+  op.on("-p", "--plot <filename>", "plots the histogram in extension format (.png|.eps)") {|v| opt[:plot] = v }
+  op.separator "        --plot terminal              plots in X11 window"
+  op.on("-w", "--with {b|p|lp|l}", "plot with style: ") {|v| opt[:with] = v }
+  op.separator "                                         b=boxes,p=points,lp=lines/points,l=lines"
+  op.on("-h", "--help", "prints arguments and examples") {|v| opt[:help] = v}
+  
+  op.separator ""
+  op.separator "NOTES:"
+  op.separator "    Do NOT use '--option=val' syntax ; instead use '--option val'"
+  op.separator "    * 'stop' will always be included, even if it isn't stepped on"
+  op.separator "    ** custom bins specified if > 1 args after --bins"
+end
+
+def entry_examples(progname)
+  array = [] 
+  array << ""
+  array << "ENTRY EXAMPLES:"
+  array << "   #{progname} 7 8 9 -b 2"
+  array << "       # vals: 7,8,9 ; number_of_bins: 2"
+  array << "   #{progname} -b 2 7 8 9"
+  array << "       # vals: [none]  bins: 2 7 8 9  (<--probably not what you wanted)"
+  array << "   #{progname} -b 2 -t min 7 8 9"
+  array << "       # vals: 7,8,9 ; number_of_bins: 2 ; type: min"
+  array << "   #{progname} 7 8 9 -b 0 1 2 3"
+  array << "       # vals: 7,8,9 ; bins: 0 1 2 3"
+  array << "   #{progname} -b 0 1 2 3 -- 7 8 9"
+  array << "       # vals: 7,8,9 ; bins: 0 1 2 3"
+  array << "   #{progname} -i"
+  array << "       # [then paste in cols]"
+  array << "   #{progname} -r -b 10"
+  array << "       # number_of_bins: 10 ; [then paste in datasets as rows]"
+  array << ""
+  array << "PLOT EXAMPLES:"
+  array << "   #{progname} 7 8 9 -b 2 -p filename.png"
+  array << "       # creates a png image of the plot"
+  array << "   #{progname} 7 8 9 -b 2 -p filename.eps -w lp"
+  array << "       # creates an eps image of the plot with lines and points"
+  array << "   #{progname} 7 8 9 -b 2 -p terminal --with l"
+  array << "       # creates a plot in window with lines"
+  array.join("\n")
+end
+
+# grab --bins (-b) option and all valid trailing values
+# returns bins (as array) and args array stripped of --bins stuff
+def remove_bins(argv)
+  bins = []
+  pickup_bins = false
+  dash_regex = /^-/o
+  newargv = []
+  argv.each do |arg|
+    if arg =~ dash_regex
+      if arg == '-b' || arg == '--bins'  
+        pickup_bins = true
+      else  ## any other options, then we start picking up vals again
+        pickup_bins = false 
+        newargv << arg
+      end
+    elsif pickup_bins
+      bins << arg
+    else
+      newargv << arg
+    end
+  end
+  [bins, newargv]
+end
+
+# takes args like this:
+# %w(23 43 - 432 - 42 43 32)
+# returns each val as .to_f
+# -> [[23, 43], [432], [42, 43, 32]]
+def extract_vals(argv)
+  vals_ar = []
+  if argv.first == '-'
+    argv.shift
+  end
+  vals_ar << []
+  current = vals_ar.last
+  argv.each do |val|
+    if val == '-'
+      vals_ar << []
+      current = vals_ar.last
+    else
+      current << val.to_f
+    end
+  end
+  vals_ar
+end
+
+
+# returns as arrays the datasets given
+# cols is limited to two columns
+def get_input_vals(cols=true)
+  datasets = []
+  if cols
+    puts "==> Paste (or enter) values as a single column."
+    puts "==> OR paste bins, then values as two columns."
+    puts "==> [multiple datasets can be input on command line,"
+    puts "==>  or as rows]"
+  else
+    puts "==> Paste (or enter) values (multiple datasets OK) as rows"
+    puts "==> The first row will be considered the bins unless"
+    puts "==> the bins were already specified on the command line"
+  end
+  lines = []
+  while (string = gets)
+    if string =~ /.+/
+      lines << string 
+    else
+      break
+    end
+  end
+  ar_of_ar = lines.map do |line|
+    line.chomp.split(/\s+/)
+  end
+
+  if cols
+    ds0 = []
+    ds1 = []
+    ar_of_ar.each do |ar|
+      if ar[0] != '' 
+        ds0 << ar[0]
+      end
+      if ar[1]
+        ds1 << ar[1]
+      end
+    end
+    datasets << ds0
+    datasets << ds1 if ds1.size > 0
+  else
+    datasets = ar_of_ar
+  end
+  datasets 
+end
+
+
+# escapes any ' chars
+def escape_to_gnuplot(string)
+  # long way, but it works.
+  new_string = ""
+  string.split(//).each do |chr|
+    if chr == "'" ; new_string << "\\" end 
+    new_string << chr
+  end
+  new_string
+end
+
+def bin_range_arg_to_custom_bin_array(arg)
+  range = arg.split ','
+  range[2] ||= 1  # no step? then its one
+  range.map! {|v| v.to_f } 
+  ## Create custom bins from the range numbers
+  if range[1] < range[0] ; abort "stop cannot be less than start" end
+  create_bins(*range)
+end
+
+# returns an array of bins
+# stop is always included, even if it is not stepped on
+def create_bins(start, stop, step)
+  bins = []
+  (start...stop).step(step) {|v| bins << v }
+  if bins.last != stop
+    bins << stop
+  end
+  bins
+end
+
+# takes an array of bins and array of vals
+# vals can be an array of arrays (multiple histograms)
+# should be given as single array if its a single set
+# with = {b|l|lp|p}
+# boxes,lines,linespoints,points
+def plot_histogram(bins, vals_ar, filename, bin_type, with, labels=nil)
+  plot_with = case with
+              when 'b' ; 'boxes fs solid'
+              when 'l' ; 'lines'
+              when 'lp' ; 'linespoints'
+              when 'p' ; 'points'
+              end
+              
+
+  case filename
+  when 'terminal'
+    output_type = :terminal
+  when /\.eps$/
+    output_type = :eps
+  when /\.png$/
+    output_type = :png
+  else
+    output_type = :png
+    filename << ".png"
+  end
+
+  terminal_string = ''
+  case output_type
+  when :terminal
+    terminal_string = "x11" 
+  when :png
+    terminal_string = "png noenhanced" 
+  when :eps
+    terminal_string = "postscript eps noenhanced color"
+    # \"Helvetica\"" 
+  end
+  Gnuplot.open do |gp|
+    Gnuplot::Plot.new( gp ) do |plot|
+      plot.terminal terminal_string
+      plot.output(filename) unless output_type == :terminal
+      #plot.title "Histogram"
+      plot.xlabel "bins (type:#{bin_type})"
+      plot.ylabel "occurences"
+      plot.style "line 1 lt 1"
+      plot.style "line 2 lt 12"
+      #plot.style  "line 1 lt 1 lw #{opts.lw} pt 7 ps #{opts.ps}",
+      #plot.yrange "[-0.05:#{1.0 + 0.2*files.size}]"
+      vals_ar.each_with_index do |vals,i|
+        plot.data << Gnuplot::DataSet.new([bins,vals]) do |ds|
+          ds.with = plot_with
+          if labels
+            if labels[i]
+              ds.title = labels[i]
+            else
+              ds.notitle
+            end
+          else
+            ds.notitle
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+#################################################
+# MAIN:
+#################################################
+(bins, newargv) = remove_bins(ARGV.to_a)
+ARGV.clear
+
+# parse the options out
+opts.parse!(newargv)
+
+if opt[:help]
+  puts opts
+  puts entry_examples(progname)
+  exit
+end
+
+# get interactive values or pull them off the command line
+vals_ar = []
+if opt[:input_cols]
+  datasets = get_input_vals()
+  if datasets.size == 2
+    bins = datasets[0]
+    vals_ar = [datasets[1]]
+  else
+    vals_ar = [datasets[0]]
+  end
+elsif opt[:input_rows]
+  datasets = get_input_vals(false)
+  ## set the bins to the first dataset if none given
+  if bins.size == 0
+    bins = datasets.shift
+  end
+  vals_ar = datasets
+elsif opt[:file_rows]
+  vals_ar = IO.readlines(opt[:file_rows]).select {|v| v =~ /\d/ and v !~ /^#/ }.map {|v| v.chomp.split(/\s+/) }
+elsif opt[:yml_ar]  # just one array of data
+  require 'yaml'
+  vals_ar = [YAML.load_file(opt[:yml_ar])]
+else
+  vals_ar = extract_vals(newargv)
+end
+
+# print help if we don't have any values given
+if vals_ar[0].size == 0
+  puts opts
+  exit
+end
+
+
+# prep the bins (if one value, then its the # of bins and not a list of bins)
+if bins.size == 0
+  bins = opt[:bins] ## should be default value since we already swipe the args
+elsif bins.size == 1
+  bin_arg = bins.first
+  ## if there are commas then this specifies a range:
+  if bin_arg =~ /,/
+    bins = bin_range_arg_to_custom_bin_array(bin_arg)
+  ## no commas?  then this is the number of bins:
+    bins = bins.map {|v| v.to_f }
+  else
+    bins = bin_arg.to_i
+  end
+else # custom array
+  bins = bins.map {|v| v.to_f }
+end
+
+
+vec_ar = vals_ar.map do |vals|
+  vals.map {|v| v.to_f }
+end
+first_vec = vec_ar.shift
+
+#outbins, outfreqs = first_vec.histogram(bins, opt[:type].to_sym)  # for one
+#puts "BINS: #{bins}"
+#[first_vec, *vec_ar].each do |vec|
+#  puts "DATA: #{vec}"
+#end
+
+output = first_vec.histogram(bins, opt[:type].to_sym, *vec_ar)
+# first ar is the bins, rest are the frequencies
+
+# output
+if opt[:cols]
+  SyncEnumerator.new(output).each do |row|
+    puts row.join(' ')
+  end
+else
+  output.each do |row|
+    puts row.join(' ')
+  end
+end
+
+if opt[:labels]
+  labels = opt[:labels].split(',')
+else
+  labels = nil
+end
+
+# convert into arrays
+output.map! {|vec| vec.to_a }
+bins = output.shift
+if opt[:plot]
+  require 'gnuplot'
+  plot_histogram( bins, output, opt[:plot], opt[:type], opt[:with], labels)
+end
+
+

data/histogram.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'histogram/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "histogram"
+  spec.version       = Histogram::VERSION
+  spec.authors       = ["John T. Prince"]
+  spec.email         = ["jtprince@gmail.com"]
+  spec.description   = %q{gives objects the ability to 'histogram' in several useful ways}
+  spec.summary       = %q{histograms data in different ways}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+
+  [ "bundler ~> 1.3", 
+    "rake ~> 10.1.0",
+    "simplecov ~> 0.7.1",
+    "rspec ~> 2.13.0",
+    "narray",
+  ].each do |argline|
+    spec.add_development_dependency *argline.split(' ', 2).compact
+  end
+end

data/lib/histogram.rb

@@ -0,0 +1,348 @@
+
+class NArray 
+end
+
+module Histogram
+  DEFAULT_BIN_METHOD = :scott
+  DEFAULT_QUARTILE_METHOD = :moore_mccabe
+
+  class << self
+    # returns (min, max)
+    def minmax(obj)
+      if obj.is_a?(Array)
+        obj.minmax
+      else
+        mn = obj[0]
+        mx = obj[0]
+        obj.each do |val|
+          if val < mn then mn = val end
+          if val > mx then mx = val end
+        end
+        [mn, mx]
+      end
+    end
+
+    # returns (mean, standard_dev)
+    # if size == 0 returns [nil, nil]
+    def sample_stats(obj)
+      _len = obj.size
+      return [nil, nil] if _len == 0
+      _sum = 0.0 ; _sum_sq = 0.0
+      obj.each do |val|
+        _sum += val
+        _sum_sq += val * val
+      end
+      std_dev = _sum_sq - ((_sum * _sum)/_len)
+      std_dev /= ( _len > 1 ? _len-1 : 1 )
+      [_sum.to_f/_len, Math.sqrt(std_dev)]
+    end
+
+    # opts: 
+    #
+    #     defaults:
+    #     :method => :moore_mccabe, :tukey
+    #     :sorted => false
+    #   
+    def iqrange(obj, opts={})
+      opt = {method: DEFAULT_QUARTILE_METHOD, sorted: false}.merge( opts )
+      srted = opt[:sorted] ? obj : obj.sort 
+      sz = srted.size
+      answer = 
+        case opt[:method]
+        when :tukey
+          hi_idx = sz / 2
+          lo_idx = (sz % 2 == 0) ? hi_idx-1 : hi_idx
+          median(srted[hi_idx..-1]) - median(srted[0..lo_idx])
+        when :moore_mccabe
+          hi_idx = sz / 2
+          lo_idx = hi_idx - 1
+          hi_idx += 1 unless sz.even?
+          median(srted[hi_idx..-1]) - median(srted[0..lo_idx])
+        else
+          raise ArgumentError, "method must be :tukey"
+        end
+      answer.to_f
+    end
+
+    # finds median on a pre-sorted array
+    def median(sorted)
+      (sorted[(sorted.size - 1) / 2] + sorted[sorted.size / 2]) / 2.0
+    end
+  end
+
+  # returns(integer) takes :scott|:sturges|:fd|:middle
+  #
+  # middle is the median between the other three values
+  #
+  # inspired by {Richard Cotton's matlab
+  # implementation}[http://www.mathworks.com/matlabcentral/fileexchange/21033-calculate-number-of-bins-for-histogram]
+  # and the {histogram page on
+  # wikipedia}[http://en.wikipedia.org/wiki/Histogram]
+  def number_of_bins(methd=DEFAULT_BIN_METHOD, quartile_method=DEFAULT_QUARTILE_METHOD)
+    if methd == :middle
+      [:scott, :sturges, :fd].map {|v| number_of_bins(v) }.sort[1]
+    else
+      nbins = 
+        case methd
+        when :scott
+          range = (self.max - self.min).to_f
+          (mean, stddev) = Histogram.sample_stats(self) 
+          range / ( 3.5*stddev*(self.size**(-1.0/3)) )
+        when :sturges
+          1 + Math::log(self.size, 2)
+        when :fd
+          2 * Histogram.iqrange(self, method: quartile_method) * (self.size**(-1.0/3))
+        end
+      nbins = 1 if nbins <= 0
+      nbins.ceil.to_i
+    end
+  end
+
+  # Returns [bins, freqs]
+  # 
+  # histogram(bins, opts)
+  # histogram(opts)
+  #
+  # Options:
+  #
+  #     :bins => :scott    Scott's method    range/(3.5σ * n^(-1/3))
+  #              :fd       Freedman-Diaconis range/(2*iqrange *n^(-1/3)) (default)
+  #              :sturges  Sturges' method   log_2(n) + 1 (overly smooth for n > 200)
+  #              :middle   the median between :fd, :scott, and :sturges
+  #              <Integer> give the number of bins
+  #              <Array>   specify the bins themselves
+  #
+  #     :bin_boundary  => :avg      boundary is the avg between bins (default)
+  #                       :min      bins specify the minima for binning
+  #
+  #     :bin_width => <float> width of a bin (overrides :bins)
+  #     :min => <float> # explicitly set the min
+  #     :max => <float> # explicitly set the max val
+  #     
+  #     :other_sets => an array of other sets to histogram
+  #
+  # Examples 
+  #
+  #    require 'histogram/array'
+  #    ar = [-2,1,2,3,3,3,4,5,6,6]
+  #    # these return: [bins, freqencies]
+  #    ar.histogram(20)                  # use 20 bins
+  #    ar.histogram([-3,-1,4,5,6], :bin_boundary => :avg) # custom bins
+  #    
+  #    # returns [bins, freq1, freq2 ...]
+  #    (bins, *freqs) = ar.histogram(30, :bin_boundary => :avg, :other_sets => [3,3,4,4,5], [-1,0,0,3,3,6])
+  #    (ar_freqs, other1, other2) = freqs
+  #
+  #    # histogramming with weights
+  #    w_weights.histogram(20, :weights => [3,3,8,8,9,9,3,3,3,3]) 
+  #
+  #    # with NArray
+  #    require 'histogram/narray'
+  #    NArray.float(20).random!(3).histogram(20)
+  #       # => [bins, freqs]  # are both NArray.float objects
+  #
+  # Notes
+  #
+  # * The lowest bin will be min, highest bin the max unless array given.
+  # * Assumes that bins are increasing.
+  # * :avg means that the boundary between the specified bins is at the avg
+  #   between the bins (rounds up )
+  # * :min means that to fit in the bin it must be >= the bin and < the next
+  #   (so, values lower than first bin are not included, but all values
+  #   higher, than last bin are included.  Current implementation of custom
+  #   bins is slow.
+  # * if other_sets are supplied, the same bins will be used for all the sets.
+  #   It is useful if you just want a certain number of bins and for the sets
+  #   to share the exact same bins. In this case returns [bins, freqs(caller),
+  #   freqs1, freqs2 ...]
+  # * Can also deal with weights.  :weights should provide parallel arrays to
+  #   the caller and any :other_sets provided.   
+  def histogram(*args)
+    make_freqs_proc = lambda do |obj, len|
+      if obj.is_a?(Array)
+        Array.new(len, 0.0)
+      elsif obj.is_a?(NArray)
+        NArray.float(len)
+      end
+    end
+
+    case args.size
+    when 2
+      (bins, opts) = args
+    when 1
+      arg = args.shift
+      if arg.is_a?(Hash)
+        opts = arg
+      else
+        bins = arg
+        opts = {}
+      end
+    when 0
+      opts = {}
+      bins = nil
+    else
+      raise ArgumentError, "accepts no more than 2 args"
+    end
+
+    opts = ({ :bin_boundary => :avg, :other_sets => [] }).merge(opts)
+
+    bins = opts[:bins] if opts[:bins]
+    bins = DEFAULT_BIN_METHOD unless bins
+
+    bin_boundary = opts[:bin_boundary]
+    other_sets = opts[:other_sets]
+
+    bins_array_like = bins.kind_of?(Array) || bins.kind_of?(NArray) || opts[:bin_width]
+    all = [self] + other_sets 
+
+    if bins.is_a?(Symbol)
+      bins = number_of_bins(bins)
+    end
+
+    weights = 
+      if opts[:weights]
+        have_frac_freqs = true
+        opts[:weights][0].is_a?(Numeric) ? [ opts[:weights] ] : opts[:weights]
+      else
+        []
+      end
+
+    # we need to know the limits of the bins if we need to define our own bins
+    if opts[:bin_width] || !bins_array_like 
+      calc_min, calc_max = 
+        unless opts[:min] && opts[:max]
+          (mins, maxs) = all.map {|ar| Histogram.minmax(ar) }.transpose
+          [mins.min, maxs.max]
+        end
+    end
+    _min = opts[:min] || calc_min
+    _max = opts[:max] || calc_max
+
+    if opts[:bin_width]
+      bins = []
+      _min.step(_max, opts[:bin_width]) {|v| bins << v }
+    end
+
+    _bins = nil
+    _freqs = nil
+    if bins_array_like
+      ########################################################
+      # ARRAY BINS:
+      ########################################################
+      _bins = 
+        if bins.is_a?(Array)
+          bins.map {|v| v.to_f } 
+        elsif bins.is_a?(NArray)
+          bins.to_f
+        end
+      case bin_boundary
+      when :avg
+        freqs_ar = all.zip(weights).map do |xvals, yvals|
+
+          _freqs = make_freqs_proc.call(xvals, bins.size)
+
+          break_points = [] 
+          (0...(bins.size)).each do |i|
+            bin = bins[i]
+            break if i == (bins.size - 1)
+            break_points << avg_ints(bin,bins[i+1]) 
+          end
+          (0...(xvals.size)).each do |i|
+            val = xvals[i]
+            height = have_frac_freqs ? yvals[i] : 1
+            if val < break_points.first
+              _freqs[0] += height
+            elsif val >= break_points.last
+              _freqs[-1] += height 
+            else
+              (0...(break_points.size-1)).each do |i| 
+                if val >= break_points[i] && val < break_points[i+1]
+                  _freqs[i+1] += height
+                  break
+                end
+              end
+            end
+          end
+          _freqs 
+        end
+      when :min
+        freqs_ar = all.zip(weights).map do |xvals, yvals|
+
+          #_freqs = VecI.new(bins.size, 0)
+          _freqs = make_freqs_proc.call(xvals, bins.size)
+          (0...(xvals.size)).each do |i|
+            val = xvals[i]
+            height = have_frac_freqs ? yvals[i] : 1
+            last_i = 0
+            last_found_j = false
+            (0...(_bins.size)).each do |j|
+              if val >= _bins[j]
+                last_found_j = j
+              elsif last_found_j
+                break
+              end
+            end
+            if last_found_j ; _freqs[last_found_j] += height ; end
+          end
+          _freqs
+        end
+      end
+    else
+      ########################################################
+      # NUMBER OF BINS:
+      ########################################################
+      # Create the scaling factor
+
+      dmin = _min.to_f
+      conv = bins.to_f/(_max - _min)
+
+      _bins = 
+        if self.is_a?(Array)
+          Array.new(bins)
+        elsif self.is_a?(NArray)
+          NArray.float(bins)
+        end
+
+      freqs_ar = all.zip(weights).map do |xvals, yvals|
+
+        # initialize arrays
+        _freqs = make_freqs_proc.call(xvals, bins)
+        _len = size
+
+        # Create the histogram:
+        (0...(xvals.size)).each do |i|
+          val = xvals[i]
+          height = have_frac_freqs ? yvals[i] : 1
+          index = ((val-_min)*conv).floor
+          if index == bins
+            index -= 1
+          end
+          _freqs[index] += height
+        end
+        _freqs
+      end
+
+      # Create the bins:
+      iconv = 1.0/conv
+      case bin_boundary
+      when :avg
+        (0...bins).each do |i|
+          _bins[i] = ((i+0.5) * iconv) + dmin
+        end
+      when :min
+        (0...bins).each do |i|
+          _bins[i] = (i * iconv) + dmin
+        end
+      end
+    end
+    [_bins] + freqs_ar
+  end
+
+  def avg_ints(one, two) # :nodoc:
+    (one.to_f + two.to_f) / 2.0
+  end
+
+end
+
+
+

data/lib/histogram/array.rb

@@ -0,0 +1,5 @@
+require 'histogram'
+
+class Array
+  include Histogram
+end

data/lib/histogram/narray.rb

@@ -0,0 +1,5 @@
+require 'histogram'
+
+class NArray
+  include Histogram
+end

data/lib/histogram/plot.rb

@@ -0,0 +1,7 @@
+
+module Histogram
+  module Plot
+    def plot_with_normal()
+    end
+  end
+end

data/lib/histogram/version.rb

@@ -0,0 +1,3 @@
+module Histogram
+  VERSION = "0.2.1"
+end

data/spec/histogram_spec.rb

@@ -0,0 +1,162 @@
+require 'spec_helper'
+
+require 'histogram'
+
+RSpec::Matchers.define :be_within_rounding_error_of do |expected|
+  match do |actual|
+    (act, exp) = [actual, expected].map {|ar| ar.collect {|v| v.to_f.round(8) } }
+    act.to_a.should == exp.to_a
+  end
+end
+
+shared_examples 'something that can histogram' do
+  it 'makes histograms with the specified number of bins' do
+    (bins, freqs) = obj0.histogram(5)
+    [bins, freqs].each {|ar| ar.should be_a(obj0.class) }
+    [bins,freqs].zip( [ [1,3,5,7,9], [2,2,2,2,3] ] ).each do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'returns bins as the min boundary if given that option' do
+    (bins, freqs) = obj0.histogram(5, :bin_boundary => :min)
+    [bins, freqs].zip( [ [0,2,4,6,8], [2,2,2,2,3] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'makes histograms when given the bins' do
+    bins, freqs = obj1.histogram([1,3,5,7,9])
+    [bins, freqs].zip( [ [1,3,5,7,9], [3,1,1,2,3] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'interprets bins as the min boundary when given the bin_boundary option' do
+    bins, freqs = obj2.histogram([1,3,5,7,9], :bin_boundary => :min)
+    [bins, freqs].zip( [ [1,3,5,7,9], [3,0,2,2,3] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'can histogram multiple sets' do
+    (bins, freq1, freq2, freq3) = obj3.histogram([1,2,3,4], :other_sets => [obj4, obj4])
+    bins.should be_within_rounding_error_of [1,2,3,4]
+    freq1.should be_within_rounding_error_of [2.0, 2.0, 2.0, 3.0]
+    freq2.should be_within_rounding_error_of [0.0, 5.0, 0.0, 1.0]
+    freq3.should be_within_rounding_error_of freq2
+  end
+
+  it 'works with a given min val' do
+    (bins, freqs) = obj5.histogram(4, :min => 2, :bin_boundary => :min)
+    [bins, freqs].zip( [ [2.0, 3.5, 5.0, 6.5], [4.0, 1.0, 2.0, 3.0] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'works with a given max val' do
+    (bins, freqs) = obj5.histogram(4, :max => 7, :bin_boundary => :min)
+    [bins, freqs].zip( [ [1.0, 2.5, 4.0, 5.5] ,[2.0, 3.0, 2.0, 3.0] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'works with given min/max vals' do
+    (bins, freqs) = obj5.histogram(4, :min => 2, :max => 7, :bin_boundary => :min)
+    [bins, freqs].zip( [ [2.0, 3.25, 4.5, 5.75], [4.0, 1.0, 1.0, 4.0] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'can use equal weights' do
+    weights = Array.new(obj1.size, 3)
+    bins, freqs = obj1.histogram([1,3,5,7,9], :weights => weights)
+    [bins, freqs].zip( [ [1,3,5,7,9], [3,1,1,2,3].map {|v| v * 3} ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+  it 'can use unequal weights' do
+    weights = [10, 0, 0, 0, 50, 0, 0, 0, 0.2, 0.2]
+    (bins, freqs) = obj1.histogram([1,3,5,7,9], :weights => weights)
+    [bins, freqs].zip( [ [1,3,5,7,9], [10, 0, 50, 0, 0.4] ] ) do |ar, exp|
+      ar.should be_within_rounding_error_of exp
+    end
+  end
+
+end
+
+describe Histogram do
+  tmp = { 
+    obj0: (0..10).to_a,
+    obj1: [0, 1, 1.5, 2.0, 5.0, 6.0, 7, 8, 9, 9],
+    obj2: [-1, 0, 1, 1.5, 2.0, 5.0, 6.0, 7, 8, 9, 9, 10], 
+    obj3: [1, 1, 2, 2, 3, 3, 4, 4, 4],
+    obj4: [2, 2, 2, 2, 2, 4],
+    obj5: [1,2,3,3,3,4,5,6,7,8],
+  }
+  data = tmp.each {|k,v| [k, v.map(&:to_f).extend(Histogram)] }
+
+  let(:data) { data }
+
+  data.each do |obj, ar|
+    let(obj) { ar.map(&:to_f).extend(Histogram) }
+  end
+
+  describe Array do
+    it_behaves_like 'something that can histogram'
+  end
+
+  have_narray = 
+    begin
+      require 'narray'
+      NArray.respond_to?(:to_na)
+      true
+    rescue
+      false
+    end
+
+  describe NArray, :pending => !have_narray do
+    data.each do |obj, ar|
+      let(obj) { NArray.to_na(ar).to_f.extend(Histogram) }
+    end
+    it_behaves_like 'something that can histogram'
+  end
+
+  describe 'calculating bins' do
+    let(:even) {
+      [1,2,3,4,5,6,7,8].extend(Histogram)
+    }
+    let(:odd) { even[0..-2] }
+
+    let(:data_array) {
+      [0,1,2,2,2,2,2,3,3,3,3,3,3,3,3,3,5,5,9,9,10,20,15,15,15,16,17].extend(Histogram)
+    }
+
+    it 'calculates :sturges, :scott, :fd, or :middle' do
+      answers = [6,3,6,6]
+      [:sturges, :scott, :fd, :middle].zip(answers) do |mth, answ|
+        # these are **frozen**, not checked against other implementations, yet
+        # However, I've meticulously gone over the implementation of sturges, scott
+        # and fd and am confident they are correct.
+        # Note, there is some room for disagreement with how an interquartile
+        # range is calculated (I only have 2 simple methods implemented here).
+        # Also, I take the ceil of the resulting value and others may round.
+        data_array.number_of_bins(mth).should == answ
+      end
+    end
+
+    it 'calculates the interquartile range via moore_mccabe' do
+      Histogram.iqrange(even, method: :moore_mccabe).should == 4.0
+      Histogram.iqrange(odd, method: :moore_mccabe).should == 4.0
+    end
+
+    it 'calculates the interquartile range via tukey' do
+      Histogram.iqrange(even, method: :tukey).should == 4.0
+      Histogram.iqrange(odd, method: :tukey).should == 3.0
+    end
+
+
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+require 'simplecov'
+SimpleCov.start
+
+require 'rspec'
+
+require 'rspec/core/formatters/progress_formatter'
+# doesn't say so much about pending guys
+class QuietPendingFormatter < RSpec::Core::Formatters::ProgressFormatter
+  def example_pending(example)
+    output.print pending_color('*')
+  end
+end
+
+require 'rspec/core/formatters/documentation_formatter'
+class QuietPendingDocFormatter < RSpec::Core::Formatters::DocumentationFormatter
+  def example_pending(example)
+    output.puts pending_color( "<pending>: #{example.execution_result[:pending_message]}" )
+  end
+end
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.formatter = QuietPendingDocFormatter
+  config.color = true
+end
+
+TESTFILES = File.dirname(__FILE__) + "/testfiles"
+
+

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: histogram
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- John T. Prince
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+- !ruby/object:Gem::Dependency
+  name: narray
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: gives objects the ability to 'histogram' in several useful ways
+email:
+- jtprince@gmail.com
+executables:
+- histogram
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/histogram
+- histogram.gemspec
+- lib/histogram.rb
+- lib/histogram/array.rb
+- lib/histogram/narray.rb
+- lib/histogram/plot.rb
+- lib/histogram/version.rb
+- spec/histogram_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: histograms data in different ways
+test_files:
+- spec/histogram_spec.rb
+- spec/spec_helper.rb