fairgraph：EBRAINS知识图谱的Python API。

作者：Andrew P. Davison, Onur Ates, Nico Feld, Yann Zerlaut, Glynis Mattheisen, Peyman Najafi

版权CNRS 2019-2023

fairgraph 是一个用于在EBRAINS知识图谱中处理元数据的Python库，特别关注数据重用，尽管它在元数据注册/维护中也非常有用。API是不稳定的，可能会发生变化。

安装

获取最新版本

pip install fairgraph

获取开发版本

git clone https://github.com/HumanBrainProject/fairgraph.git
pip install -U ./fairgraph

知识图谱版本

本版本的 fairgraph 支持 EBRAINS 知识图谱（KG）的版本 3。

基本设置

库的基本思想是将知识图谱中的元数据节点表示为Python对象。与知识图谱服务的通信通过客户端对象进行，需要一个与EBRAINS账户关联的访问令牌。

如果您在协作Jupyter笔记本中工作，客户端会自动找到您的令牌。

如果您在协作实验室外工作，我们建议您从您可用的任何身份验证端点获取令牌，并将其保存为环境变量，以便客户端可以找到它，例如在shell提示符下。

export KG_AUTH_TOKEN=eyJhbGci...nPq

然后您可以创建客户端对象

>>> from fairgraph import KGClient

>>> client = KGClient(host="core.kg.ebrains.eu")

您还可以显式地将令牌传递给客户端

>>> client = KGClient(token)

从知识图谱检索元数据

知识图谱使用openMINDS模式。每个openMINDS模式对应一个Python类，这些类按照openMINDS结构分组到模块中。例如

>>> from fairgraph.openminds.core import DatasetVersion
>>> from fairgraph.openminds.controlled_terms import Technique

以下openMINDS模块目前可用：core、controlled_terms、sands、computation、chemicals、specimen_prep、ephys、publications、stimulation。使用这些类，您可以列出所有符合特定标准的元数据，例如

>>> patch_techniques = Technique.list(client, name="patch clamp")
>>> print([technique.name for technique in patch_techniques])
['cell attached patch clamp', 'multiple whole cell patch clamp', 'patch clamp', 'patch clamp technique', 'whole cell patch clamp']
>>> whole_cell_patch = patch_techniques[4]

>>> datasets = DatasetVersion.list(client, techniques=whole_cell_patch, scope="in progress")

对于版本化的研究产品，如数据集、模型和软件，某些属性可能从父对象继承（例如，DatasetVersion通常从Dataset继承其名称）。在这种情况下，我们有一个方便的方法来检索父对象的名称

>>> print(datasets[0].get_name(client, scope="in progress"))
'Cholinergic interneurons in the striatum - Single cell patch clamp recordings'

如果您知道对象的唯一标识符，可以直接检索它

>>> dataset = DatasetVersion.from_id("17196b79-04db-4ea4-bb69-d20aab6f1d62", client, scope="in progress")

知识图谱中元数据的链接不会自动跟踪，以避免不必要的网络流量，但可以使用resolve()方法跟踪

>>> license = dataset.license.resolve(client, scope="in progress")
>>> authors = [author.resolve(client, scope="in progress") for author in dataset.authors]

关联的元数据可通过Python对象的属性访问，例如

>>> print(dataset.version_innovation)
This is the first version of this research product.

要打印出给定对象的全部元数据，请使用show()方法

>>> print(license.show())
id          https://kg.ebrains.eu/api/instances/6ebce971-7f99-4fbc-9621-eeae47a70d85
name        Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
legal_code  https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
alias       CC BY-NC-SA 4.0
webpages    ['https://creativecommons.org/licenses/by-nc-sa/4.0', 'https://spdx.org/licenses/CC-BY-NC-SA-4.0.html']

您还可以访问任何关联的数据

>>> dataset.download(client, local_directory=dataset.alias)

存储和编辑元数据

对于有权在知识图谱中存储和编辑元数据的用户，可以使用Python创建或编辑fairgraph对象，然后将其保存回知识图谱，例如

from datetime import datetime
from fairgraph.openminds.core import Person, Organization, Affiliation

mgm = Organization(name="Metro-Goldwyn-Mayer", alias="MGM")
mgm.save(client, space="myspace")

affiliation = Affiliation(organization=mgm, start_date=datetime(1942, 1, 1))
author = Person(family_name="Laurel", given_name="Stan", affiliations=affiliation)
author.save(client, space="myspace")

获取帮助

有关fairgraph的任何问题，请通过https://ebrains.eu/support/联系我们。如果您发现错误或想建议改进或新功能，请在问题跟踪器中提交工单。

致谢

本开源软件代码的部分或全部是在人类大脑项目中开发的，该项目由欧盟“地平线2020”研究与创新框架计划资助，具体资助协议编号为No. 720270、No. 785907和No. 945539（人类大脑项目SGA1、SGA2和SGA3）。