crosstab 0.1.0

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 / 2007-11-17
+
+* First release
+

data/Manifest.txt

@@ -0,0 +1,23 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/crosstab.rb
+lib/crosstab/banner.rb
+lib/crosstab/cell.rb
+lib/crosstab/column.rb
+lib/crosstab/crosstab.rb
+lib/crosstab/extensions.rb
+lib/crosstab/generic.rb
+lib/crosstab/group.rb
+lib/crosstab/row.rb
+lib/crosstab/table.rb
+test/test_banner.rb
+test/test_cell.rb
+test/test_column.rb
+test/test_crosstab.rb
+test/test_extensions.rb
+test/test_group.rb
+test/test_missing.rb
+test/test_row.rb
+test/test_table.rb

data/README.txt

@@ -0,0 +1,133 @@
+crosstab
+    by Michael Judge <mjudge@surveycomplete.com>
+    http://crosstab.rubyforge.org/
+
+== DESCRIPTION:
+  
+Crosstab is a library for generating formatted pivot tables.
+
+== FEATURES:
+
+* Input your data as an array of hashes
+* Input a report layout, built using a Ruby DSL
+* Outputs ASCII pivot tables suitable for fast reports
+* Pretty fast: takes less than a second to process 1,000 records of data by a report with 100 rows and 10 columns.
+					 
+== SYNOPSIS:
+
+  require 'crosstab'
+  
+  data = [{:gender => "M", :age => 1},
+          {:gender => "F", :age => 2},
+          {:gender => "M", :age => 3}]
+  
+  my_crosstab = crosstab data do
+    table do
+      title "Q.A Gender:"      
+      row "Male", :gender => "M"
+      row "Female", :gender => "F"      
+    end
+
+    table do
+      title "Q.B Age:"      
+      group "18 - 54" do
+        row "18 - 34", :age => 1
+        row "35 - 54", :age => 2      
+      end      
+      row "55 or older", :age => 3      
+    end
+    
+    banner do
+      column "Total"
+      group "Gender" do
+        column "Male", :gender => "M"
+        column "Female", :gender => "F"
+      end
+    end    
+  end
+  
+  puts my_crosstab.to_s
+  
+== REPORT:
+
+# puts my_crosstab.to_s
+Table 1
+Q.A Gender:
+                                             Gender       
+                                        ----------------  
+                                Total    Male    Female   
+                                 (A)      (B)      (C)    
+                               -------  -------  -------  
+(BASE)                               3        2        1  
+
+Male                                 2        2       --  
+                                   67%     100%           
+
+Female                               1       --        1  
+                                   33%              100%  
+
+------------------------------------------------------------------------
+Table 2
+Q.B Age:
+                                             Gender       
+                                        ----------------  
+                                Total    Male    Female   
+                                 (A)      (B)      (C)    
+                               -------  -------  -------  
+(BASE)                               3        2        1  
+
+18 - 54                              2        1        1  
+-----------------------------      67%      50%     100%  
+
+  18 - 34                            1        1       --  
+                                   33%      50%           
+
+  35 - 54                            1       --        1  
+                                   33%              100%  
+
+55 or older                          1        1       --  
+                                   33%      50%           
+
+
+------------------------------------------------------------------------
+== JUST THE BEGINNING:
+
+* I hope to add in later releases:
+*   New export formats: html, pdf, csv, excel.
+*   More stats than just frequency and percentage: mean, median, std. deviation, std. error, and significance testing
+*   Optional row and table suppression for low frequencies
+*   Optional table rows populating from the data
+*   Optional table ranking -- automatically reorder rows based in descending order based on frequencies observed
+
+== REQUIREMENTS:
+
+* None
+
+== INSTALL:
+
+* sudo gem install crosstab
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007 Michael Judge
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,17 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/crosstab.rb'
+
+Hoe.new('crosstab', Crosstab::VERSION) do |p|
+  p.rubyforge_name = 'crosstab'
+  p.summary = 'Crosstab is a library for generating formatted pivot tables.'
+  p.email = "mjudge@surveycomplete.com"  
+  p.description = p.paragraphs_of('README.txt', 2..13).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.remote_rdoc_dir = '' # Release to root
+end
+
+# vim: syntax=Ruby

