# fairgraph: a Python API for the EBRAINS Knowledge Graph.
Authors: Andrew P. Davison, Onur Ates, Nico Feld, Yann Zerlaut, Glynis Mattheisen, Peyman Najafi
Copyright CNRS 2019-2024
**fairgraph** is a Python library for working with metadata
in the EBRAINS Knowledge Graph, with a particular focus on data reuse,
although it is also useful in metadata registration/curation.
The API is not stable, and is subject to change.
## Installation
To get the latest release:
```
pip install fairgraph
```
To get the development version:
```
git clone https://github.com/HumanBrainProject/fairgraph.git
pip install -U ./fairgraph
```
## Knowledge Graph versions
This version of fairgraph supports version 3 of the EBRAINS Knowledge Graph (KG).
## Basic setup
The basic idea of the library is to represent metadata nodes from the Knowledge Graph as Python objects.
Communication with the Knowledge Graph service is through a client object,
for which an access token associated with an EBRAINS account is needed.
If you are working in a Collaboratory Jupyter notebook, the client will find your token automatically.
If working outside the Collaboratory, we recommend you obtain a token from whichever authentication endpoint
is available to you, and save it as an environment variable so the client can find it, e.g. at a shell prompt:
```
export KG_AUTH_TOKEN=eyJhbGci...nPq
```
You can then create the client object:
```
>>> from fairgraph import KGClient
>>> client = KGClient(host="core.kg.ebrains.eu")
```
You can also pass the token explicitly to the client:
```
>>> client = KGClient(token)
```
## Retrieving metadata from the Knowledge Graph
The Knowledge Graph uses [openMINDS](https://github.com/HumanBrainProject/openMINDS) schemas.
Each openMINDS schema corresponds to a Python class, which are grouped into modules
following the openMINDS structure. For example:
```
>>> from fairgraph.openminds.core import DatasetVersion
>>> from fairgraph.openminds.controlled_terms import Technique
```
The following openMINDS modules are currently available: `core`, `controlled_terms`, `sands`, `computation`, `chemicals`, `specimen_prep`, `ephys`, `publications`, `stimulation`.
Using these classes, it is possible to list all metadata matching a particular criterion, e.g.
```
>>> 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")
```
For research products that are versioned, such as datasets, models, and software, certain attributes may be inherited from the parent (e.g. a DatasetVersion generally inherits its name from a Dataset). In this case, we have a convenience method to retrieve the parent's name:
```
>>> print(datasets[0].get_name(client, scope="in progress"))
'Cholinergic interneurons in the striatum - Single cell patch clamp recordings'
```
If you know the unique identifier of an object, you can retrieve it directly:
```
>>> dataset = DatasetVersion.from_id("17196b79-04db-4ea4-bb69-d20aab6f1d62", client, scope="in progress")
```
Links between metadata in the Knowledge Graph are not followed automatically,
to avoid unnecessary network traffic, but can be followed with the `resolve()` method:
```
>>> license = dataset.license.resolve(client, scope="in progress")
>>> authors = [author.resolve(client, scope="in progress") for author in dataset.authors]
```
The associated metadata is accessible as attributes of the Python objects, e.g.:
```
>>> print(dataset.version_innovation)
This is the first version of this research product.
```
To print out all the metadata for a given object, use the `show()` method:
```
>>> 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']
```
You can also access any associated data:
```
>>> dataset.download(client, local_directory=dataset.alias)
```
## Storing and editing metadata
For those users who have the necessary permissions to store and edit metadata in the Knowledge Graph,
**fairgraph** objects can be created or edited in Python, and then saved back to the Knowledge Graph, e.g.:
```
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")
```
## Getting help
In case of questions about **fairgraph**, please contact us via https://ebrains.eu/support/.
If you find a bug or would like to suggest an enhancement or new feature,
please open a ticket in the [issue tracker](https://github.com/HumanBrainProject/fairgraph/issues).
## Acknowledgements
<div><img src="https://www.braincouncil.eu/wp-content/uploads/2018/11/wsi-imageoptim-EU-Logo.jpg" alt="EU Logo" height="23%" width="15%" align="right" style="margin-left: 10px"></div>
This open source software code was developed in part or in whole in the Human Brain Project, funded from the European Union's Horizon 2020 Framework Programme for Research and Innovation under Specific Grant Agreements No. 720270, No. 785907 and No. 945539 (Human Brain Project SGA1, SGA2 and SGA3) and in the EBRAINS research infrastructure,
funded from the European Union's Horizon Europe funding programme under grant agreement No. 101147319 (EBRAINS-2.0).
Raw data
{
"_id": null,
"home_page": null,
"name": "fairgraph",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ebrains, hbp, metadata, electrophysiology, knowledge-graph",
"author": null,
"author_email": "\"Andrew P. Davison\" <andrew.davison@cnrs.fr>",
"download_url": "https://files.pythonhosted.org/packages/89/1d/c8a7dafd576dfa2d58b19a842f40cc7a5c84118bba6bc9c433826d0b5f99/fairgraph-0.12.2.tar.gz",
"platform": null,
"description": "# fairgraph: a Python API for the EBRAINS Knowledge Graph.\n\nAuthors: Andrew P. Davison, Onur Ates, Nico Feld, Yann Zerlaut, Glynis Mattheisen, Peyman Najafi\n\nCopyright CNRS 2019-2024\n\n**fairgraph** is a Python library for working with metadata\nin the EBRAINS Knowledge Graph, with a particular focus on data reuse,\nalthough it is also useful in metadata registration/curation.\nThe API is not stable, and is subject to change.\n\n## Installation\n\nTo get the latest release:\n\n```\npip install fairgraph\n```\n\nTo get the development version:\n\n```\ngit clone https://github.com/HumanBrainProject/fairgraph.git\npip install -U ./fairgraph\n```\n\n## Knowledge Graph versions\n\nThis version of fairgraph supports version 3 of the EBRAINS Knowledge Graph (KG).\n\n## Basic setup\n\nThe basic idea of the library is to represent metadata nodes from the Knowledge Graph as Python objects.\nCommunication with the Knowledge Graph service is through a client object,\nfor which an access token associated with an EBRAINS account is needed.\n\nIf you are working in a Collaboratory Jupyter notebook, the client will find your token automatically.\n\nIf working outside the Collaboratory, we recommend you obtain a token from whichever authentication endpoint\nis available to you, and save it as an environment variable so the client can find it, e.g. at a shell prompt:\n\n```\nexport KG_AUTH_TOKEN=eyJhbGci...nPq\n```\n\nYou can then create the client object:\n\n```\n>>> from fairgraph import KGClient\n\n>>> client = KGClient(host=\"core.kg.ebrains.eu\")\n```\n\nYou can also pass the token explicitly to the client:\n\n```\n>>> client = KGClient(token)\n```\n\n\n## Retrieving metadata from the Knowledge Graph\n\nThe Knowledge Graph uses [openMINDS](https://github.com/HumanBrainProject/openMINDS) schemas.\nEach openMINDS schema corresponds to a Python class, which are grouped into modules\nfollowing the openMINDS structure. For example:\n\n```\n>>> from fairgraph.openminds.core import DatasetVersion\n>>> from fairgraph.openminds.controlled_terms import Technique\n```\n\nThe following openMINDS modules are currently available: `core`, `controlled_terms`, `sands`, `computation`, `chemicals`, `specimen_prep`, `ephys`, `publications`, `stimulation`.\nUsing these classes, it is possible to list all metadata matching a particular criterion, e.g.\n\n```\n>>> patch_techniques = Technique.list(client, name=\"patch clamp\")\n>>> print([technique.name for technique in patch_techniques])\n['cell attached patch clamp', 'multiple whole cell patch clamp', 'patch clamp', 'patch clamp technique', 'whole cell patch clamp']\n>>> whole_cell_patch = patch_techniques[4]\n```\n\n```\n>>> datasets = DatasetVersion.list(client, techniques=whole_cell_patch, scope=\"in progress\")\n```\n\nFor research products that are versioned, such as datasets, models, and software, certain attributes may be inherited from the parent (e.g. a DatasetVersion generally inherits its name from a Dataset). In this case, we have a convenience method to retrieve the parent's name:\n\n```\n>>> print(datasets[0].get_name(client, scope=\"in progress\"))\n'Cholinergic interneurons in the striatum - Single cell patch clamp recordings'\n```\n\nIf you know the unique identifier of an object, you can retrieve it directly:\n\n```\n>>> dataset = DatasetVersion.from_id(\"17196b79-04db-4ea4-bb69-d20aab6f1d62\", client, scope=\"in progress\")\n```\n\nLinks between metadata in the Knowledge Graph are not followed automatically,\nto avoid unnecessary network traffic, but can be followed with the `resolve()` method:\n\n```\n>>> license = dataset.license.resolve(client, scope=\"in progress\")\n>>> authors = [author.resolve(client, scope=\"in progress\") for author in dataset.authors]\n```\n\nThe associated metadata is accessible as attributes of the Python objects, e.g.:\n\n```\n>>> print(dataset.version_innovation)\nThis is the first version of this research product.\n```\n\nTo print out all the metadata for a given object, use the `show()` method:\n\n```\n>>> print(license.show())\nid https://kg.ebrains.eu/api/instances/6ebce971-7f99-4fbc-9621-eeae47a70d85\nname Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International\nlegal_code https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode\nalias CC BY-NC-SA 4.0\nwebpages ['https://creativecommons.org/licenses/by-nc-sa/4.0', 'https://spdx.org/licenses/CC-BY-NC-SA-4.0.html']\n```\n\nYou can also access any associated data:\n\n```\n>>> dataset.download(client, local_directory=dataset.alias)\n```\n\n\n## Storing and editing metadata\n\nFor those users who have the necessary permissions to store and edit metadata in the Knowledge Graph,\n**fairgraph** objects can be created or edited in Python, and then saved back to the Knowledge Graph, e.g.:\n\n```\nfrom datetime import datetime\nfrom fairgraph.openminds.core import Person, Organization, Affiliation\n\nmgm = Organization(name=\"Metro-Goldwyn-Mayer\", alias=\"MGM\")\nmgm.save(client, space=\"myspace\")\n\naffiliation = Affiliation(organization=mgm, start_date=datetime(1942, 1, 1))\nauthor = Person(family_name=\"Laurel\", given_name=\"Stan\", affiliations=affiliation)\nauthor.save(client, space=\"myspace\")\n```\n\n## Getting help\n\nIn case of questions about **fairgraph**, please contact us via https://ebrains.eu/support/.\nIf you find a bug or would like to suggest an enhancement or new feature,\nplease open a ticket in the [issue tracker](https://github.com/HumanBrainProject/fairgraph/issues).\n\n## Acknowledgements\n\n<div><img src=\"https://www.braincouncil.eu/wp-content/uploads/2018/11/wsi-imageoptim-EU-Logo.jpg\" alt=\"EU Logo\" height=\"23%\" width=\"15%\" align=\"right\" style=\"margin-left: 10px\"></div>\n\nThis open source software code was developed in part or in whole in the Human Brain Project, funded from the European Union's Horizon 2020 Framework Programme for Research and Innovation under Specific Grant Agreements No. 720270, No. 785907 and No. 945539 (Human Brain Project SGA1, SGA2 and SGA3) and in the EBRAINS research infrastructure,\nfunded from the European Union's Horizon Europe funding programme under grant agreement No. 101147319 (EBRAINS-2.0).\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "Python API for the EBRAINS Knowledge Graph",
"version": "0.12.2",
"project_urls": {
"Homepage": "https://github.com/HumanBrainProject/fairgraph"
},
"split_keywords": [
"ebrains",
" hbp",
" metadata",
" electrophysiology",
" knowledge-graph"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1851cd61406d9c06d4ec66bdaaf84dd7149873e40e9289adb35ebcde8dc3c747",
"md5": "6665eeda2c8af77d7aba15c8790c6674",
"sha256": "0802dc7e8b4616c1bb33d719ce64d8f783e65b3d36e6ad3e24fe684e6f7f1db4"
},
"downloads": -1,
"filename": "fairgraph-0.12.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6665eeda2c8af77d7aba15c8790c6674",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 401135,
"upload_time": "2024-12-13T10:50:32",
"upload_time_iso_8601": "2024-12-13T10:50:32.638881Z",
"url": "https://files.pythonhosted.org/packages/18/51/cd61406d9c06d4ec66bdaaf84dd7149873e40e9289adb35ebcde8dc3c747/fairgraph-0.12.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "891dc8a7dafd576dfa2d58b19a842f40cc7a5c84118bba6bc9c433826d0b5f99",
"md5": "52f4554a2b4820b6bcd143051b4e440b",
"sha256": "e6e25b4a8b801d035f1ee9324bfdea606c79ae9976337c8562fe674012a900ec"
},
"downloads": -1,
"filename": "fairgraph-0.12.2.tar.gz",
"has_sig": false,
"md5_digest": "52f4554a2b4820b6bcd143051b4e440b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 155652,
"upload_time": "2024-12-13T10:50:34",
"upload_time_iso_8601": "2024-12-13T10:50:34.929407Z",
"url": "https://files.pythonhosted.org/packages/89/1d/c8a7dafd576dfa2d58b19a842f40cc7a5c84118bba6bc9c433826d0b5f99/fairgraph-0.12.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 10:50:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HumanBrainProject",
"github_project": "fairgraph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "ebrains-kg-core",
"specs": []
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "tabulate",
"specs": []
},
{
"name": "requests",
"specs": []
}
],
"lcname": "fairgraph"
}
JSON
