Wiki Display Components

Section 5.3: Wiki Display Components

RAMADDA provides a number of information and data display components in the wiki facility. There are a number of examples available. An easy way to figure out what is going on is to the the wiki text of working examples. The wikitext used for any RAMADDA entry can be viewed with the Menu->View->Information page - example.

5.3.0 The Basics

The charts and information displays follow the RAMADDA wiki tag format:

{{display_<display type>  <name=value pairs>}}

Each of these tags support the following attributes:

layoutHere="true"  
showMenu="true"  
showTitle="true"
title="Title to display"

If layoutHere is set to false then the component is laid out by the container group (below). Otherwise it is displayed in place.

Some of the displays use a color table:

colorTable="rainbow|grayscale|inversegrayscale|blues|blue_green_red|white_blue|blue_red"

The full set of color tables can be viewed at here.

5.3.1 Specifying Fields

Most of these displays are based on point data in RAMADDA. The point data model is based on a series of records (or rows) that are made up of a set of fields (or columns). Each field has a certain type - double, integer, string, date. Many of the displays below use a fields attribute to specify the fields that are displayed. These are either the field ids of the point data or a 1-based index into the field list.

fields="active_voters,total_ballots"
Or:
fields="1,#2,#3"

The field ids for a point data entry can be viewed with the Metadata view, e.g. - (example).

{{display_linechart fields="#5,#6,#7,#8,#9,#10" }}

5.3.2 Filtering Data

A display can present a set of widgets that allow the user to filter the data being shown. For example, in the image below (See here ) the data has a set of fields - elev, elev_gain, distance, range and class.

Image 1: Filtering Data

Below is the wiki text that creates the above display. The map display defines which fields should be used with the filterFields="..." attribute. The ranking display specifies the same set of filter fields but also has a hideFilterWidget=true which specifies to actually not show the widgets. The filter values the user enters in the map display are then applied to the ranking display.

+row
+col-3
{{display  type="ranking"  
...
filterFields="elev,elev_gain,distance,range,class" hideFilterWidget=true
 }} 
 -col
 +col-9
{{display  type="map"  
...
filterFields="elev,elev_gain,distance,class,range"
}} 
 -col
 -row

Filter attributes:

filterFields="field1,field2"
The fields to filter on
hideFilterWidget=true
Don't show the filter widgets.
<field_name>.filterValue="some value"
Specify an initial filter value
<field_name>.includeAll="false"
For enumerated values a menu of items is shown. To not have the "All" value add a attribute.
<field_name>.filterMultiple="true"
Support multiple values to filter on
<field_name>.filterMultipleSize="5"
How big a selection menu to show
<field_name>.filterValues="value1,value2,.."
Specify values to use in the filter menu instead of the values in the data
<field_name>.filterValueMin="min value", <field_name>.filterValueMax="max value"
Use these to specify initial values for numeric fields.
<field_name>.filterLabel="some label"
Specify an alternative label to display with the filter widget
<field_name>.filterPrefix="some prefix", <field_name>.filterSuffix="some suffix"
Specify extra text to wrap the filter value

5.3.3 Converting Data

convertData="command1;command2;...;"

Where commands can be:
  derived(field=field_id, function=some_expression)
e.g.:
  derived(field=poptimes10, function=population*10)

  rotateData(includeFields=true,includeDate=true,flipColumns=true)
  addPercentIncrease(replaceValues=false)

5.3.4 Subsetting Data

You can specify various filters applied to the data

By date:
startDate="yyyy-MM-dd"
endDate="yyyy-MM-dd"

By value:
dataFilters="command(field=<field id>,value=<value>,enabled=<value>,label=<label>...


Where "command" can be one of:
match - string match
notmatch - string not match
lessthan - <=
greaterthan - >=
equals
notequals


If the label is specified then a selector checkbox will be shown to turn on/off this filter

You can also sample the data with:

stride=1 -  take every other point
maxDisplayedPoints= - if set, then set the stride so we at most have  maxDisplayedPoints points

You can bin the data based on dates with:

binDate=day|week|month|year
binType=total|count|average

Only show unique rows with:

uniqueField=<field id>

5.3.5 Color

RAMADDA provides a large number of built-in color tables. When editing the wiki text if you right-lick inside of a {{display ...}} tag a context menu will be shown that will list the available color tables. Colors are defined and can also be modified the following ways.

colorTable="some color table name" - specify the color table

colorTable="colors:red,green,blue,...."   - explicit list of colors

colorTable.<field name> ="some color table"  - specify a color table for one of the "color by" fields

colorTableInverse="true"   -reverse the colors

colorTableAlpha="0.0 - 1.0" - specify a transparency value

colorBy=<field name> - specify a data field to color by

colorByFields=<field1,field2,...,fieldN> - specify a number of fields to allow the user to choose how to color

