[[TOC]]

= S3Cube =

S3Cube is a REST method handler for data analysis.

== Functionality ==

S3Cube can generate contingency tables (a.k.a. pivot tables) from S3Resources.

== Dependencies ==

S3Cube uses [http://code.google.com/p/pyvttbl pyvttbl] to generate contingency tables. A modified version of {{{pyvttbl}}} is integrated into the S3 framework.

Pyvttbl requires the following Python modules:

  - numpy
  - matplotlib

Python 2.7 is recommended for S3Cube, however it would work with Python 2.6.

[=#url_methods]
== URL Methods ==

S3Cube responds to the {{{analyze}}} URL method, for ''all'' resources (generic method).

The following parameters are accepted:

  ||'''Parameter'''||'''Explanation'''||'''required?'''||
  ||rows||the name of the field to be used for the table rows||yes||
  ||cols||the name of the field to be used for the table columns||no (if no cols are specified, all instance values appear in 1 column)||
  ||fact||the name of the field to be used for the instance values||no (falls back to "name" if present, otherwise to "id")||
  ||aggregate||the aggregation function||no (default: list)||

rows, cols and fact support the same options as list_fields:

  - fields in the table
  - virtual fields in the table
  - fields/virtual fields in tables linked by foreign keys ($-notation)

S3Cube supports a number of aggregation functions. The following functions have been tested so far:

  ||'''Function'''||'''Explanation'''||
  ||list||a comma-separated list of all instance values||
  ||count||the number of instance values||
  ||sum||the sum of all instance values||
  ||avg||the average (mean) of all instance values||

== Examples ==

  - http://localhost:8000/eden/org/organisation/analyze?rows=country&cols=sector_id&fact=name
  - http://localhost:8000/eden/pr/person/analyze?rows=age_group&cols=gender&fact=id&aggregate=count

  $-notation for references:

  - http://localhost:8000/eden/org/office/analyze?rows=location_id$parent&cols=type&fact=name

  reduced parameter list:

  - http://localhost:8000/eden/org/office/analyze?rows=type&aggregate=count
  - http://localhost:8000/eden/org/organisation/analyze?rows=sector_id

== Report Options ==

Table configurations can contain a `report_options` item, which is a Storage object. This object is used to configure reports and report options form.

The `rows`, `cols`, `facts` and `aggregate` items are lists of available values for the user to select from.

The `defaults` item is a Storage object that contains the default values for the report. It can contain a value for `rows`, `cols`, `fact`, `aggregate` and `totals` (as described in [#URLMethods URL Methods]).

Here is an example of a `report_options` item:
{{{#!python
report_options=Storage(
	rows=report_fields,
	cols=report_fields,
	facts=report_fields,
	defaults=Storage(
		rows="project_id",
		cols="name",
		fact="time_actual",
		aggregate="sum",
		totals=True
	)
}}}

All items in `report_options` and `defaults` are optional.

== Further Development ==

The following enhancements are currently under development:

  - Support for JSON, CSV and XLS exports
  - Support for client-side graphs representation (via JSON)