Configurable Graphs and Plots Framework
Starting in S106, a framework exists that makes it possible for openBIS to generate graphs and plots from tabular datasets (csv, tsv, etc).
Configure the Graphs
The graphs are configured in their own properties file. This properties file is shared by one reporting plugin and one servlet and specifies the order and properties of the graphs shown. The location of this file can be freely chosen and configured in the
service.properties file. In this example it is in the
etc directory of the datastor server (DSS) .
The width of full-size image (obtained by clicking on the thumbnail)
The height of full-size image (obtained by clicking on the thumbnail)
The width of the thumbnail shown in the table
The height of the thumbnail shown in the table
The kinds of graphs to show, one per column, for each dataset
Three graph-types are supported : scatterplot, histogram, and heatmap. Each graph-type has its own specific configuration
The column in the dataset used for the x-coordinate of the points in the scatterplot
The column in the dataset used for the y-coordinate of the points in the scatterplot
The title of the graph
The column in the dataset used to compute the histogram
The number of bins in the histogram; defaults to 10 if not specified
The title of the graph
The column that gives the x-coordinate of the wells
The column that gives the y-coordinate of the wells
The column used to determine color/intensity in the heatmap
The title of the graph
If the x-axis column and y-axis column are the same, it is assumed that the well positions are specified in "Spreadsheet" format, e.g., A22, G9, etc.
Properties defining a column (i.e.
column) specify code and label of the column. The code is used to pick the right data and the label is used in the graph.
There are the following ways of specifying code and label:
- Normalized label as code: The value of the property defines the label. The code is the normalized label. Normalization means: Turning lower case to upper case and replacing everything which isn't a letter from A-Z or a digit by an underscore '_'.
- Bracket code: The value of property specifies code and label in the form '
label'. Note, that the code will be normalized.
- Sub properties: Sub properties
.labelas shown in the example above. If only
.labelis defined the code is determined by bracket code or by normalization of the label.
Minimal example of a data file
Internal configuration of necessary reporting plug-ins and servlets to service.properties
The graphs are driven by a reporting plug-in which creates a table and shows the graphs, one graph per column, and in one row per dataset. The graphs themselves are generated by a servlet, which the plugin refers to. Both the plugin and servlet need to be set-up in the service.properties.
Add a reporting plug-in
The class should be
servlet-path is the path to the servlet that generates the graphs (see following section). The properties-file should refer to a graph-configuration properties file (see Configure the Graphs). The file to shown is determined by the property
file-include-pattern or if missing by
file-exclude-pattern. Both property specify a regular expression. There should be exactly one file in the data set fulfilling this condition.
If you are using the Apache redirection you have to adopt the
Make sure the
Xfvb is setup and running. What to do is documented here
Graphs without common properties file
With openBIS version S151 a new parameterizable graph generation servlet was added. This service is available at the url \[dss url\]/graphservice/.
The servlet accepts the following URL parameters
|file||yes||The file that contains the data to be displayed in graph. If "dataset" is not given, the given path is relative to user's session workspace root. If dataset is given, it is relative to dataset root.|
|dataset||no||The dataset from which the data file for the graph is read. If not given, the data file is read from session workspace|
|sessionID||yes||Session token of caller|
|graph-name||no||Name of the graph. If given, all the parameters below are read from common property file if they exist (see example tabular-data-graph.properties). The values given as URL parameters override the ones defined in the file.|
|graph-type||yes||Type of graph. Valid values: SCATTERPLOT, HISTOGRAM, HEATMAP|
|title||no||Title of the graph. Defaults to value of graph-name.|
|col-x||yes||Column name in file from which to read values for x-axis.|
|col-y||yes||Column name in file from which to read values for y-axis.|
|label-x||no||Label of x-axis of the generated graph. Defaults to value of col-x.|
|label-y||no||Label of y-axis of the generated graph. Defaults to value of col-y.|
|image-height||no||Height of the generated graph in pixels. Defaults to 600.|
|image-width||no||Width of the generated graph in pixels. Defaults to 800.|
|delimiter||no||Delimiter character used in the data file. Defaults to ";"|
|col-z||mandatory only for graph-type HEATMAP||Column name in file form which to read values for z-axis.|
|bins||mandatory only for graph-type HISTOGRAM||Number of bins in histogram.|