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) .
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
key | value |
---|---|
full-width | The width of full-size image (obtained by clicking on the thumbnail) |
full-height | The height of full-size image (obtained by clicking on the thumbnail) |
column-width | The width of the thumbnail shown in the table |
column-height | The height of the thumbnail shown in the table |
graphs | 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
Scatterplot
key | value |
---|---|
x-axis | The column in the dataset used for the x-coordinate of the points in the scatterplot |
y-axis | The column in the dataset used for the y-coordinate of the points in the scatterplot |
title | The title of the graph |
Histogram
key | value |
---|---|
column | The column in the dataset used to compute the histogram |
number-of-bins | The number of bins in the histogram; defaults to 10 if not specified |
title | The title of the graph |
Heatmap
key | value |
---|---|
x-axis | The column that gives the x-coordinate of the wells |
y-axis | The column that gives the y-coordinate of the wells |
column | The column used to determine color/intensity in the heatmap |
title | 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
TotalCells,InfectedCells 1,1 2,3 4,5 5,6 3,4
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
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/ graph.properties-file = etc/tabular-data-graph.properties graph.servlet.class = ch.systemsx.cisd.openbis.dss.generic.server.FileTabularDataGraphServlet graph.servlet.path = /${graph.servlet-path}* graph.servlet.properties-file = ${graph.properties-file}
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/ http://openbis-dsu.ethz.ch:8080/openbis/ ProxyPassReverse /openbis/ http://openbis-dsu.ethz.ch:8080/openbis/ ProxyPass /datastore_server/ http://openbis-dsu.ethz.ch:8081/datastore_server/ ProxyPassReverse /datastore_server/ http://openbis-dsu.ethz.ch:8081/datastore_server/ ProxyPass /datastore_server_graph/ http://openbis-dsu.ethz.ch:8081/datastore_server_graph/ ProxyPassReverse /datastore_server_graph/ http://openbis-dsu.ethz.ch:8081/datastore_server_graph/ ProxyPass / http://openbis-dsu.ethz.ch:8082/ ProxyPassReverse / http://openbis-dsu.ethz.ch:8082/
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
argument | mandatory | description |
---|---|---|
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. |