The EBRAINS Knowledge Graph (KG) is a metadata management system that allows researchers to share and discover datasets, computational models, and software. The HDC’s KG Space integration offers easy-to-use tools for researchers to upload openMINDS metadata directly from an HDC Dataset to the EBRAINS Knowledge Graph. This direct integration with the EBRAINS Knowledge Graph fosters the discoverability and sharing of Dataset metadata created and maintained in the HealthDataCloud (HDC) with other Project members and, ultimately, into the public EBRAINS Knowledge Graph.

How it works

Members of an HDC Project can create Datasets for the management, annotation, versioning, and sharing of subsets of the Projects' data (see Working with HDC Datasets for more details). When it’s time to share openMINDS metadata from an HDC Dataset with the EBRAINS Knowledge Graph, users can use the KG Space integration tools in the HDC Portal to create a new space in the EBRAINS Knowledge Graph dedicated to that Dataset, then upload KG-compatible metadata files directly from the HDC Dataset interface. Access to the new KG Space is fully automatized and roles and permissions are synced with the HDC Project ensuring that only members of the Project from which the Data originated can access the KG space for that Dataset. Further, access to the KG space is role-based and permissions (Owner, Editor, Reader) map to Project members' HDC roles. As an HDC Project can have many Datasets associated with it, and each Dataset can have its own dedicated KG space in the EBRAINS Knowledge Graph, all Project members will have access to all the Project’s associated Dataset KG spaces. Ultimately, when HDC metadata are ready to be published in the public EBRAINS Knowledge Graph, users would submit a request to the EBRAINS Curation Team and follow their curation and publication processes (see Submiting a curation request).

Importantly, all sensitive data and metadata must remain within the HDC, and only non-sensitive metadata can be shared via the Knowledge Graph (please carefully read the Limitations section below).

Creating a Knowledge Graph Space for an HDC Dataset

After creating an HDC Dataset (please see Working with HDC Datasets), the user who created the Dataset can create a KG Space for this Dataset at any time. The only prerequisite is that the Dataset already contains data from a Project, thereby establishing the association between the Dataset and an HDC Project (see Working with Project Files in the Portal or Working with Project Files in the Command Line Interface). This association is automatically made as soon as data from a Project is added to the Dataset. The KG Space integration tools are found directly on the Datasets interface.

1. After creating an HDC Dataset and adding Project data into it, click the Create a KG Space button in the Dataset interface.
2. The KG Space will be created in a protected namespace of the central EBRAINS Knowledge Graph, using the naming convention prefix collab-hdc- added to the Dataset Code. For instance, if the HDC Dataset Code is demodataset, the name of the created KG Space will be collab-hdc-demodataset.
3. Upon successful creation of the KG space, the Dataset interface is updated to display the KG Space name:

All members of the associated Project will now also have access to the created KG Space, with permissions that match those of their role in the HDC Project (please see Access management of KG Spaces for HDC Project members for details). However, please be aware that it can take up to one hour until access is granted for all Project members after the initial KG Space creation.

Access management of KG Spaces for HDC Project members

Since the Identity and Access Management of both the HDC and the KG are based on EBRAINS accounts, roles and permissions granted to a given EBRAINS account in an HDC Project can be directly mapped to roles and permissions in the corresponding KG Spaces of the associated Datasets. Please refer to the table below for an overview of how HDC Project member roles are mapped to the KG Space roles and what permissions these roles grant in the KG Space. Please also find more details in the KG documentation of user roles.

Note: The role in KG Space of the HDC user who created both the Dataset and the corresponding Dataset will be also match the users role in the Project, i.e. if a Project Collaborator creates a Dataset with a KG Space, the role in the KG Space will be Editor - not Owner.

Importantly, when members are added to or removed from the HDC Project, or their roles within the HDC Project are changed, the changes are automatically broadcasted to all KG Spaces associated with this Project as well. Thus, removing a member from a Project will also disable their access to the corresponding Projects' KG Spaces.

Uploading metadata from HDC to a KG Space

Metadata files can be uploaded directly to the dedicated KG Space from the Dataset interface in the HDC web portal. Please refer to the HDC user guide article Working with Datasets on detailed information on how to create and edit Datasets in the HDC, and the section Creation of a Knowledge Graph Space for an HDC Dataset above on how to create an associated KG Space for this Dataset.

