Skip to main content

A Python library and set of command line utilities for exchanging Knowledge Graphs (KGs) that conform to or are aligned to the Biolink Model.

Project description

Knowledge Graph Exchange

Python Run testsDocumentation Status Quality Gate Status Maintainability Rating Coverage PyPI Docker

KGX (Knowledge Graph Exchange) is a Python library and set of command line utilities for exchanging Knowledge Graphs (KGs) that conform to or are aligned to the Biolink Model.

The core datamodel is a Property Graph (PG), represented internally in Python using a networkx MultiDiGraph model.

KGX allows conversion to and from:

KGX will also provide validation, to ensure the KGs are conformant to the Biolink Model: making sure nodes are categorized using Biolink classes, edges are labeled using valid Biolink relationship types, and valid properties are used.

Internal representation is a property graph, specifically a networkx MultiDiGraph.

The structure of this graph is expected to conform to the Biolink Model standard, as specified in the KGX format specification.

In addition to the main code-base, KGX also provides a series of command line operations.

Example usage

Validate:

poetry run kgx validate -i tsv tests/resources/merge/test2_nodes.tsv tests/resources/merge/test2_edges.tsv

Merge:

poetry run kgx merge —merge-config tests/resources/test-merge.yaml 

Graph Summary:

poetry run kgx graph-summary -i tests/resources/graph_nodes.tsv  -o summary.txt

Transform:

poetry run kgx transform —transform-config tests/resources/test-transform-tsv-rdf.yaml

Error Detection and Reporting

Non-redundant JSON-formatted structured error logging is now provided in KGX Transformer, Validator, GraphSummary and MetaKnowledgeGraph operations. See the various unit tests for the general design pattern (using the Validator as an example here):

from kgx.validator import Validator
from kgx.transformer import Transformer

Validator.set_biolink_model("2.11.0")

# Validator assumes the currently set Biolink Release
validator = Validator()

transformer = Transformer(stream=True)

transformer.transform(
    input_args = {
        "filename": [
            "graph_nodes.tsv",
            "graph_edges.tsv",
        ],
        "format": "tsv",
    },
    output_args={
        "format": "null"
    },
    inspector=validator,
)

# Both the Validator and the Transformer can independently capture errors

# The Validator, from the overall semantics of the graph...
# Here, we just report severe Errors from the Validator (no Warnings)
validator.write_report(open("validation_errors.json", "w"), "Error")

# The Transformer, from the syntax of the input files... 
# Here, we catch *all* Errors and Warnings (by not providing a filter)
transformer.write_report(open("input_errors.json", "w"))

The JSON error outputs will look something like this:

{
    "ERROR": {
        "MISSING_EDGE_PROPERTY": {
            "Required edge property 'id' is missing": [
                "A:123->X:1",
                "B:456->Y:2"
            ],
            "Required edge property 'object' is missing": [
                "A:123->X:1"
            ],
            "Required edge property 'predicate' is missing": [
                "A:123->X:1"
            ],
            "Required edge property 'subject' is missing": [
                "A:123->X:1",
                "B:456->Y:2"
            ]
        }
    },
    "WARNING": {
        "DUPLICATE_NODE": {
          "Node 'id' duplicated in input data": [
            "MONDO:0010011",
            "REACT:R-HSA-5635838"
          ]
        }
    }
}

This system reduces the significant redundancies of earlier line-oriented KGX logging text output files, in that graph entities with the same class of error are simply aggregated in lists of names/identifiers at the leaf level of the JSON structure.

The top level JSON tags originate from the MessageLevel class and the second level tags from the ErrorType class in the error_detection module, while the third level messages are hard coded as log_error method messages in the code.

It is likely that additional error conditions within KGX can be efficiently captured and reported in the future using this general framework.

Installation

Installing from PyPI

KGX is available on PyPI and can be installed using pip as follows,

pip install kgx

To install a particular version of KGX, be sure to specify the version number,

pip install kgx==0.5.0

Installing from GitHub

Clone the GitHub repository and then install,

git clone https://github.com/biolink/kgx
cd kgx
poetry install

Setting up a testing environment for Neo4j

This release of KGX supports graph source and sink transactions with the 4.3 release of Neo4j.

KGX has a suite of tests that rely on Docker containers to run Neo4j specific tests.

To set up the required containers, first install Docker on your local machine.

Once Docker is up and running, run the following commands:

docker run -d --rm --name kgx-neo4j-integration-test -p 7474:7474 -p 7687:7687 --env NEO4J_AUTH=neo4j/test neo4j:4.3
docker run -d --rm --name kgx-neo4j-unit-test -p 8484:7474 -p 8888:7687 --env NEO4J_AUTH=neo4j/test neo4j:4.3

Note: Setting up the Neo4j container is optional. If there is no container set up then the tests that rely on them are skipped.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kgx-2.3.0.tar.gz (95.0 kB view details)

Uploaded Source

Built Distribution

kgx-2.3.0-py3-none-any.whl (117.8 kB view details)

Uploaded Python 3

File details

Details for the file kgx-2.3.0.tar.gz.

File metadata

  • Download URL: kgx-2.3.0.tar.gz
  • Upload date:
  • Size: 95.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.8.18

File hashes

Hashes for kgx-2.3.0.tar.gz
Algorithm Hash digest
SHA256 4f0c05eba4505119af8e6210a46ea2d4b0ce7adc7a1006f63c058756b400957f
MD5 528c2461594be7b7c19bda3c6e0f7faa
BLAKE2b-256 b9105f30e029ae26fb02abba1c8f3ee4ebd7f06d6510d16a01a2e6ae6e583c3d

See more details on using hashes here.

Provenance

File details

Details for the file kgx-2.3.0-py3-none-any.whl.

File metadata

  • Download URL: kgx-2.3.0-py3-none-any.whl
  • Upload date:
  • Size: 117.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.8.18

File hashes

Hashes for kgx-2.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8bcd4a1d109ff6e45fca7591b4d2a4ac42e1de98d48d89572636f9f6399e1bd6
MD5 9a49122e1176f9afea63d2d9a29f952b
BLAKE2b-256 1a9b75f335edeaee44769f90bd8a67ba7e0be124f6fa4d10e29d4c99801dc984

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page