graph-exploring-tool/README.rst

####################
Graph Exploring Tool
####################

.. image:: docs/ui.png
   :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.
Note: You may need to install Python SSL certificates in case you encounter connection issues.
You can do this by running `pip install certifi`.
macOS users may need to install certificates directly from their Python installation directory.
Search for `Install Certificates.command`.

We also provide the option to install the package from a repository. If this is your preferred method, please follow along.

..
   .. code-block:: shell

      pip install graph-exploring-tool

   or

.. code-block:: shell

   pip install --index-url https://pip:glpat-m8mNfhxZAUnWvy7rLS1x@git.rys.one/api/v4/projects/264/packages/pypi/simple --no-deps graph-exploring-tool


.. role:: bash(code)
   :language: bash

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.

Usage
-----

Interface
~~~~~~~~~

|query_image| |prefix_image|
|ui_annotated_image|

.. |query_image| image:: docs/query.png
   :alt: Screenshot including the query panel of the user interface
   :width: 48%

.. |prefix_image| image:: docs/prefix.png
   :alt: Screenshot including the prefix panel of the user interface
   :width: 48%

.. |ui_annotated_image| image:: docs/ui_annotated.png
   :alt: Screenshot including the prefix panel of the user interface
   :width: 100%

The Graph Exploring Tool (or GET) is a graphical application which allows you to explore the knowledge graph using SPARQL queries.
We provide templates which allow for quick traversal of compliant knowledge graphs.
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.
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.


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 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 list of corresponding individuals will now be visible in the Results panel.
You can now use these results to further query the graph.

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
~~~~~~~~~~~~~~~~~~

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.

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.