To upload metadata from the HDC Dataset interface,

1. Go to the Metadata tab and select the openMINDS Schemas in the Existing Schemas overview panel. If you have no openMINDS compatible schema files in the Dataset yet, you can use the Upload Schemas button for uploading.
2. Select an openMINDS compatible schema file you want to upload to the KG Space by clicking on it in the list. Upon selection of a file, four icons offer additional actions that can be performed with this file.
3. Click on the Upload icon. Your file will be transferred into the corresponding KG Space.
   
4. Upon successful transfer of the file, the date and time at which the file was transferred to the KG Space will be indicated next to the file:
   
   

The uploaded metadata file will now be discoverable for all EBRAINS users with access and view permissions to this KG Space, i.e. all members of the corresponding HDC Project (see Access management of KG Spaces for HDC Project members). Please be aware that uploading metadata from a HDC Dataset to the associated KG Space does not result in automatic publication of these files, neither in the public EBRAINS Knowledge Graph, nor the EBRAINS Knowledge Graph search tool. To do so, please see Submit a curation request below.

Deleting metadata in the HDC Dataset and in the KG Space

Metadata files can be deleted from the HDC Dataset and/or from the dedicated KG Space, directly from the Dataset interface in the HDC web portal.

To delete a metadata file,

1. Go to the Metadata tab and select the openMINDS Schemas in the Existing Schemas overview panel.
2. Select the openMINDS file you want to delete by clicking on it in the list. Upon selection of a file, four icons offer additional actions that can be performed with this file.
3. Click on the Delete icon. If your file has not been transferred to or from KG, it will be deleted instantly from your HDC Dataset.
   If your file has been transferred from or to KG, a pop-up window will prompt you to specify where you want to delete the file.
   You can chose to delete the file only in the HDC Dataset, only in KG, or in both locations. Upon clicking the corresponding button, the file will be deleted instantly at the specified location(s).
   You can abort the deletion by clicking on Cancel.

Downloading metadata from KG to the HDC Dataset

Metadata files can be downloaded from the EBRAINS Knowledge Graph to the HDC Dataset, directly from the Dataset interface in the HDC web portal.

To download a metadata instance from KG which does not yet exist in your HDC Dataset,

1. Go to the Metadata tab and select the openMINDS Schemas in the Existing Schemas overview panel.
2. Click on the Download Instances button. This will open a pop-up window that prompts you to input the KG UUID of the openMINDS instance you want to download.
   Optionally, you can specify a filename that will be used in the displayed list of metadata files in the HDC Dataset interface. If you don´t provide a filename, the KG UUID will be used per default.
   
    
3. You can confirm and start the download by clicking on the Download button. The file will be added to your list of metadata instances in your HDC Dataset interface:
   
   

To download the latest version of a metadata instance from KG which does already exist in your HDC Dataset,

1. Go to the Metadata tab and select the openMINDS Schemas in the Existing Schemas overview panel.
2. Select the openMINDS file you want to update with the latest version in KG by clicking on it in the list. Upon selection of a file, four icons offer additional actions that can be performed with this file.
3. Click on the Update icon.
   
    
4. Upon successful transfer of the file, the date and time at which the file was transferred from the KG Space will be indicated next to the file:
   

Submitting a curation request

Once you have uploaded all relevant metadata files that describe your HDC Dataset and are ready to initiate the publication of the metadata in the public EBRAINS Knowledge Graph, please refer to these instructions and guidelines to get in touch with the EBRAINS Knowledge Graph Curation Team.

Limitations

A set of limitations applies for the integration of the EBRAINS Knowledge Graph and the HealthDataCloud:

• Only non-sensitive metadata may be uploaded to the KG. All sensitive data and metadata must remain in the HealthDataCloud.
• Only valid JSON files can be uploaded. However, the use of openMINDS compatible schemas (JSON-LD files) is highly recommended to make use of the full functionality of the KG.

Copyright © 2023-2024 Indoc Systems.

HealthDataCloud is powered by Pilot technology, a product of Indoc Systems.