{
    "info": {
        "author": "Andrew P. Davison",
        "author_email": "andrew.davison@unic.cnrs-gif.fr",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: Apache Software License",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.4",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Topic :: Scientific/Engineering"
        ],
        "description": "# fairgraph: a Python API for the Human Brain Project Knowledge Graph.\n\nAuthors: Andrew Davison and Onur Ates, CNRS\n\nCopyright CNRS 2019\n\n**fairgraph** is an experimental Python library for working with metadata\nin the HBP 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\n```\ngit clone https://github.com/HumanBrainProject/pyxus.git pyxus_src\npip install -r pyxus_src/pyxus/requirements.txt\npip install pyxus_src/pyxus\ngit clone https://github.com/HumanBrainProject/fairgraph.git\npip install -U ./fairgraph\n```\n\n## Basic setup\n\nThe basic idea of the library is to represent data instances 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 HBP Identity account is needed.\n\nIf you are working in a Collaboratory Jupyter notebook:\n\n```\nfrom jupyter_collab_storage import oauth_token_handler\ntoken = oauth_token_handler.get_token()\n```\n\nIf working outside the Collaboratory, we recommend you obtain a token from https://nexus-iam.humanbrainproject.org/v0/oauth2/authorize\nand save it as an environment variable, e.g. at a shell prompt:\n\n```\nexport HBP_token=eyJhbGci...nPq\n```\n\nand then in Python\n\n```\ntoken = os.environ['HBP_token']\n```\n\nOnce you have a token:\n\n```\nfrom fairgraph import KGClient\n\nclient = KGClient(token)\n```\n\n## Retrieving metadata from the Knowledge Graph\n\nThe different metadata/data types available in the Knowledge Graph are grouped into modules,\ncurrently `commons`, `core`, `brainsimulation`, `electrophysiology` and `minds`.\nFor example:\n\n```\nfrom fairgraph.commons import BrainRegion\nfrom fairgraph.electrophysiology import PatchedCell\n```\n\nUsing these classes, it is possible to list all metadata matching a particular criterion, e.g.\n\n```\ncells_in_ca1 = PatchedCell.list(client, brain_region=BrainRegion(\"hippocampus CA1\"))\n```\n\nIf you know the unique identifier of an object, you can retrieve it directly:\n\n```\ncell_of_interest = PatchedCell.from_uuid(\"153ec151-b1ae-417b-96b5-4ce9950a3c56\", client)\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```\nexample_cell = cells_in_ca1[3]\nexperiment = example_cell.experiments.resolve(client)\ntrace = experiment.traces.resolve(client)\n```\n\nThe associated metadata is accessible as attributes of the Python objects, e.g.:\n\n```\nprint(example_cell.cell_type)\nprint(example_cell.reversal_potential_cl)\nprint(trace.time_step)\nprint(trace.data_unit)\n```\n\nYou can also access any associated data:\n\n```\nimport requests\nimport numpy as np\n\ndownload_url = trace.data_location['downloadURL']\ndata = np.genfromtxt(BytesIO(requests.get(download_url).content))\n```\n\n## Advanced queries\n\nWhile certain filters and queries are built in (such as the filter by brain region, above),\nmore complex queries are possible using the [Nexus query API](https://bbp-nexus.epfl.ch/staging/docs/kg/api-reference/operating-on-resources.html#search-and-filtering)\n\n```\nfrom fairgraph.base import KGQuery\nfrom fairgraph.minds import Dataset\n\nquery = {\n    \"path\": \"minds:specimen_group / minds:subjects / minds:samples / minds:methods / schema:name\",\n    \"op\": \"in\",\n    \"value\": [\"Electrophysiology recording\",\n              \"Voltage clamp recording\",\n              \"Single electrode recording\",\n              \"functional magnetic resonance imaging\"]\n}\ncontext = {\n            \"schema\": \"http://schema.org/\",\n            \"minds\": \"https://schema.hbp.eu/minds/\"\n}\n\nactivity_datasets = KGQuery(Dataset, query, context).resolve(client)\nfor dataset in activity_datasets:\n    print(\"* \" + dataset.name)\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 fairgraph.core import Person, Organization\nfrom fairgraph.commons import Address\n\nmgm = Organization(\"Metro-Goldwyn-Mayer\")\nmgm.save(client)\nauthor = Person(\"Laurel\", \"Stan\", \"laurel@example.com\", affiliation=mgm)\nauthor.save(client)\n```\n\n```\nmgm.address = Address(locality='Hollywood', country='United States')\nmgm.save(client)\n```\n\n## Getting help\n\nIn case of questions about **fairgraph**, please e-mail support@humanbrainproject.eu.\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\"></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 and No. 785907 (Human Brain Project SGA1 and SGA2).",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/HumanBrainProject/fairgraph",
        "keywords": "nar hbp metadata electrophysiology nexus shacl",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "fairgraph",
        "package_url": "https://pypi.org/project/fairgraph/",
        "platform": "",
        "project_url": "https://pypi.org/project/fairgraph/",
        "project_urls": {
            "Homepage": "https://github.com/HumanBrainProject/fairgraph"
        },
        "release_url": "https://pypi.org/project/fairgraph/0.3.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Python API for the Human Brain Project Knowledge Graph",
        "version": "0.3.1"
    },
    "last_serial": 5462336,
    "releases": {
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5b8007ba1557590d9284c0b6a8545177",
                    "sha256": "dd5c35a471678f064727d0239c5a65de57d6c8f609fe7304279b13219b23dbfb"
                },
                "downloads": -1,
                "filename": "fairgraph-0.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "5b8007ba1557590d9284c0b6a8545177",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 31642,
                "upload_time": "2019-06-11T21:08:12",
                "url": "https://files.pythonhosted.org/packages/45/64/1994d58ce0c709a9c7201334cb2107f7ff6f799f6209cc7225b827d6fd7f/fairgraph-0.2.0.tar.gz"
            }
        ],
        "0.3.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8d894f9c19991ddfd8ee76d464a5c554",
                    "sha256": "ed76a86d46ccb9fb6ade7ebc0c5cb6d76c75dc1b9d87535e1201ab628fb16740"
                },
                "downloads": -1,
                "filename": "fairgraph-0.3.0.tar.gz",
                "has_sig": false,
                "md5_digest": "8d894f9c19991ddfd8ee76d464a5c554",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 33606,
                "upload_time": "2019-06-12T13:29:23",
                "url": "https://files.pythonhosted.org/packages/d4/ae/9dc96f336c82126f58546ea0ef9bd4c027507a0829d450b2deedf7b0293d/fairgraph-0.3.0.tar.gz"
            }
        ],
        "0.3.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "91223e0009d4b4c3d760617f5d6236ae",
                    "sha256": "4807176a239b1839d8fc8e2ee55e2ee6ab842fbaac708f48b21609eff5195659"
                },
                "downloads": -1,
                "filename": "fairgraph-0.3.1.tar.gz",
                "has_sig": false,
                "md5_digest": "91223e0009d4b4c3d760617f5d6236ae",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 41067,
                "upload_time": "2019-06-28T15:45:23",
                "url": "https://files.pythonhosted.org/packages/99/15/b3f4db8db49cd502a095923758ee75429b3b1ae8592488330183c9f84913/fairgraph-0.3.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "91223e0009d4b4c3d760617f5d6236ae",
                "sha256": "4807176a239b1839d8fc8e2ee55e2ee6ab842fbaac708f48b21609eff5195659"
            },
            "downloads": -1,
            "filename": "fairgraph-0.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "91223e0009d4b4c3d760617f5d6236ae",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 41067,
            "upload_time": "2019-06-28T15:45:23",
            "url": "https://files.pythonhosted.org/packages/99/15/b3f4db8db49cd502a095923758ee75429b3b1ae8592488330183c9f84913/fairgraph-0.3.1.tar.gz"
        }
    ]
}