[[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:

  - scipy
  - numpy
  - matplotlib

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

== 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

== Further Development ==

The following enhancements are currently under development:

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