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.


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.

Why?
----

TODO Explain what problem is solved.