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 file. In this example it is in the etc directory of the datastor server (DSS) .
separator = ,

full-width = 800
full-height = 600

column-width = 300
column-height = 200

graphs = scatter1, hist, heat, heat2, scatter2

scatter1.graph-type = scatterplot
scatter1.x-axis = TotalCells
scatter1.y-axis = InfectedCells
scatter1.title = Total vs. Infected

hist.graph-type = histogram
hist.column = TotalCells
hist.number-of-bins = 7
hist.title = Total Cells Histogram

heat.graph-type = heatmap
heat.x-axis = WellName
heat.y-axis.code = WELL_NAME
heat.y-axis.label = Well Name
heat.column = InfectionIndex
heat.title = Infection Index

heat2.graph-type = heatmap
heat2.x-axis = WellName
heat2.y-axis = WellName
heat2.column = TotalCells
heat2.title = Total Cells

scatter2.graph-type = scatterplot
scatter2.x-axis = TotalCells
scatter2.y-axis = RelativeInfectionIndex
scatter2.title = Total vs. Rel Infection




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.

Column Property

Properties defining a column (i.e. x-axis, y-axis, and 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 '<code> label'. Note, that the code will be normalized.
  • Sub properties: Sub properties .code and .label as shown in the example above. If only .label is 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

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

Add a reporting plug-in
reporting-plugins = graph, ...

graph.label = Show My Graphs
graph.dataset-types = MY_DATA_SET_TYPE
graph.class = ch.systemsx.cisd.openbis.dss.generic.server.plugins.FileBasedImageAnalysisGraphReportingPlugin
graph.file-include-pattern = test_plot.csv
graph.servlet-path = datastore_server_graph/ = etc/
graph.servlet.class = ch.systemsx.cisd.openbis.dss.generic.server.FileTabularDataGraphServlet
graph.servlet.path = /${graph.servlet-path}* = ${}

The class should be ch.systemsx.cisd.openbis.dss.generic.server.plugins.FileBasedImageAnalysisGraphReportingPlugin. The 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 /etc/http/conf.d/openbis.conf:

 ProxyPass /openbis/
 ProxyPassReverse /openbis/
 ProxyPass /datastore_server/
 ProxyPassReverse /datastore_server/
 ProxyPass /datastore_server_graph/
 ProxyPassReverse /datastore_server_graph/
 ProxyPass /
 ProxyPassReverse /

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

fileyesThe 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.
datasetnoThe dataset from which the data file for the graph is read. If not given, the data file is read from session workspace
sessionIDyesSession token of caller
graph-namenoName of the graph. If given, all the parameters below are read from common property file if they exist (see example The values given as URL parameters override the ones defined in the file.
graph-typeyesType of graph. Valid values: SCATTERPLOT, HISTOGRAM, HEATMAP
titlenoTitle of the graph. Defaults to value of graph-name.
col-xyesColumn name in file from which to read values for x-axis.
col-yyesColumn name in file from which to read values for y-axis.
label-xnoLabel of x-axis of the generated graph. Defaults to value of col-x.
label-ynoLabel of y-axis of the generated graph. Defaults to value of col-y.
image-heightnoHeight of the generated graph in pixels. Defaults to 600.
image-widthnoWidth of the generated graph in pixels. Defaults to 800.
delimiternoDelimiter character used in the data file. Defaults to ";"
col-zmandatory only for graph-type HEATMAPColumn name in file form which to read values for z-axis.
binsmandatory only for graph-type HISTOGRAMNumber of bins in histogram.



  • No labels