Version 11.4 by Dennis Segebarth on 2024/12/18 11:45
Hide last authors
Dennis Segebarth 3.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Dennis Segebarth 1.1 4
5
Dennis Segebarth 3.1 6 The [[EBRAINS Knowledge Graph>>https://docs.kg.ebrains.eu/]] (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.
Dennis Segebarth 1.1 7
Dennis Segebarth 3.1 8 = How it works =
9
10 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//).
11
12 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).
13
14 = Creating a Knowledge Graph Space for an HDC Dataset =
15
16 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.
17
Dennis Segebarth 5.1 18 [[image:1723654516142-916.png||height="322" width="868"]]
Dennis Segebarth 3.1 19
20
21 1. After creating an HDC Dataset and adding Project data into it, click the **Create a KG Space** button in the Dataset interface.
22 1. The KG Space will be created in a protected namespace of the central EBRAINS Knowledge Graph, using the naming convention prefix {{code language="none"}}collab-hdc-{{/code}} added to the Dataset Code. For instance, if the HDC Dataset Code is {{code language="none"}}demodataset{{/code}}, the name of the created KG Space will be {{code language="none"}}collab-hdc-demodataset{{/code}}.
23 1. Upon successful creation of the KG space, the Dataset interface is updated to display the KG Space name:
24
Dennis Segebarth 5.1 25 [[image:1723654530597-697.png||height="362" width="868"]]
Dennis Segebarth 3.1 26
27 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.
28
29 = Access management of KG Spaces for HDC Project members =
30
31 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>>url:https://docs.kg.ebrains.eu/8387ccd27a186dea3dd0b949dc528842/user_roles.html]].
32
33 (% style="width:50%" %)
34 |=Role in HDC Project|=Role in KG Space|=Permissions in KG Space
35 |Project Admin|Owner|(((
36 * Read, write, and release instances
37 * Maintain the space information
38 )))
39 |Project Collaborator|Editor|(((
40 * Read and write instances, but NOT release them
41 )))
42 |Project Contributor|Reviewer|(((
43 * Read instances, but cannot create nor manipulate them
44 )))
45
46 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.
47
48 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.
49
50 = Uploading metadata from HDC to a KG Space =
51
52 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.
53
54 To upload metadata from the HDC Dataset interface,
55
56 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.
Dennis Segebarth 10.1 57 1. 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.
Dennis Segebarth 3.1 58 1. Click on the **Upload **icon. Your file will be transferred into the corresponding KG Space.
Dennis Segebarth 5.1 59 [[image:1723654548709-344.png||height="262" width="829"]]
Dennis Segebarth 3.1 60 1. 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:
Dennis Segebarth 5.1 61 \\[[image:1723654561600-690.png||height="271" width="829"]]
Dennis Segebarth 3.1 62
63 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.
64
Dennis Segebarth 10.1 65 {{info}}
66 If you created the KG Space just moments ago before uploading an openMINDS metadata file, the upload may fail, indicated by a pop-up message stating a permission error. This is due to a delayed update of your permissions associated with your EBRAINS account (outside of the HDC platform). Simply logout and login again to enforce an update of the permissions and you will be able to upload the file.
67 {{/info}}
68
69 = Deleting metadata in the HDC Dataset and in the KG Space =
70
71 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.
72
73 To delete a metadata file,
74
75 1. Go to the **Metadata** tab and select the **openMINDS Schemas** in the Existing Schemas overview panel.
76 1. 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.
77 1. 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.
78 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.
79 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).
80 You can abort the deletion by clicking on **Cancel**.
81
82 [[image:1727895633789-733.png||height="267" width="904"]] [[image:1727895895627-519.png||height="262" width="530"]]
83
84
85 = Downloading metadata from KG to the HDC Dataset =
86
87 Metadata files can be downloaded from the EBRAINS Knowledge Graph to the HDC Dataset, directly from the Dataset interface in the HDC web portal.
88
89 To download a metadata instance from KG which does not yet exist in your HDC Dataset,
90
91 1. Go to the **Metadata** tab and select the **openMINDS Schemas** in the Existing Schemas overview panel.
92 1. 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.
93 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.
94 [[image:1727897008202-845.png||height="331" width="756"]][[image:1727896452582-622.png]]
95
96 1. 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:
97 \\[[image:1727896792502-312.png||height="384" width="826"]]
98
99 To download the latest version of a metadata instance from KG which does already exist in your HDC Dataset,
100
101 1. Go to the **Metadata** tab and select the **openMINDS Schemas** in the Existing Schemas overview panel.
102 1. 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.
103 1. Click on the **Update **icon.
104 [[image:1727897465730-525.png]]
105
106 1. 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:
107 [[image:1727897549750-642.png]]
108
Dennis Segebarth 3.1 109 = Submitting a curation request =
110
111 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>>https://wiki.ebrains.eu/bin/view/Collabs/data-curation]] to get in touch with the EBRAINS Knowledge Graph Curation Team.
112
113 = Limitations =
114
115 A set of limitations applies for the integration of the EBRAINS Knowledge Graph and the HealthDataCloud:
116
117 * Only non-sensitive metadata may be uploaded to the KG. All sensitive data and metadata must remain in the HealthDataCloud.
118 * 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.
119
Dennis Segebarth 1.1 120 ----
121
Dennis Segebarth 4.1 122 Copyright © 2023-2024 [[Indoc Systems>>url:https://www.indocsystems.com]].
Dennis Segebarth 1.1 123
124 HealthDataCloud is powered by Pilot technology, a product of [[Indoc Systems>>url:https://www.indocsystems.com]].