Skip to content

Graphs

Jump to bottom Edit New page
Jenny Schweers edited this page Mar 16, 2020 · 33 revisions

Graphs

In a suite, an individual detail field may be in the form of a graph.

Overarching Placement

Graphs are defined in suite.xml, inside <detail> blocks, inside <template> blocks, similarly to text templates. To display a graph in case selection or details, add a new <field> to the appropriate <detail> block. The field's header text will be displayed as the graph's title.

Note that the template's "form" attribute must be set to "graph," and the graph must have a type. Supported types:

  • "xy" may be configured to display as a line or scatter chart
  • "time" for xy charts where the x axis uses date or datetime values
  • "bubble" for bubble charts
  • "bar" for bar charts. Bar charts expect the x function to return a string, which will be used to label the bar. While bar charts support multiple series, each series should use the same nodeset and x function.
<detail id="m0_case_long">
  <title>
    <text>
      <locale id="case_lists.m0.title"/>
    </text>
  </title>
  <field>
    <header>
      <text>
        <locale id="case_lists.m0.header"/>
      </text>
    </header>
    <template form="graph">
      <graph type="xy">
        <!-- see below -->
      </graph>
    </template>
  </field>
</detail>

Graph

A graph should contain a element for every series to be drawn.

It may contain a configuration element to define the graph's look and feel.

It may contain any number of annotations, which are strings to be drawn at specific points on the graph.

<graph>
  <series type="line">
    <!-- May contain 0..* series. See below. -->
  </series>
  <configuration>
    <!-- May contain a single configuration. See below. -->
  </configuration>
  <annotation>
    <!-- May contain 0..* annotations. See below. -->
  </annotation>
</graph>

Series

A series is primarily defined by a nodeset, x function, and y function. The x and y functions will be applied against each node in the nodeset to generate points on the graph. Nodesets are likely either case data or fixture data.

Any series contained in a bubble graph must also have a radius function, which will determine the size of each bubble. Usually, the bubble graph should also specify a max-radius for each series (see below).

A series may contain a <configuration> block to customize its look and feel.

<series nodeset="instance('casedb')/casedb/case[index/parent=current()/@case_id]">
  <configuration>
    <!-- see below -->
  </configuration>
  <x function="hours" />
  <y function="contraction_frequency" />
  <radius function="contraction_length" />
</series>

Configuration (series)

The configuration block consists of a set of properties. Each is a text element, as used elsewhere in the suite, so it can be localized text, an XPath expression, etc. An id identifies each property.

Supported properties:

  • bar-color: Bar graphs only. XPath expression. This expression will be applied to each bar in turn and should evaluate to a #aarrggbb or #rrggbb string. Can be used to color bars based on their values, e.g., "if(value > 100, '#990000', '#009900')". This will override the line-color setting. However, line-color is still used to set the color that appears in the legend, if a legend is shown.
  • fill-below: If set, area below this line will be filled with the given color, which is expected to be a #aarrggbb or #rrggbb string. Any series with fill-below set will be drawn stacked (as in stacked area graphs). They will be stacked in the order they are defined, with the first-defined graph drawn on the bottom. (On the alert/action graph at the top of the page, this is how the red and yellow areas are created.)
  • is-data: True if the series should be represented in the legend and tooltip. Defaults to true.
  • line-color: Color of line (or bars, or bubbles). Defaults to black. Note that setting this to #00xxxxxx will make the line disappear altogether.
  • max-radius: Bubble graphs only. Set the maximum radius value. Useful when looking at multiple series or graphs. Without this set, the graph will calculate the radius scale for each series independently: that is, suppose you have two series on a bubble graph, A and B, which can both contain values from 1 to 5. Without max-radius set, the graph will decide how to scale the bubbles - that is, how many pixels wide to make them - independently. So if a particular graph only has data between 1 and 3 series A, but 1 and 5 in series B, the graph might decide that a 3 bubble is 50 pixels wide for series A, but only 30 pixels wide in series B, resulting in a misleading graph. Instead, if max-radius is set to 5 for both series, the graph will appropriately size the bubbles.
  • name: If using a legend, how to refer to this series.
  • point-style: What shape to make the series' points. One of "none", "circle", "cross", "diamond", "triangle-up", "triangle-down". Defaults to "circle." (Compare the two lines on the alert/action graph at the top of the page.)
  • secondary-y: XY graphs only. If true, plot this data on a secondary y axis, which may have its own min, max, and labels, and will be drawn on the right side of the graph.
  • var-*: See graph configuration below. These variables will be available only to this series.
  • x-name: Label to display for x-values in tooltip. Defaults to the XPath expression used to define the series' x values.
