|
|
@@ -6,14 +6,39 @@ Graph Exploring Tool
|
|
|
:alt: Screenshot of the user interface
|
|
|
|
|
|
Virtual Knowledge Graph exploration tool built for use with a graph based on the FTG+PM concept.
|
|
|
+We add prefix translation for general concepts and the `SDO2L vocabulary <https://msdl.uantwerpen.be/git/lucasalbertins/DTDesign/src/joeri/examples/oml/SystemDesignOntology2Layers>`_.
|
|
|
+The translated prefixes can be extended:
|
|
|
+
|
|
|
+.. code-block:: toml
|
|
|
+
|
|
|
+ # Functions and services
|
|
|
+ [[prefixes]]
|
|
|
+ name = "dtf"
|
|
|
+ ...
|
|
|
+ [[prefixes]]
|
|
|
+ name = "traceability_model"
|
|
|
+ namespace = "http://ua.be/sdo2l/vocabulary/formalisms/traceability_model#"
|
|
|
+ [[prefixes]]
|
|
|
+ name = "xopp"
|
|
|
+ namespace = "http://ua.be/sdo2l/vocabulary/formalisms/xopp#"
|
|
|
+ [[prefixes]]
|
|
|
+ name = "federation"
|
|
|
+ namespace = "http://ua.be/sdo2l/vocabulary/federation#"
|
|
|
+
|
|
|
+The `Modifying settings`_ section goes into more detail on this file.
|
|
|
|
|
|
+Why?
|
|
|
+----
|
|
|
+
|
|
|
+This tool allows a user to explore the knowledge graph using predefined SPARQL queries.
|
|
|
+Therefore, SPARQL knowledge requirements are minimized while still allowing service invoking and data extraction.
|
|
|
|
|
|
Installation
|
|
|
------------
|
|
|
|
|
|
-If you are on Windows you can download the binary at URL and run it by double-clicking it.
|
|
|
+If you are on Windows, you can download the binary at URL and run it by double-clicking it.
|
|
|
|
|
|
-We also provide the option to install the package from a repository. If this is your prefered method please follow along.
|
|
|
+We also provide the option to install the package from a repository. If this is your preferred method, please follow along.
|
|
|
|
|
|
..
|
|
|
.. code-block:: shell
|
|
|
@@ -30,7 +55,7 @@ We also provide the option to install the package from a repository. If this is
|
|
|
.. role:: bash(code)
|
|
|
:language: bash
|
|
|
|
|
|
-To run the application you can use :bash:`python3 -m graph-exploring-tool`.
|
|
|
+To run the application, you can use :bash:`python3 -m graph-exploring-tool`.
|
|
|
|
|
|
For WSL check out: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps
|
|
|
|
|
|
@@ -62,7 +87,7 @@ The tool separates actions into multiple panels.
|
|
|
1. The left Query Palette panel **(red)** allows you to load a predefined template. Hovering over the name of the template will provide a tooltip with the description of the action carried out by that template.
|
|
|
2. The center and main Query Editor panel **(green)** is where the template is shown once it has been chosen. You can change the template itself or use the provided fields **(blue)** to insert references into the template itself.
|
|
|
The reference fields support dragging and dropping.
|
|
|
- To perform the query you need to click the Query button.
|
|
|
+ To perform the query, you need to click the Query button.
|
|
|
3. The small one line panel **(yellow)** show the status. This includes messages whether a query was successful. Any error will also be displayed right here.
|
|
|
4. The most important panel is the Results panel **(orange)**. Any information returned by the query will be displayed here.
|
|
|
You can drag and drop any of the fields in the result onto the parameters fields in the template.
|
|
|
@@ -74,17 +99,88 @@ Workflow
|
|
|
We propose a simple workflow:
|
|
|
You open up the FTGPM++ (workflow diagram) and look at what is of interest to you.
|
|
|
Let's say you are interested in finding all the individuals (or instances) of a certain type.
|
|
|
-You look at the Query Palette panel. You see the first options which is what you need.
|
|
|
+You look at the Query Palette panel. You see the first option, which is what you need.
|
|
|
Now you click on this (Find Individuals) button. Here you see that you need to specify two parameters.
|
|
|
|
|
|
- We need to know what class the individuals you're looking for belong to and perhaps a relation to another individual.
|
|
|
|
|
|
-The example assumes you want to find all Formalisms and their name.
|
|
|
-At this point you can execute the query by clicking the Query button.
|
|
|
+The example assumes you want to find all `Formalisms` and their name.
|
|
|
+At this point, you can execute the query by clicking the Query button.
|
|
|
The list of corresponding individuals will now be visible in the Results panel.
|
|
|
You can now use these results to further query the graph.
|
|
|
|
|
|
-Why?
|
|
|
-----
|
|
|
+Outlier detection workflow demo
|
|
|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+To give a concrete example, we follow a workflow for figuring out outliers in a CSV file created during the `enactment process <https://msdl.uantwerpen.be/git/lucasalbertins/wee/wiki/Basic+Tutorial>`_.
|
|
|
+You start by opening the GUI.
|
|
|
+You can then double-check the settings, like the endpoint.
|
|
|
+If all settings are correct, you can proceed by choosing the `Outlier Function` in the `Query Palette`.
|
|
|
+
|
|
|
+The `Visual Query Editor` will now have the following `Query` pre-set for you.
|
|
|
+
|
|
|
+.. code-block:: sql
|
|
|
+
|
|
|
+ SELECT ?outlier ?outlier_relation ?outlier_value WHERE {
|
|
|
+ SERVICE <{{ service_endpoint }}> {
|
|
|
+ SELECT ?outlier ?outlier_relation ?outlier_value WHERE {
|
|
|
+ BIND(dtf:outlier("{{ outlier_file }}", "{{ outlier_column }}", "{{ outlier_artifact }}") AS ?outlier)
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+You don't need to understand the SPARQL query itself. What you are likely interested in are the fields below the `Query`.
|
|
|
+
|
|
|
+- `http://127.0.0.1:8000/`
|
|
|
+- `rotation.csv`
|
|
|
+- `2`
|
|
|
+- `<http://ua.be/drivetrain/description/artifacts/artifacts#drivetrain-sensor-data-v1>`
|
|
|
+
|
|
|
+They are, in sequential order, the service, the file, the column, and the artifact URI.
|
|
|
+The first field, `http://127.0.0.1:8000/`, is the `URI to a (in this case local) service for outliers <https://msdl.uantwerpen.be/git/arys/spendpoint>`_ we provide.
|
|
|
+
|
|
|
+Once you're satisfied with the fields you filled in you can gently press the `Query` button.
|
|
|
+You should be greeted by a results resembling the following image.
|
|
|
+
|
|
|
+.. |results| image:: docs/results.png
|
|
|
+ :alt: Screenshot including the results of an outlier query
|
|
|
+ :width: 100%
|
|
|
+
|
|
|
+Congratulations! You have successfully performed outlier detection on the enactment artifact.
|
|
|
+
|
|
|
+Advanced usage
|
|
|
+--------------
|
|
|
+
|
|
|
+.. _Modifying settings:
|
|
|
+Modifying settings
|
|
|
+~~~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+All settings are stored in the :bash:`data/configuration.toml` file.
|
|
|
+There isn't much of value for an end user to change.
|
|
|
+The 4 settings available are:
|
|
|
+
|
|
|
+- The :bash:`endpoint_sparql`: where to send the queries.
|
|
|
+- The :bash:`example_prefix`: the initial prefix shown in the interface.
|
|
|
+- The :bash:`example_query`: the initial query shown in the interface.
|
|
|
+- A list of :bash:`prefixes` which have a :bash:`name` and :bash:`namespace`: these are used for simplifying queries.
|
|
|
+
|
|
|
+Adding templates
|
|
|
+~~~~~~~~~~~~~~~~
|
|
|
+
|
|
|
+You can add more templates by creating a :bash:`.toml` file under :bash:`data/palette/`.
|
|
|
+Each template has required fields.
|
|
|
+
|
|
|
+- A :bash:`group`: What group this template belongs to in the palette panel.
|
|
|
+- The :bash:`name`: A short identifier for the template.
|
|
|
+- The :bash:`prefix` list: A string containing the full prefix for the query.
|
|
|
+- The :bash:`query` template: The query itself. Placeholder can be defined between double curly brackets.
|
|
|
+- The :bash:`description`: A longer description for the template, which will be shown as the tooltip.
|
|
|
+- Whether :bash:`visual_support` is enabled: Deprecated. Always true.
|
|
|
+- A list of :bash:`replacements` each having 3 fields: One needs to be defined for each placeholder in the query.
|
|
|
+
|
|
|
+ - The :bash:`placeholder`: Which placeholder gets replaced.
|
|
|
+ - The :bash:`suggestion`: The initial value of the replacement.
|
|
|
+ - The :bash:`description`: What should be put in the field.
|
|
|
|
|
|
-TODO Explain what problem is solved.
|
|
|
+You need to restart the interface after you create a new file.
|
|
|
+The new template will now be available as a choice in the palette panel.
|
