= S3Report =
[[TOC]]

S3Report is a REST method handler for data analysis.

== Functionality ==

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

== Dependencies ==

S3Report 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

[=#url_methods]
== URL Methods ==

S3Report responds to the {{{report}}} 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)

S3Report 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/report?rows=country&cols=sector_id&fact=name
  - http://localhost:8000/eden/pr/person/report?rows=age_group&cols=gender&fact=id&aggregate=count

  $-notation for references:

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

  reduced parameter list:

  - http://localhost:8000/eden/org/office/report?rows=type&aggregate=count
  - http://localhost:8000/eden/org/organisation/report?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` property 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]).

The `search` property is a list of S3Search widgets that will allow the report to be filtered. If no `search` property is specified, no filter form will be available.

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
	),
	search=[
		S3SearchOptionsWidget(
			name="project_id",
			label = T("Project"),
			field = "project_id",
		),
	],
)
}}}

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)