crosstab 0.1.0

data/lib/crosstab/column.rb

@@ -0,0 +1,64 @@
+class Crosstab::Column < Crosstab::Generic
+  def initialize(label=nil, qual=nil)    
+    title label if label
+    qualification qual if qual
+  end
+  
+  # attr_reader for the records attribute which should contain an empty array, or -- if calculate was called on
+  # the crosstab -- this will contain the array of records that fit this column's qualification.
+  # 
+  # Example:
+  # 
+  #   my_crosstab = Crosstab::Crosstab.new do
+  #     data_source [{:a => 1, :b => 1}, {:a => 2, :b => 2}]
+  #     
+  #     banner do
+  #       title "Age"
+  #       column "18-34", :b => 1
+  #       column "35-54", :b => 2
+  #     end
+  #     
+  #     table do
+  #       row "Male", :a => 1
+  #       row "Female", :a => 2
+  #     end
+  #   end
+  #   
+  #   my_crosstab.calculate
+  #   
+  #   my_crosstab.banner.columns[0].title
+  #   # => "18-34"
+  #   
+  #   my_crosstab.banner.columns[0].records
+  #   # => [{:a => 1, :b => 1}]
+  #   
+  def records(value=nil)
+    if value
+      @records = value
+    else
+      @records ||= []
+    end
+  end
+  
+  # DSL accessor for the group attribute
+  # 
+  # Example:
+  #    
+  #    group
+  #    # => nil
+  #    
+  #    group Crosstab::Group.new("Gender")
+  #    # => Crosstab::Group...
+  #    
+  #    group.title
+  #    # => "Gender"
+  #    
+  def group(g=nil)
+    if g
+      @group = g
+      g.children << self # Add self to its list of children
+    else        
+      @group ||= nil
+    end
+  end
+end

data/lib/crosstab/crosstab.rb