5.3.6 Display Groups

There is a group tag that can manage a number of children displays. The general use is of the form below where displays 1-3 are part of group 1 and displays 4,5 are part of group 2. The group allows for different displays to communicate with each other (e.g., creating a new chart, map click, animation, etc), the inheritance of certain attributes (e.g., showMenu, showTitle) and the layout of the children displays. If there is a wiki page that does not have a group but only one or more display tags then a group will be added automatically.

{{group group 1 ...}}
{{display display 1}}
{{display display 2}}
{{display display 3}}

{{group group 2...}}
{{display display 4}}
{{display display 5}}

If showMenu is set to true for a group then the below menu is displayed. This supports the interactive creation of new charts and displays. The layout of these displays can be changed interactively, their state can be changed and they can be deleted.

Image 2: Group menu

If the user is logged in then the set of dynamically created displays can be saved (e.g., as a wiki page) through the group menu as seen below:

Image 3: File save menu

Display Layout

Each child display may be located in a fixed location (using layoutHere=false) in the web page or the group can manage the layout of the children displays. Different layouts can be specified with the layoutType attribute. The available layouts are:

layoutType=tabs
layoutType=table
layoutType=columns
layoutType=rows

Using the table layout the number of columns is specified with the layoutColumns attribute. For the columns and rows layout type each child display can specify the column number of row number it should be placed in. For example, for the rows layout if you had:

{{group layoutType="rows"}}
{{display display1  row="1"}}
{{display display2  row="1"}}
{{display display3  row="1"}}
{{display display4  row="2"}}
{{display display5  row="2"}}
{{display display6  row="3"}}

Would result in (without the border):

display1

display2

display3

display4

display5

display6

The divid attribute allows you to specify a div tag that is in the wiki page as the location for the group and the displays to place themselves in. For example, below is the (abbreviated) wiki text used to create this page on ramadda.org. We want to have a fixed layout where the entry list is on the left and the map is on the right. Any charts or other display components that are interactively created by the user are managed by the group and layed out below the list and map. To do this we define a regular html table layout that contains a couple of div tags - one for the list and one for the map. We set the IDs of the div tags and then reference those IDs in the display wiki tags below. Likewise, the group has a divid=maindiv which corresponds to the div at the bottom of the page.

<table width=100% border=0 cellpadding=10>
<tr valign=top>
<td width=50%><div id="listdiv"></div></td>
<td width=50%><div id="mapdiv"></div></td>
</table>

<div id=maindiv></div>
{<noop>{group  layoutType="table"  layoutColumns="1" divid="maindiv"}}
{<noop>{display_entrylist   divid="listdiv" }}
{<noop>{display_map  layoutHere="true" height="250" divid="mapdiv"}}

5.3.7 Displaying Multiple Entries

When you have multiple entries you can create a display (e.g., a time series) and allow the user to select which entry to display. Here is an example that shows a time series plot of one of a set of data files:

Below is the relevant wiki text for the above display. You can also view the full wiki text here. All that is needed is to add a changeEntries=true attribute to the group tag. An optional changeEntriesLabel can be specified to provide a context specific label. The firstEntry attribute is an optional way of specifying which entry should be shown as the first entry. For the actual displays you should specify an entry that is initially used as well.

{{group  changeEntries=true changeEntriesLabel="Select Region" 
firstEntry="93198426-f87d-40e6-b206-43b25ad1d4fa"  
}}

{{display_fieldslist width=150px
entry=93198426-f87d-40e6-b206-43b25ad1d4fa
fields="#41,#42,#43,#44,#45,#46,#47,#48,#49,#50"
...
}}

{{display_linechart
entry=93198426-f87d-40e6-b206-43b25ad1d4fa
fields="#41,#42,#43,#44,#45,#46,#47,#48,#49,#50"
...
}}

The above lists the entries in a menu. Alternatively you can display the entries in a map or in a timeline.

5.3.8 The Displays

Search form

Supports an embedded and configurable search form. New displays (e.g., line chart) based on the result entries can be created.

{{display type="entrylist" width="800"  
height="400"  
orientation="vertical|horizontal"  
showForm="true|false - is form shown"
formOpen="true|false - is form open"
showSearchSettings="true|false"
showType="true|false - show the type selector menu" 
types="comma separated list of entry types to show"
doSearch="true|false - perform the search when the page is first displayed"
showToggle="true|false - show the form toggle"
showText="true|false - show the search text input"
showArea="true|false - show the map selector"
showDate="true|false - show the data selector"
showMetadata="true|false - show the metadata search fields"
metadataTypes="comma separated list of metadata types to show"
formWidth="width of the search form"
entriesWidth="width of the results list"
provider="google,arxiv,wolfram,..."}}

Image 4: Search form