data/lib/crosstab.rb

@@ -0,0 +1,25 @@
+dir = File.dirname(__FILE__)
+$LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
+
+module Crosstab
+ VERSION = '0.1.0'
+end
+
+require 'crosstab/generic'
+require 'crosstab/crosstab'
+require 'crosstab/banner'
+require 'crosstab/table'
+require 'crosstab/column'
+require 'crosstab/row'
+require 'crosstab/cell'
+require 'crosstab/group'
+require 'crosstab/extensions'
+
+require 'rubygems'
+require 'text/reform'
+
+def crosstab(data, &block)
+  my_crosstab = Crosstab::Crosstab.new(&block)
+  my_crosstab.data_source(data)
+  my_crosstab
+end

data/lib/crosstab/banner.rb

@@ -0,0 +1,90 @@
+class Crosstab::Banner < Crosstab::Generic
+
+  # Pass in a block and we'll execute it within the context of this class.  If no block is passed in,
+  # a "Total" column will be added automatically.
+  # 
+  # Example:
+  # 
+  #   my_crosstab = Crosstab.new do
+  #     banner do
+  #       column "Male", :a => 1
+  #       column "Female", :a => 2
+  #     end
+  #   end
+  #   
+  def initialize(&block)
+    if block
+      instance_eval(&block) 
+    else
+      column "Total"
+    end
+  end
+
+  # attr_reader for the columns attribute which should contain an empty array, or a list of columns
+  # 
+  # Example: 
+  # 
+  #   columns
+  #   #=> []
+  #
+  #   column "Male", :a => 1
+  # 
+  #   columns
+  #   #=> [Crosstab::Column...]
+  # 
+  def columns
+    @columns ||= []
+  end
+  
+  # Creates a new Crosstab::Column and appends it to the columns array.
+  # 
+  # Example: 
+  # 
+  #   columns
+  #   #=> []
+  #
+  #   column "Male", :a => 1
+  # 
+  #   columns
+  #   #=> [Crosstab::Column...]
+  # 
+  def column(name=nil,qualification=nil)
+    columns << Crosstab::Column.new(name, qualification)
+  end
+  
+  # DSL child setter, creates a new Group, and columns created within its block will be assigned to that group.
+  # 
+  # Example: 
+  # 
+  #   columns
+  #   #=> []
+  #
+  #   group "Gender" do
+  #     column "Male", :a => 1
+  #     column "Female", :a => 2
+  #   end
+  # 
+  #   columns
+  #   #=> [Crosstab::Column..., Crosstab::Column...]
+  #   
+  #   columns[0].group.title
+  #   # => "Gender"
+  # 
+  #   columns[1].group.title
+  #   # => "Gender"
+  
+  def group(name=nil, &block)
+    if block
+      old_columns = columns.dup # Save current state
+
+      instance_eval(&block) # Execute block within current scope
+
+      g = Crosstab::Group.new(name) # Create new group
+      
+      # Set group for all of the new columns
+      (columns - old_columns).each do |col|
+        col.group g 
+      end
+    end
+  end
+end

data/lib/crosstab/cell.rb