@@ -0,0 +1,243 @@
+class Crosstab::Crosstab < Crosstab::Generic
+  # Pass in a block and we'll execute it within the context of this class.
+  # 
+  # Example:
+  # 
+  #   my_crosstab = Crosstab.new do
+  #     banner do
+  #       column "Total"
+  #       column "18-34", :b => 1
+  #       column "35-54", :b => 2
+  #     end
+  #     
+  #     table do
+  #       row "Male", :a => 1
+  #       row "Female", :a => 2
+  #     end
+  #   end
+  #   
+  def initialize(&block)
+    instance_eval(&block) if block
+  end
+  
+  
+  
+  # DSL accessor for the data_source attribute which normally contains an empty array or an array of hashes.  To install
+  # your own data, just pass in an array of hashes as the argument.
+  # 
+  # Example:
+  #    
+  #    my_crosstab = Crosstab::Crosstab.new
+  #
+  #    my_crosstab.data_source
+  #    # => []
+  #    
+  #    my_crosstab.data_source [{:a => 1, :b => 2},
+  #                             {:a => 2, :b => 2}]
+  #                             
+  #    my_crosstab.data_source
+  #    # => [{:a => 1, :b => 2},{:a => 2, :b => 2}]
+  #    
+  def data_source(value=nil)
+    if value
+      @data_source = value
+    else
+      @data_source ||= []
+    end
+  end
+  
+  # Creates a new Crosstab::Banner
+  # 
+  # Example: 
+  # 
+  #   # First let's look at the default banner with its total column:
+  #   
+  #   banner
+  #   #=> Crosstab::Banner   
+  #
+  #   #   banner.columns.first.title
+  #   #=> "Total"
+  #
+  #   # Now let's create a new banner.
+  #   banner do
+  #     column "Male", :a => 1
+  #     column "Female", :a => 2
+  #   end
+  #
+  #   banner.columns.first.title
+  #   #=> "Male"
+  #   banner.columns.last.title
+  #   #=> "Female"
+  #    
+  def banner(&block)
+    if block
+      @banner = Crosstab::Banner.new(&block)
+    else
+      @banner ||= Crosstab::Banner.new
+    end
+  end
+  
+  # Returns the array of tables for this Crosstab.
+  def tables
+    @tables ||= []  
+  end
+
+  # Creates a new Crosstab::Table and appends it to tables
+  # 
+  # Example: 
+  # 
+  #   my_crosstab = Crosstab.new
+  #   my_crosstab.tables
+  #   # => []
+  #   
+  #   my_crosstab.table do
+  #     title "Q.B Age"
+  #     row "18-34", :b => 1
+  #     row "35-54", :b => 2
+  #   end  
+  #
+  #   my_crosstab.tables
+  #   # => [Crosstab::Table]
+  #     
+  #   my_crosstab.tables.first.rows.first.title
+  #   #=> "18-34"
+  #   
+  #   my_crosstab.tables.first.rows.last.title
+  #   #=> "35-54"
+  #   
+  def table(&block)
+    tables << Crosstab::Table.new(&block)
+  end
+  
+  # Runs the calculations.  
+  # 
+  # Warning: This is a CPU-heavy method.  If you're working with a large record size, processing time can explode out of control.
+  # You can expect this routine to process 1,000,000+ transactions a second.  What's a transaction?  It's just about 1 record x 
+  # 1 row x 1 column.  
+  # 
+  # Some examples: 1 second =>         N=1,000 * 100 rows * 10 columns 
+  #                1 second =>       N=100,000 *  10 rows *  1 column
+  #                16.6 minutes => N=1,000,000 * 100 rows * 10 columns
+  # 
+  def calculate
+    # pre-calculate which interviews belong in the banner run
+    working_records = data_source.select do |i|      
+      self.qualifies? i and banner.qualifies? i
+    end
+      
+    # pre-calculate which interviews belong in each column
+    banner.columns.each do |column|
+      column.records(working_records.select { |i| column.qualifies? i })
+    end
+      
+    tables.each do |table|
+      banner.columns.each_with_index do |column, column_index|
+        # pre-calculate which interviews belong in this table
+        table_records = column.records.select do |i|              
+          table.qualifies? i
+        end
+        
+        # do the actual stub calculations          
+        table.rows.each do |row|
+          # if this row is part of a group, and the group hasn't already been calculated for this cell...
+          if row.group and row.group.cells[column_index].nil?
+            row.group.cells[column_index] = Crosstab::Cell.new
+            row.group.cells[column_index].base table_records.length
+            row.group.cells[column_index].frequency table_records.select { |i| row.group.qualifies? i }.length
+          end
+          
+          # The actual normal row calculations
+          row.cells[column_index] ||= Crosstab::Cell.new
+          row.cells[column_index].base table_records.length
+          row.cells[column_index].frequency table_records.select { |i| row.qualifies? i }.length
+        end
+      end
+    end
+  end
+  
+  def to_s
+    calculate
+    
+    widths = { :hyphenation_min => 3,
+               :row_header => 29, # Width of the title of each row
+               :row_indent => 2, # Indent 2 spaces if the row is part of a group
+               :column => 7,
+               :divider => 2 }
+    
+    letter_lookup = {}
+    (1..26).each { |x| letter_lookup[x] = (x+64).chr }
+    
+    format_strings =        { :group_headers  => " " * widths[:row_header] + " " * widths[:divider] + (banner.columns.collect { |x| x.group }.to_freq_chart.collect { |x| (x[1].nil? ? " " : "|") * (widths[:column] * x[0] + widths[:divider] * (x[0] - 1))  + " " * widths[:divider]}.join),
+                              :group_border   => " " * widths[:row_header] + " " * widths[:divider] + (banner.columns.collect { |x| x.group }.to_freq_chart.collect { |x| (x[1].nil? ? " " : "-") * (widths[:column] * x[0] + widths[:divider] * (x[0] - 1))  + " " * widths[:divider]}.join),
+                              :column_headers => " " * widths[:row_header] + " " * widths[:divider] + ("|" * widths[:column] + " " * widths[:divider]) * banner.columns.length,
+                              :column_border  => " " * widths[:row_header] + " " * widths[:divider] + ("-" * widths[:column] + " " * widths[:divider]) * banner.columns.length,
+                              :baseline       => "[" * widths[:row_header] + " " * widths[:divider] + ("]" * widths[:column] + " " * widths[:divider]) * banner.columns.length,
+                              :rows           => "[" * widths[:row_header] + " " * widths[:divider] + ("]" * widths[:column] + " " * widths[:divider]) * banner.columns.length,
+                              :indented_rows  => " " * widths[:row_indent] + "[" * (widths[:row_header] - widths[:row_indent]) + " " * widths[:divider] + ("]" * widths[:column] + " " * widths[:divider]) * banner.columns.length,
+                              :underline_row  => "_" * widths[:row_header],
+                              :line_break     => "",
+                              :page_break     => "-" * 72 }
+
+    r = Text::Reform.new
+    r.min_break = widths[:hyphenation_min]
+    
+    report_stack = []
+    tables.each_with_index do |tbl, i|
+      # Table Header
+      report_stack << "Table #{i + 1}"
+      report_stack << tbl.title.dup if tbl.title
+
+      # Group headers
+      
+      if banner.columns.any? { |x| x.group }
+        report_stack << format_strings[:group_headers]
+
+        banner.columns.each do |col|
+          if col.group
+            unless report_stack.last == col.group.title
+              report_stack << col.group.title.dup
+            end
+          end
+        end
+        
+        report_stack << format_strings[:group_border]        
+      end 
+      
+      # Column Headers
+      report_stack << format_strings[:column_headers]
+      banner.columns.each_with_index do |col, col_index|
+        report_stack << [ col.title.dup, "(#{letter_lookup[col_index + 1]})"]
+      end
+
+      report_stack << format_strings[:column_border]
+      
+      # Baseline
+      report_stack << format_strings[:baseline]
+      report_stack << "(BASE)"
+      report_stack += tbl.rows[0].cells.collect { |x| x.base }
+      report_stack << format_strings[:line_break]
+      
+      # Each row
+      tbl.rows.each do |row|
+        if row.group and not row.group.printed?
+          row.group.printed? true # Set to true so it won't be printed again
+          
+          report_stack << format_strings[:rows]
+          report_stack << [row.group.title.dup, "-" * widths[:row_header]]
+          report_stack += row.group.cells.collect { |cell| cell.result }
+          report_stack << format_strings[:line_break]
+        end
+        
+        report_stack << format_strings[row.group ? :indented_rows : :rows] # if it's part of a group then indent it.
+        report_stack << row.title.dup
+        report_stack += row.cells.collect { |cell| cell.result }
+        report_stack << format_strings[:line_break]
+      end      
+
+      report_stack << format_strings[:page_break]      
+    end
+    
+    r.format(*report_stack)
+  end
+end
+    