The entries displayed in the results list can be interactively displayed. The provider attribute allows you to specify alternative search providers. The list of available search providers can be viewed here.

The metadataTypes attribute allows you to specify what metadata to show. The list of available metadata types can be viewed here.

In the search results list new displays can be created through the pull down menu:

Entry Grid

The entrygrid display shows a set of entries based on their date.

{{display type="entrygrid" showIcon="true"  showName="true"  scaleWidth="true"  scaleHeight="false"  
#xAxisAscending="true"  
#xAxisScale="true"  
#yAxisAscending="true"  
#yAxisScale="true"  
#urlTemplate="{url}|{entryid}|{resource}"  
#height="400"  #width="100%"  
#entries=""}}

Image 6: Entry Grid

Animation

Controls time or index based animation. Other charts will highlight the record of the current time.

{{display type="animation"}}

Image 7: Animation

Map

A map that shows georeferenced point data. This can be integrated with other displays, e.g., clicking on a point will highlight that location in a line chart.

If a Geojson or Kml layer is specified then the layer is displayed instead of the points. The location of each point is used to find a containing map feature. That map feature is then colored as defined below.
pruneFeatures. If set to true than any map feature that does not have a corresponding point will not be shown. r
The colorBy attribute specifies the field that is used to color the points or the map segments. The colorTable attribute specifies a color table to use and the colorByMin and colorByMax attributes are option and are used to define a color range.
The centerOnFilterChange will cause the map to recenter when the data is subset from the selection filters.
The displayDiv, when specified, is the id of a div tag that the map will display the details of a point or map segment as the user mouses over it. The [ug::attr {displayDiv="mapDisplay${entryid}"}] macro allows one to specify a unique div id for pages that may have multiple map displays. The div looks like: [wiki::text { <div id="mapDisplay{{entryid}}" style="max-height:500px;"></div> }] There is a full example shown below.

{{display type="map" width="100%"  height="400"
geojsonLayer="entry id of a geojson file" 
geojsonLayerName="Layer name"
kmlLayer="entry id of a kml file" 
kmlLayerName="Layer name"
pruneFeatures="true" 
colorBy="total_ballots"
colorTable="inversegrayscale"
colorByMin="min value"
colorByMax="max value"
displayDiv="mapDisplay${entryid}"}}

Example

Image 8: Map

Image 9: Chloropleth Map

This is the wiki text used in the above example:

 
:heading Map
+row
+col-md-6
{{display_map column="1"  width="-100" height="500"   includeData="false"   showTitle="false" 
title="Colored by total ballots" 
geojsonLayer="7c8f5e25-e569-4ca9-b389-5bb03cdb138b" 
geojsonLayerName="Precincts"
displayAsMap="true"
pruneFeatures="true"
colorBy="total_ballots"
colorBar="inversegrayscale"
displayDiv="mapDisplay${entryid}"
}}
-col
+col-6


:heading Map Details

-col
-row

Map Animation:
The map display can be configured to provide a time-based animation of the points with the following attributes.

doAnimation="true" - enable animation
animationShowSlider="true" - show the slider
animationDateFormat="yyyyMMdd" or "yyyy" - default is the fully formatted date
animationMode="cumulative" or "sliding" - how the time window is moved
animationSteps="60"   - how many steps
animationWindow="year" or "month" or "day" or "hour" or "minute" or "second"  - override the animationSteps
animationSpeed="250" - time in milliseconds between each step

Map Labels:
You can display text labels at each point with the following attributes:

labelTemplate="text template with ${field id} macros. Use _nl_ for new lines"
labelFontColor="#000"
labelFontSize="12px"
labelFontFamily="'Open Sans', Helvetica Neue, Arial, Helvetica, sans-serif"
labelFontWeight="plain"
labelAlign="lb"  //See http://dev.openlayers.org/docs/files/OpenLayers/Feature/Vector-js.html
align is of the form "hv" where h is "l|c|r" (left, center, right)  and v is "t|n|b" (top,middle,bottom)
labelXOffset="0"
labelYOffset="0"
labelOutlineColor="#fff")
labelOutlineWidth="0"

Map Sizes

//Define the point radius
radius="4" 
//define a field to size by
sizeBy="<field>"
//use a log scale
sizeByLog=true
//Size min/max
sizeByRadiusMin=1
sizeByRadiusMax=15

Map Colors

//Field to color by
colorBy="<field>cnt"
//Color table
colorTable="blue_green_red"
//Or colors
colors="color1,color2,...,colorN"
//Use a log scale
colorByLog=true
//Set the stroke color
strokeColor="#fff0"
//Map string values to colors
colorByMap="value:color,...,value:color"

//These are used in conjunction with a vector map layer
//If true then count the points within each map feature and use that as the color by value
colorByCount=true
//Suffix to show on map click
doCountLabel="clubs"

//If true then prune out the features that don't have any data points in them
pruneFeatures="true"

Map Shapes
Define different shapes to display in the map.

//Define a different icon to use 
pointIcon="/repository/dutchbrothers.png" 
//Define a different shape
shape="star|cross|x|square|triangle|circle|lightning|rectangle|church"
//Map values to shape
shapeBy=<field>
shapeByMap="value1:shape1,...,valueN:shapeN"

Line chart

Displays time series or indexed point data. The vAxisMinValue and vAxisMaxValue are used as the range instead of the min/max from the data.
If padRight is set to true than the chart is padded on the right with the same space as what is used for the second axis legend. This allows for two or more charts to be aligned that have one or more fields being displayed.

{{display type="linechart" width="800"  height="400"  
fields=""       
vAxisMinValue="0" vAxisMaxValue="1.0" padRight="true"}}

Image 10: Line chart

You can set various colors of the chart with the following properties:

chart.fill="color or 'transparent'"
chart.stroke="stroke color"
chart.strokeWidth="width"

chartArea.fill="color or 'transparent'"
chartArea.stroke="stroke color"
chartArea.strokeWidth="width"

hAxis.gridlines.color="color"
vAxis.gridlines.color="color"

Annotating Charts
Annotations for a chart can be specified in two ways. The first is to specify one or more data fields to create the annotation from:

  annotationFields="field1,field2,..."
  annotationLabelField="field" //optional for the label

The second way is to specify the annotations using an annotations attribute:

annotations="
<,index1>,label1,description1;
<,index2>,label2,description2;
...
"

Where <index> is either a date or a numeric index, e.g;

 annotations="
2,A,annotation 1;
2016-06-24,B,annotation 2;
2016-06-24,C,<,h1>,annotation 3</h1>
2017-01-02,D,annotation 4
"

Bar chart

{{display type="barchart" fields=""  padRight="true"}}

Image 11: Bar chart

Stacked bar chart

{{display type="barstack" fields=""}}

Area chart

{{display type="areachart" width="800"  height="400"  
fields=""  
vAxisMinValue="0" vAxisMaxValue="1.0" 
padRight="true"
isStacked="true"}}

Image 12: Area chart

Scatter Plot

{{display type="scatterplot" width="800"  height="400"  fields=""}}

Image 13: Scatter Plot

Histogram

The minValue and maxValue attributes are used to specify the maximum and minimum evertical data value to render. More info at Google charts histogram documentation.

{{display type="histogram" width="800"  height="400"  fields=""  
colors="comma separated color list"  
legendPosition="none|top|right|left|bottom"  
textPosition="out|in|none"  
isStacked="false|true|percent|relative"  
logScale="true|false"  scaleType="log|mirrorLog"  
vAxisMinValue=""  vAxisMaxValue=""  
minValue=""  maxValue=""}}

Image 14: Histogram

Bubble Chart

The fields specify a text field for the label and the numeric value fields used for the x and y axis, the bubble color and bubble size.

{{display type="bubble" width="500"  height="500"  
fields="label|x|y|color|size"  
colorTable=""  
colors="comma separated color list"  
legendPosition="none|top|right|left|bottom"  
hAxisFormat="none|decimal|scientific|percent|short|long"  
vAxisFormat="none|decimal|scientific|percent|short|long"  
hAxisTitle=""  
vAxisTitle=""}}

Example

Pie chart

More info at Google charts pie chart documentation

{{display type="piechart" fields=""
pieHole="0.5"  
is3D="true"    
bins="bin count"  
binMin="min"  
binMax="max"  
sliceVisibilityThreshold="0.01"  
width="500"  height="250"}}

Image 15: Pie chart

Radar Display

{{display type="radar" fields=""}}

Example

Image 16: Radar Display

Wind Rose

{{display type="windrose" fields=""}}

Example

Image 17: Wind Rose

Density Display

{{display type="density" fields="tmax,vp"}}

Example

Image 18: Density Display

3D Scatter

{{display type="3dscatter" fields=""}}

Example

Image 19: 3D Scatter

Calendar

Displays point data based on the date of each record. The calendar entry is color coded based on the specified field.
If missingValue is specified than any point value with that value won't be shown.

{{display type="calendar" fields=""  cellSize="15"  missingValue="0"}}

Image 20: Calendar

Gauge

This shows a single value from a series of point data.

{{display type="gauge" fields=""  gaugeMin=""  gaugeMax=""  gaugeLabel=""}}

Image 21: Gauge

5.3.0	The Basics
5.3.1	Specifying Fields
5.3.2	Filtering Data
5.3.3	Converting Data
5.3.4	Subsetting Data
5.3.5	Color
5.3.6	Display Groups
5.3.7	Displaying Multiple Entries
5.3.8	The Displays