The downloaded file will contain a folder called SparqlCharts-master. Rename it to SparqlCharts and put it into your wikis extension folder.
Include the following line at the end of your Template:Ll:
wfLoadExtension('SparqlCharts');
You can use the extension now! (There are no other extensions required as prerequisites and there is no setup procedure needed.)
Basic Usage
After successful installation, you can execute a SPARQL query and display the results of that query by using the following pattern:
{{#sparqlcharts:
QUERY
|endpoint=ENDPOINT
}}
In the pattern, replace QUERY with your SPARQL query and ENDPOINT with the endpoint you want to send your query to. A simple query could look like this:
Since we did not define a format by setting the format parameter, the query result gets displayed as the default format, which is a table. To display the results in a format other than a table, add the line |format=FORMAT and replace FORMAT by any value listed below. Each format provides several parameters to change the chart's visual appearance such as |height=HEIGHT or |color=COLOR. There are also parameters to select which parts of the result table of the SPARQL query should get displayed in the chart, explained here.
Formats
Simple Bar Chart
Click on "Expand" to see details about this format.
Used JavaScript library: D3.js[1]. Format is based on this guide.
The list of supported named colors is specified by CSS.
See here for an explanation of the parameters xaxis, yaxis, tooltipvar1, tooltipvar2, etc. and tooltiplabel1, tooltiplabel2 etc.
Click on "Expand" to see an example of the "bar chart" format.
Parameters to chose displayed parts of the SPARQL result table
Every format has certain parameters to select the very parts from the SPARQL query's result table that should be displayed in the chart.
Parameters xaxis, yaxis, zaxis
Let be the result table of the SPARQL query with rows and columns and let be the cell of in row and column . Most of the chart formats display a set of 2-tuples[3] of the form , which means every element of one tuple corresponds to the same row in the table. With the parameter xaxis you can chose the column for the first element of the 2-tuple by setting the xaxis parameter to the name of the SPARQL query's result variable that corresponds to the column .
For the bar chart format, as shown in the image below, every bar corresponds to a 2-tuple, where the first element of the tuple becomes the x-axis value of the bar, representing the "name" of the bar, and the second element becomes the y-axis value, representing the height of the bar (hence the naming of the parameters).
The charts listed in the table all work after this logic. Not all chart formats display sets of 2-tuples. The multi-bar chart and the stacked area chart are displaying 3-tuples and therefore need a third parameter: zaxis.
xaxis
yaxis
zaxis
bar chart
name of bars on x-axis
height of bars (=y-axis value)
-
line chart
x-axis values of data point
y-axis values of data points
-
pie chart
name of slices
size of slices
-
multi-bar chart
name of bars on x-axis
height of bars (=y-axis value)
name of keys in legend
(one color for each key)
stacked area chart
x-axis values of data points
y-axis values of data points
name of keys in legend
(one color for each key)
Parameters subject, object, group_subj, group_obj
The force directed graph does not display data tuples but a graph i.e. vertices and edges. Each row of the SPARQL query's result table represents one edge in the graph and its incident vertices. The parameter subject defines the column for the tail (starting point) of the edge and the parameter object defines the column for the head (end point) of the edge. The parameters group_subj (resp. group_obj) defines the group of the tail (resp. head). Different groups get displayed through different colors in the graph.
subject
object
group_subj
group_obj
force directed graph
vertex, that is tail of the edge
vertex, that is head of the edge
group of tail
group of head
Parameters boxplot1, boxplot2, etc. and boxplot1_name, etc.
In the boxplot format, every boxplot represents a group of numerical data. The data for one group is taken from a single column of the SPARQL query's result table so that one boxplot corresponds to one column of the table. With |boxplot1=?population you state that the first boxplot represents all values of he "?population"-column of the result table. With |boxplot1_name=Size of population you can set the title of boxplot1, which gets displayed on the x-axis.
Parameters tooltipvar1, tooltipvar2, etc. and tooltiplabel1, etc.
At the current state of implementation, you can only use the parameters tooltipvar1, tooltipvar2 etc. and respectively tooltiplabel1, tooltiplabel2 for the bar chart format.
A bar chart without a tooltip represents a set of 2-tuples as stated above. If you set the parameter tooltipvar1 to a variable of the SPARQL query's result table (a variable other than set by xaxis and yaxis) every bar represents a 2-tuple and the tooltip represents a further column of the result table. This makes a barchart with one element in the tooltip representing a set of 3-tuples. In the example, the column "?id" and "?count" get already displayed by the bar chart without tooltip. By setting |tooltipvar1=?type the values of the "?type"-column get displayed as a tooltip for the respective bars. |tooltiplabel1=complaint type simply sets a label that gets displayed in front of the value from the "?type"-column.
Querying own Wiki (with the help of Semantic MediaWiki)
If you use Semantic MediaWiki it is possible to synchronize your wikis data with a SPARQL endpoint (see here). By setting the endpoint parameter to the address of this endpoint, you can query for sites in your wiki or for the semantic properties.
Known issues
[4] Filter statements in SPARQL that use the pipe symbol for logical OR statements (the || symbol) will not work with the MediaWiki parser. To fix this, you need to create a template, such as the Template:! which contains the pipe character, and then include this template within your queries.
Will not work:
FILTER(?x = 3 || ?x = 4)
Works:
filter(?x = 3 {{!}}{{!}} ?x = 4)
At the moment, text cannot be wrapped around the charts and the charts cannot be placed within a table.
Future development
Here is a list of some charts that could be added to the extension:
The used NVD3 template for the "simple line chart" format provides the possibility to display multiple lines in one chart. This functionality has not been implemented in the extension yet but could be added easily.
The "force directed graph" format only exploits a few functions provided by the used [D3-template]. The format could be enriched by multiple features, such as: Mouseover-features like highlighting adjacent vertices/subgraphs or showing tooltips; collapsing/expanding subgraphs; different shapes and sizes of vertices and edges, etc. (This is a good example for a more powerful implementation).
The idea of the SparqlCharts extension is based on the "SparqlExtension" by Alfredas Chmieliauskas, Chris Davis, which provides similiar functionality (and more). Other than the SparqlExtension, our extension does not use the Google Charts API but processes the charts locally.
↑In mathematics, an n-tuple is a sequence (or ordered list) of n elements, where n is a non-negative integer. Tuples are usually written by listing the elements within parentheses "" and separated by commas; for example, denotes a 5-tuple. (See here)