data/lib/crosstab/extensions.rb

@@ -0,0 +1,26 @@
+class Array
+
+  # Converts a flat list to a frequency chart.
+  # 
+  # Example:
+  #   
+  #   [nil, "a", "a", "a", "b", "b", "b", nil, "c"].to_freq_chart
+  #   # => [[1,nil],[3,"a"],[3,"b"],[1,nil],[1,"c"]]
+  #   
+  def to_freq_chart
+    # pre_state: [nil, a, a, a, b, b, b, nil, c]        
+    bland_array = self.collect { |x| [1,x] }
+        
+    # pre_state: [[1,nil],[1,a],[1,a],[1,a],[1,b],[1,b],[1,b],[1,nil],[1,c]]
+    final_array = []
+    bland_array.each do |x|
+      if final_array.length > 0 and final_array.last[1] == x[1]
+        final_array.last[0] += 1
+      else
+        final_array << x
+      end
+    end
+   
+    final_array
+  end
+end

data/lib/crosstab/generic.rb

@@ -0,0 +1,83 @@
+class Crosstab::Generic
+  # DSL accessor for the title attribute
+  # 
+  # Example:
+  #    
+  #    title
+  #    # => nil
+  #    
+  #    title "Q.A Gender:"
+  #    # => "Q.A Gender:"
+  #    
+  #    title
+  #    # => "Q.A Gender:"
+  #    
+  def title(value=nil)
+    if value
+      @title = value
+    else
+      @title ||= nil
+    end
+  end
+  
+  # Redefines the qualifies? test for this object
+  # 
+  # Example:
+  # 
+  #   # By default, qualifies? always returns true.
+  #
+  #   qualifies? :a => 1
+  #   # => true
+  # 
+  #   # But if we set it...
+  #   qualification :a => 2
+  #   
+  #   # Then qualifies? returns false unless :a == 1
+  #   qualifies? :a => 1
+  #   # => false
+  #   
+  #   qualifies? :a => 2
+  #   # => true
+  #   
+  def qualification(hash)
+    @key, @value = *hash.to_a.first
+    
+    # Performance hack: improves overall benchmark from 1.37 to 0.96 by rendering the key and value inline.
+    #                   Don't use any weird keys or values.  Stick to standard ruby library ones unless you know what you're doing.
+    instance_eval %{
+      def qualifies?(i)
+        i[#{@key.inspect}] == #{@value.inspect}
+      end
+    }
+  end
+
+  # Returns true when a record passes the qualification filter.  
+  # This will always return true until set by qualification.
+  def qualifies?(record)
+    true
+  end
+
+  # DSL accessor for the printed flag.  Returns true if this object hasn't been printed to the screen yet.  
+  # It's just a useful flag when building a report (e.g., you can set printed? to true everytime you touch
+  # an object, and then you'll know if you've printed a group already.)
+  # 
+  # Example:
+  #    
+  #    printed?
+  #    # => false
+  #    
+  #    printed? true
+  #    # => true
+  #    
+  #    printed?
+  #    # => true
+  #        
+  
+  def printed?(value=nil)
+    if value
+      @printed = value
+    else
+      @printed ||= false
+    end
+  end 
+end

data/lib/crosstab/group.rb

@@ -0,0 +1,28 @@
+class Crosstab::Group < Crosstab::Row
+
+  # attr_reader for the children attribute which should contain an empty array, or a list of rows or columns
+  # 
+  # Example: 
+  # 
+  #   children
+  #   #=> []
+  #
+  #   children [ Crosstab::Row("Male", :a => 1) ]
+  # 
+  #   children.first.title
+  #   #=> "Male"
+  #   
+  def children(value=nil)
+    if value
+      @children = value
+    else
+      @children ||= []
+    end
+  end
+  
+  # Returns true when a record passes a qualification filter belonging to any child of the group.  This is how
+  # subtotals work.
+  def qualifies?(record)
+    children.any? { |child| child.qualifies? record }
+  end
+end

data/lib/crosstab/row.rb

@@ -0,0 +1,65 @@
+class Crosstab::Row < Crosstab::Generic
+  def initialize(label=nil, qual=nil)    
+    title label if label
+    qualification qual if qual
+  end
+  
+  # attr_reader for the cells attribute which should contain an empty array, or -- if calculate was called on
+  # the crosstab -- this will contain an array of cells, one for each column in the banner.
+  # 
+  # Example:
+  # 
+  #   my_crosstab = Crosstab::Crosstab.new do
+  #     data_source [{:a => 1}, {:a => 2}]
+  #     
+  #     table do
+  #       title "Q.A Gender:"
+  #       row "Male", :a => 1
+  #       row "Female", :a => 2
+  #     end
+  #   end
+  #   
+  #   my_crosstab.calculate
+  #   
+  #   my_crosstab.tables[0].rows[0].title
+  #   # => "Male"
+  #   
+  #   my_crosstab.tables[0].rows[0].cells[0].frequency
+  #   # => 1
+  #   
+  #   my_crosstab.tables[0].rows[0].cells[0].base
+  #   # => 2
+  #   
+  #   my_crosstab.tables[0].rows[0].cells[0].percentage
+  #   # => 0.5
+  #   
+  def cells(value=nil)
+    if value
+      @cells = value
+    else
+      @cells ||= []
+    end
+  end
+  
+  # DSL accessor for the group attribute
+  # 
+  # Example:
+  #    
+  #    group
+  #    # => nil
+  #    
+  #    group Crosstab::Group.new("Gender")
+  #    # => Crosstab::Group...
+  #    
+  #    group.title
+  #    # => "Gender"
+  #    
+  def group(g=nil)
+    if g
+      @group = g
+      g.children << self # Add self to its list of children
+    else        
+      @group ||= nil
+    end
+  end
+end