@@ -0,0 +1,162 @@
+class Crosstab::Cell
+  # Optionally, can take options :base and :frequency for a fast initialization.
+  # 
+  # Example:
+  # 
+  #   cell = Crosstab::Cell.new
+  #   cell.frequency 2
+  #   cell.base 4
+  #   cell.percentage
+  #   # => 0.5
+  #   
+  #   cell = Crosstab::Cell.new :base => 4, :frequency => 2
+  #   cell.percentage
+  #   # => 0.5
+  #   
+  def initialize(options={})
+    base options[:base] if options[:base]
+    frequency options[:frequency] if options[:frequency]    
+  end
+
+  # DSL accessor for the base attribute.  The base is the number of records used in calculations for this cell.
+  # 
+  # Example:
+  # 
+  #   cell = Crosstab::Cell.new
+  #
+  #   cell.frequency 2
+  #   cell.base 4
+  #   
+  #   cell.percentage
+  #   # => 0.5
+  #   
+  def base(value=nil)
+    if value
+      @base = value
+    else
+      @base ||= 0
+    end
+  end
+  
+  # Returns and sets the frequency for this cell, that is, the number of records that meet both the row and column qualifications.
+  # 
+  # Example:
+  # 
+  #   cell = Crosstab::Cell.new
+  #
+  #   cell.frequency 2
+  #   cell.base 4
+  #   
+  #   cell.percentage
+  #   # => 0.5
+  #   
+  def frequency(value=nil)
+    if value
+      @frequency = value
+    else
+      @frequency ||= 0
+    end
+  end
+  
+  # Returns the frequency divided by the base.  Always a float.
+  # 
+  # Example:
+  # 
+  #   cell = Crosstab::Cell.new
+  #
+  #   cell.frequency 2
+  #   cell.base 4
+  #   
+  #   cell.percentage
+  #   # => 0.5
+  #   
+  def percentage
+    if base > 0
+      frequency.to_f / base.to_f
+    else
+      0.0
+    end
+  end
+  
+  # Returns an array of default stats (frequency, percentage, then sigtesting).  It's only really useful for printing within reports.
+  # If the frequency of the cell is 0, it returns [ "--" ] because what's the point of displaying 0, 0%?
+  # 
+  # 
+  # Example:
+  # 
+  #   cell = Crosstab::Cell.new
+  #
+  #   cell.frequency 2
+  #   cell.base 4
+  #   
+  #   cell.result
+  #   # => [2, 0.5] 
+  #
+  def result
+    if frequency > 0
+      [frequency, "#{(percentage * 100).round}%" ]
+    else
+      ["--"]
+    end
+  end
+
+  # Tests this cell against another and returns true if it is statistically significant.  The default testing level is 95%, 
+  # represented as a float (i.e., 0.95.)  Other levels supported are 0.85, 0.90, and 0.98.
+  #  
+  # Example:
+  # 
+  #   cell1 = Crosstab::Cell.new :base => 100, :frequency => 65
+  #   cell2 = Crosstab::Cell.new :base => 100, :frequency => 50
+  #   
+  #   cell1.significant_against? cell2
+  #   # => true
+  #   
+  def significant_against?(test_cell, level=0.95)
+    zfactor = { 0.98 => 2.327,
+                0.95 => 1.960,
+                0.90 => 1.645,
+                0.85 => 1.440 }
+
+    # From what I understand, a z-test is meaningless if either of the two cells are in the bottom or top 10%.
+    # So we return false.  If you're any good at statistics, I would love to hear your opinion on this.  
+    # I've done this shit for ten years and I'm still copying formulas out of books.  Frankly, it sounds odd,
+    # and I can't seem to find any good documentation on why it is that we do it this way.  10% sounds like a fucking guess.
+
+	return false unless [self, test_cell].all? { |x| (0.10..0.90).include? x.percentage }
+	
+	# The preperation
+	a = self.percentage * self.base + test_cell.percentage * test_cell.base
+	b = self.base + test_cell.base
+	c = 1.0 / self.base + 1.0 / test_cell.base
+
+    # The main calculation
+    z = (self.percentage - test_cell.percentage) / Math.sqrt(a / b * (1 - a / b) * c)
+
+    # The test
+    z >= zfactor[level]
+  end
+  
+  # DSL accessor for the column that this cell belongs to.  
+  # 
+  # Example: 
+  # 
+  #   cell = Crosstab::Cell.new
+  #   cell.column
+  #   #=> nil
+  #
+  #   cell.column Crosstab::Column.new("Male", :a => 1)
+  # 
+  #   column
+  #   #=> Crosstab::Column
+  #   
+  #   column.title
+  #   #=> "Male"
+  
+  def column(value=nil)
+    if value
+      @column = value
+    else
+      @column ||= nil
+    end
+  end
+end