= Timeplot Reports =
[[TOC]]

Timeplots report the development of aggregated process attributes over time, e.g.:

  - the number of residents in a refugee camp
  - the number of projects at a location
  - the total amount of funding for a project
  - the stock level of certain items in a warehouse

These reports are represented as interactive graphs over a time axis.

  '''Note:''' ''Timeplot reports should not be confused with timeline reports (which are used to show individual items along a time axis).''

== Data Model ==

In each data item we have the following fields:

  - a numeric value (for counting, this value is generally 1 for each individual record)
  - a start date (can be None if the item has always existed)
  - an end date (optional, can be None if the item still exists beyond "now")
== Functional Requirements ==

=== Framework ===

Timeplots are meant to become a generic, configurable reporting method (similar to S3Report2), which responds to the /timeplot method. 

The method shall support both resource default options, URL options as well as interactive options selection (via Ajax-update).

Timeplots shall support filtering, and (optionally) integrate a filter form.

Timeplots shall support integration into S3Summary (widget-method) and S3Profile.

Ideally, timeplots could also be exported (XLS, PDF, PNG).

=== Aggregation methods ===

Timeplot reports shall support the following aggregation methods:

  - count (number of items)
  - sum (total value)
  - avg (average value)
  - min (minimum value)
  - max (maximum value)

=== Multiple layers ===

Timeplots shall be able to report multiple value dimensions in the same graph. These dimensions can be reported as overlays (for comparison) or stacked.

=== Baseline Aggregation ===

It shall be possible to specify a time interval for the analysis.

To be able to specify a start date/time, we must calculate baselines, i.e. the aggregated attributes at the start of the analysis interval.

=== Interval Aggregation ===

It shall be possible to specify the resolution for the aggregation. This can be:

  - hourly
  - daily
  - weekly
  - monthly
  - yearly
  - continuous (=report based on item timestamps rather than fixed intervals)
  - automatic (= automatically adjust resolution after the total length of the analysis interval)

=== Graph Exploration ===

The graphs shall provide interactive methods to explore each data point. This includes on-hover tooltips to display point data as well as options to use a data point to drill down into individual items.

It shall be possible to switch between different graph types (lines or bars).

== Implementation ==

Timeplots have been implemented in modules/s3/s3timeplot.py, the !JavaScript can be found in static/scripts/S3/s3.ui.timeplot.js.

This uses the D3 library to generate the graphs (via NVD3).

----
[wiki:BluePrint]