graph-exploring-tool

####################
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.

Why?
----

TODO Explain what problem is solved.


Installation
------------

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.

..
.. 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 options 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.


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.