User:Wingoli/SparqlCharts

The SparqlCharts extension allows to query SPARQL endpoints and display the query result in different formats.

Download
You can download the extension [TODO:Link here].

Installation

 * 1) Unzip the downloaded zip file. Put the folder 'SparqlCharts' into your wikis extension folder.
 * 2) Include the following line at the end of your LocalSettings.php:
 * 3) 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:

In the pattern, replace  with your SPARQL query and   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  and replace   by any value listed below. Each format provides several parameters to change the chart's visual appearance such as  or. There are also parameters to select which parts of the result table of the SPARQL query should get displayed in the chart, explained here.

Simple Bar Chart
Click on "Expand" to see details about this format.



Mandatory parameters:,.

Used JavaScript library: D3.js. Format is based on this guide.

The list of supported named colors is specified by CSS. See here for an explanation of the parameters,  ,  ,  , etc. and  ,   etc.

Click on "Expand" to see an example of the "bar chart" format.



The chart depicted in this screenshot has been created by the following code:

Multi-Bar Chart
Click on "Expand" to see details about this format.



Mandatory parameters:,.

Used JavaScript libraries: D3.js,  NVD3.js

See here for an explanation of the parameters,    and.

Click on "Expand" to see an example of the "mulit-bar chart" format.



The chart depicted in this screenshots has been created by the following code:

Pie Chart / Donut Chart
Click on "Expand" to see details about this format.



Mandatory parameters:,. (Note: For using the donut chart, you need to set  . As per default, this format is a pie chart.)

Used JavaScript libraries: D3.js,  NVD3.js

The possible values for the parameter   are listed here. See here for an explanation of the parameters  and.

Click on "Expand" to see an example of the "donut chart" format.



The chart depicted in this screenshot has been created by the following code:

Simple Line Chart
Click on "Expand" to see details about this format.



Mandatory parameters:,.

Used JavaScript libraries: D3.js,  NVD3.js

The list of supported named colors is specified by CSS. See here for an explanation of the parameters  and.

Click on "Expand" to see an example of the "simple line-chart" format.



The chart depicted in this screenshot has been created by the following code:

Stacked Area Chart
Click on "Expand" to see details about this format.



Mandatory parameters:,.

Used JavaScript libraries: D3.js,  NVD3.js

See here for an explanation of the parameters,    and.

Click on "Expand" to see an example of the "stacked-area chart" format.



The chart depicted in this screenshots has been created by the following code:

Boxplot
Click on "Expand" to see details about this format.



Mandatory parameters:,.

Used JavaScript libraries: D3.js. Format is based on this template.

See here for an explanation of the parameters,  , etc. and  ,   etc. Click on "Expand" to see an example of the "bar chart" format.



The chart depicted in this screenshot has been created by the following code:

Force Directed Graph
Click on "Expand" to see details about this format.



Mandatory parameters:,.

Used JavaScript libraries: D3.js. Format is based on this template.

See here for an explanation of the parameters,  , etc. and  ,. Click on "Expand" to see an example of the "force directed graph" format.



The chart depicted in this screenshot has been created by the following code:

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, ,
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 of the form, which means every element of one tuple corresponds to the same row in the table. With the parameter  you can chose the column  for the first element of the 2-tuple by setting the   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:.

Parameters,,  ,
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  defines the column for the tail (starting point) of the edge and the parameter   defines the column for the head (end point) of the edge. The parameters  (resp.  ) defines the group of the tail (resp. head). Different groups get displayed through different colors in the graph.

Parameters,, etc. and  , 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  you state that the first boxplot represents all values of he "?population"-column of the result table. With  you can set the title of boxplot1, which gets displayed on the x-axis.

Parameters,, etc. and  , etc.
At the current state of implementation, you can only use the parameters,   etc. and respectively  ,   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  to a variable of the SPARQL query's result table (a variable other than set by   and  ) 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  the values of the "?type"-column get displayed as a tooltip for the respective bars. 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  parameter to the address of this endpoint, you can query for sites in your wiki or for the [semantic properties].

Known issues

 * 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).
 * NVD3 Scatter/Bubble Chart SparqlCharts_NVD3_Scatter_Bubble_Chart.png
 * NVD3 Multi-Line Chart with focus SparqlCharts_NVD3_Multi-Line_Chart_with_focus.png
 * NVD3 Horizontal Multi-Bar Chart SparqlCharts_NVD3_Horizontal_Multi-Bar_Chart.png

Credits
The idea of the SparqlCharts extension is based on the "SparqlExtension" by [mailto:a.chmieliauskas@tudelft.nl Alfredas Chmieliauskas], [mailto:c.b.davis@tudelft.nl 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.