Class Ruport::Data::Grouping
In: lib/ruport/data/grouping.rb
Parent: Object

Overview

This class implements a grouping data structure for Ruport. A grouping is a collection of groups. It allows you to group the data in a table by one or more columns that you specify.

The data for a grouping is a hash of groups, keyed on each unique data point from the grouping column.

Methods

/   <<   []   append   each   method_missing   new   sigma   sort_grouping_by   sort_grouping_by!   subgrouping   sum   summary   to_s  

Included Modules

Enumerable Ruport::Renderer::Hooks

Attributes

data  [RW]  The grouping‘s data
grouped_by  [R]  The name of the column used to group the data

Public Class methods

Creates a new Grouping based on the supplied options.

Valid options:

:by:A column name or array of column names that the data will be grouped on.
:order:Determines the iteration and presentation order of a Grouping object. Set to :name to order by Group names. You can also provide a lambda which will be passed Group objects, and use semantics similar to Enumerable#group_by

Examples:

  table = [[1,2,3],[4,5,6],[1,1,2]].to_table(%w[a b c])

  # unordered
  grouping = Grouping.new(table, :by => "a")

  # ordered by group name
  grouping = Grouping.new(table, :by => "a", :order => :name)

  # ordered by group size
  grouping = Grouping.new(table, :by => "a",
                                 :order => lambda { |g| g.size } )

Public Instance methods

/(name)

Alias for subgrouping

Used to add extra data to the Grouping. group should be a Group.

Example:

  table = [[1,2,3],[4,5,6]].to_table(%w[a b c])

  grouping = Grouping.new(table, :by => "a")

  group = Group.new :name => 7,
                    :data => [[8,9]],
                    :column_names => %w[b c]

  grouping << group

Allows Hash-like indexing of the grouping data.

Examples:

  my_grouping["foo"]
append(group)

Alias for #<<

Iterates through the Grouping, yielding each group name and Group object

Provides a shortcut for the as() method by converting a call to to_format_name into a call to as(:format_name).

Calculates sums. If a column name or index is given, it will try to convert each element of that column to an integer or float and add them together. The sum is calculated across all groups in the grouping.

If a block is given, it yields each Record in each Group so that you can do your own calculation.

Example:

  table = [[1,2,3],[3,4,5],[5,6,7]].to_table(%w[col1 col2 col3])
  grouping = Grouping(table, :by => "col1")
  grouping.sigma("col2") #=> 12
  grouping.sigma(0)      #=> 12
  grouping.sigma { |r| r.col2 + r.col3 } #=> 27
  grouping.sigma { |r| r.col2 + 1 } #=> 15

Returns a new grouping with the specified sort order. You can sort by Group name or an arbitrary block

  by_name = grouping.sort_grouping_by(:name)
  by_size = grouping.sort_grouping_by { |g| g.size }

Applies the specified sort order to an existing Grouping object.

  grouping.sort_grouping_by!(:name)
  grouping.sort_grouping_by! { |g| g.size }

Provides access to the subgroups of a particular group in the Grouping. Supply the name of a group and it returns a Grouping created from the subgroups of the group.

sum(column=nil)

Alias for sigma

Useful for creating basic summaries from Grouping objects. Takes a field to summarize on, and then for each group, runs the specified procs and returns the results as a Table.

The following example would show for each date group, the sum for the attributes or methods :opened and :closed and order them by the :order array.

If :order is not specified, you cannot depend on predictable column order.

  grouping.summary :date,
    :opened => lambda { |g| g.sigma(:opened) },
    :closed => lambda { |g| g.sigma(:closed) },
    :order => [:date,:opened,:closed]

Uses Ruport‘s built-in text formatter to render this Grouping

Example:

  table = [[1,2,3],[4,5,6]].to_table(%w[a b c])

  grouping = Grouping.new(table, :by => "a")

  puts grouping.to_s

[Validate]