<configuration>
  <text id="fill-below">
    <value>#ffdddd00</value>
  </text>
  <text id="line-color">
    <value>#00000000</value>
  </text>
  <text id="point-style">
    <value>none</value>
  </text>
</configuration>

Configuration (graph)

Graph configuration elements have the same format as series configuration elements, just with different available properties. The properties beginning with "secondary-y" refer to a second y axis, which may have its own min, max, and labels, and which will be drawn on the right side of the graph.

Supported properties:

  • Axis min and max
    • x-min (Note that for xy or bubble graphs, this should be a number, while for time graphs, it should be a string like "2014-12-31" or "2014-12-31 14:15:16")
    • x-max (same formatting as x-max)
    • y-min
    • y-max
    • secondary-y-min
    • secondary-y-max
  • Axis titles
    • x-title
    • y-title
    • secondary-y-title
  • Axis labels: default is to let the graphing code invent reasonable labels based on the min and max.
    • x-labels
    • y-labels
    • secondary-y-labels
    • Each of these accepts three types of values: a single number, a JSON array, or a JSON object:
      • 3
        • This will draw approximately 3 evenly-spaced labels on the axis. This is the most fragile way to define labels, as it's difficult to exactly predict where the labels will be drawn. The two methods below are preferable.
      • [1, 3, 5]
        • This will draw the labels "1", "3", and "5" at those points on the y axis.
      • { "0": "freezing", "100": "boiling" }
        • This will draw the text "freezing" and "boiling" at the 0 and 100 mark on the y axis, respectively.
    • Configuring labels can get complicated quickly. Suggestions:
      • Test out your JSON in an online validator before entering it in CommCare.
      • You can use XPath calculations for labels, but remember that ultimately your calculation needs to produce a string value that is a legal JSON expression. This leads to calculations that are heavy on concat. For example:
      • Imagine you wanted to set three labels: 0, 10, and a random number between 0 and 10.
      • You'd want to use the array format, ultimately generating something like [0, 3.432987, 10] for the graph, but using the random() function to generate the middle number.
      • To do this, you can use concat and random to generate the string: concat('[0, ', random() * 10, ', 10]')
    • x-labels-time-format: Format for displaying time-based labels. This must be a string recognizable to D3 (see https://github.com/mbostock/d3/wiki/Time-Formatting). Defaults to "%Y-%m-%d." Relevant only for time graphs, and only if x-labels is a single number (or x-labels is unspecified).
  • show-axes: defaults to true
  • show-data-labels: defaults to false. If true, each point or bar in each data series (see is-data) will have its value displayed in text right above it.
  • show-grid: defaults to true
  • show-legend: defaults to false
  • var-foo: You can define suite variables, as described in the suite definition. A key like "var-foo" will define the variable $foo, which will then be available within the graph. Note that variables may not depend on each other, but standard configuration elements may depend on variables.
  • Bar graph configuration
    • bar-orientation: "horizontal" or "vertical", defaults to "horizontal"
    • stack: If true, multiple series will be displayed as stacked bars, rather than bars next to each other. Defaults to false.

Annotations

Annotations are text snippets that are drawn at user-specified points on the graph. An annotation requires an x coordinate, y coordinate, and value. These use the same <text> element as elsewhere in the suite, so they support localized text, XPath expressions, etc.

<annotation>
  <x>
    <text>
      <value>5</value>
    </text>
  </x>
  <y>
    <text>
      <value>7</value>
    </text>
  </y>
  <text>
    <value>Alert</value>
  </text>
</annotation>
Add a custom footer
Add a custom sidebar
Clone this wiki locally