PADME Playground

This repository contains the code for the PADME Playground. See the documentation for more information on the different PADME services and the service architecture. An overview of all open source services is available here.

The current live version of the playground is accessible here. The user documentation is provided here. Moreover, you can find screenshots and a demonstration video further below.

Visit our website at padme-analytics.de.

Deployment

To deploy this service, other (dependent) services need to be deployed first. See the instructions on how to setup your own PADME instance. If you have deployed the dependencies, the following variables need to be set for the deployment of the Playground (via gitlab CI/CD variables, as described in the instructions mentioned above):

Variable Name	Description	Example value
DEPLOYMENT_TARGET_DIR	The directory on the target host where the Playground compose file will be stored. We recommend the provide the exemplary value	/home/deployment/Playground/
DEPLOYMENT_TARGET_HOST	The username and host where the Playground should be deployed to. This needs to be in the format user@host	deployment@TARGET_MACHINE_HOST_NAME
DEPLOYMENT_TARGET_SSH_KEY	The ssh private key that should be used to authenticate the user at the target host. If you took the recommendation in our guide you can use the group-level variable $MACHINE_NAME_PRIVATE_KEY here.	MACHINE_NAME_PRIVATE_KEY
PLAYGROUND_KEYCLOAK_REALM	The name of the realm the playground should authenticate against. If you followed our keycloak guide this will be pht	pht

After the deployment, please follow the following instructions to finish the Keycloak setup for the playground.

Playground Keycloak setup

Perform the following steps to configure keycloak for the PADME playground:

1. Open the Keycloak UI at [https://auth.YOUR_DOMAIN](https://auth.YOUR_DOMAIN). Open the "Administration Console" and authenticate with your credentials.

2. In the realm "pht", navigate to "Clients" on the left. Click "Create" in the top right corner. Enter the following information:

Client ID: playground

Client Protocol: openid-connect (default)

Root URL: https://playground.$YOUR_DOMAIN (replace $YOUR_DOMAIN)

Submit your changes by clicking "Save"

Thats it! You should now be redirected to the Keycloak login when navigating to [https://playground.{YOUR_DOMAIN}](https://playground.{YOUR_DOMAIN}). Lastly, you need to fill the Blazegraph database associated with the Playground with data in order to use the playground. See the instructions in /backend/Readme on how to do so. You can also use the turtle file provided in /backend/eval.

Further instructions are available in this GitHub repository, which contains the version of the code that was used for a publication about the Playground.

Development

The playground consists of two main components: A backend written in Node.js and a frontend written with typescript using angular and material. For details on each component and how to continue development, please look at the readme file in the respective sub-folder.

Video demonstration

The following video demonstrates the usage of the Playground by conducting an exemplary analysis:

(Click on the image to watch the video on YouTube)

Screenshots

The following provides screenshots of the different aspects of the developed tool.

Simulation setup

Before starting the simulation, one has to select the data sources and institutes that the simulation should use. For this, one can browse the available institutes and explore their data sources, which are displayed via a data schema visualization (1). Besides the schema information, the UI also offers further details for the available data sources like the type and version of the data source (e.g. PostgreSQL version 14.0), a description of the available data, and whether authentication is required for data access (2).

The screenshots below show two examples of data schema visualizations. For example, (1) shows the data model for one of the FHIR servers from the ISIC use case. On the other hand, (3) visualizes a relation PostgreSQL database.

FHIR database (1)	Data source details (2)	Relational database (3)

After selecting the data source and institutes, one can configure the route in which the institutes should be visited (4). Once the user it satisfied with the selection, pressing 'Confirm' will lead to the Playground setting up the simulation environment (5). This setup leverages the different Playground components and plugins as introduced in the paper. The duration of the setup depends on the type of data source that is used and how much time this source needs to become responsive. For the currently supported data sources (PostsgreSQL, MinIO, Blaze FHIR) this takes between 5-20 seconds.

Route selection (4)	Simulation setup in progress (5)

Executing the simulation

Once the simulation setup is finished, the user is greeted with the main screen of the playground (6). This screen is split into two parts: The code editor on the left and simulation configuration/details on the right side.

Code editor

In the code editor, the user can choose a template as a starting point (7) or start with an empty file. Moreover, the editor allows one to download the all the files from the current analysis, create new files, upload existing files or previously downloaded analysis, and start the simulation via the 'play' button (8).

Main screen (6)	Code templates (7)	Code editor options (8)

Simulation details

The right-hand side of the main screen offers a total of six different screens which provide additional simulation details or allow developers to adjust simulation settings.

The first screen ('Schema') offers the data schema visualization as provided during the simulation setup (9 & 1). This visualization is interactive and allows one to zoom and move elements to a preferred position (see the video above). Moreover, the second screen ('Schema Details') provides the database details that were already mentioned above and could be seen in the setup screen as well (10). If needed, the third screen ('Route') allows developers to change the order in which the data providers will be visited during the simulation (11).

Data schema visualization (9)	Database details (10)	Route settings (11)

The Screen 'Log Output' allows developers to monitor the execution of their simulation. For example, (12) shows the output of an ML learning algorithm that is executed on the simulated data. If needed, this screen also allows one to show detailed build outputs for the Docker image. Moreover, it provides options to filter execution logs according to the visited data providers. After the execution of an algorithm is finished, the screen 'Filesystem Changes' allows developers to see which files in the container were modified, added, or deleted (13). Moreover, users can download the modified or changed files and view text-based files directly in the Playground (14).

Execution logs (12)	Filesystem changes (13)	Example content of a modified file (14)

Lastly, the screen 'Environment Variables' can be used to inject run-time configuration, such as Hyperparameters, into the analysis code via so-called environment variables (15). Moreover, this screen also shows the configuration parameters that are provided by the DB plugins after the data source initialization (15).

Run-time configuration (15)