PLATER

About

Suppose you have constructed a biolink-compliant knowledge graph, and want to deploy it as a TRAPI endpoint with limited fuss.
Plater is a web server that automatically exposes a Neo4j or Memgraph instance through TRAPI compliant endpoints. Plater brings several tools together in a web server to achieve this. It Uses Reasoner Pydantic models for frontend validation and Reasoner transpiler for transforming TRAPI to and from cypher and querying the Neo4j or Memgraph backend. The Neo4j or Memgraph database can be populated by using KGX upload, which is able to consume numerous graph input formats. By pointing Plater to Neo4j or Memgraph we can easily stand up a Knowledge Provider that provides the “lookup” operation and meta_knowledge_graph, as well as providing a platform to distribute common code implementing future operations across any endpoint built using Plater. In addition, with some configuration (x-trapi parameters etc...) options we can easily register our new instance to Smart api.

Another tool that comes in handy with Plater is Automat, which helps expose multiple Plater servers at a single public url and proxies queries towards them. Here is an example of running Automat instance.

Data Presentation Configuration

Node and Edge lookup

---

Neo4j or Memgraph Data Structure

Nodes

Nodes are expected to have the following core structure:

1. id : as neo4j or memgraph node property with label id
2. category : Array of biolink types as neo4j node labels, it is required for every node to have at least the node label "biolink:NamedThing".
3. Additional attributes can be added and will be exposed. (more details on "Matching a TRAPI query" section)

Edges

Edges need to have the following properties structure:

1. subject: as a neo4j or memgraph edge property with label subject
2. object: as a neo4j or memgraph edge property with label object
3. predicate: as a neo4j or memgraph edge type
4. id: as a neo4j or memgraph edge property with label id
5. Additional attributes will be returned in the TRAPI response attributes section. (more details on "Matching a TRAPI query" section)

Matching a TRAPI query

PLATER matches nodes in neo4j or memgraph using node labels. It expects nodes in neo4j or memgraph to be labeled using biolink types. Nodes in neo4j or memgraph can have multiple labels. When looking a node from an incoming TRAPI query graph, the node type(s) are extracted for a node, and by traversing the biolink model, all subtypes and mixins that go with the query node type(s) will be used to lookup nodes.

It's recommended that when encoding nodes labels in neo4j that we use the biolink class genealogy. For instance a node that is known to be a biolink:SmallMolecule can be assigned all of these classes ["biolink:SmallMolecule", "biolink:MolecularEntity", "biolink:ChemicalEntity", "biolink:PhysicalEssence", "biolink:NamedThing", "biolink:Entity", "biolink:PhysicalEssenceOrOccurrent"] .

By doing such encoding, during lookup the incoming query can be more laxed (ask for biolink:NamedThing) or more specific (ask for biolink:SmallMolecule etc...), and PLATER would be able to use the encoded label information to find matching node(s).

Similarly, for edges, edge labels in neo4j or memgraph are used to perform edge lookup. Predicate hierarchy in biolink would be consulted to find subclasses of the query predicate type(s) and those would be used in an OR combinatorial fashion to find results.

Subclass Inference

Plater does subclass inference if subclass edges are encoded into the graph. For eg , let A be a super class of B and C. And let B, C are related to D and E respectively :

(A) <- biolink:subclass_of - (B) - biolink:decreases_activity_of -> (D)
    <- biolink:subclass_of - (C) - biolink:decreases_activity_of -> (E)

Querying for A - [ biolink:decreases_activity_of] -> (?) graph structure in TRAPI would give us back nodes D and E.

Presenting Attributes

Plater tries to resolve attibute types and value types for edges and nodes in the following ways.

1. attr_val_map.json: This file has the following structure

   {
   "attribute_type_map" : {
      "<attribute_name_in_neo4j>" : "TRAPI_COMPLIANT_ATTRIBUTE_NAME"
       },
   "value_type_map": {
       "<attribute_name_in_neo4j>" : "TRAPI_COMPLIANT_VALUE_TYPE"
       }
   }
   
   

   To explain this a little further, suppose we have an attribute called "equivalent_identifiers" stored in the graph. Our attr_val_map.json would be:

   {
     "attribute_type_map": {     
         "equivalent_identifiers": "biolink:same_as"
     },
     "value_type_map": {
         "equivalent_identifiers": "metatype:uriorcurie"     
     }
   }
   
   

   When Nodes / edges that have equvalent_identifier are returned they would have :

     "MONDO:0004969": {
             "categories": [...],
             "name": "acute quadriplegic myopathy",
             "attributes": [
               {
                 "attribute_type_id": "biolink:same_as",
                 "value": [
                   "MONDO:0004969"
                 ],
                 "value_type_id": "metatype:uriorcurie",
                 "original_attribute_name": "equivalent_identifiers",
                 "value_url": null,
                 "attribute_source": null,
                 "description": null,
                 "attributes": null
               }]
           }
   

2. In cases where there are attributes in the graph that are not specified in attr_val_map.json, PLATER will try to resolve a biolink class by using the original attribute name using Biolink model toolkit.

3. If the above steps fail the attribute will be presented having "attribute_type_id": "biolink:Attribute" and "value_type_id": "EDAM:data_0006"

4. If there are attributes that is not needed for presentation through TRAPI Skip_attr.json can be used to specify attribute names in neo4j or memgraph to skip. KGX loading adds a new attributes provided_by and knowledge_source to nodes and edges respectively, which are the file name used to load the graph. By default, we have included these to the skip list.

Provenance

---

By setting PROVENANCE_TAG environment variable to something like infores:automat.ctd , PLATER will return provenance information on edges.

Installation

To run the web server directly:

Create a virtual Environment and activate.

cd <PLATER-ROOT>
python<version> -m venv venv
source venv/bin/activate

Install dependencies

pip install -r PLATER/requirements.txt

Configure PLATER settings

Populate .env-template file with settings and save as .env in repo root dir.

 WEB_HOST=0.0.0.0
 WEB_PORT=8080
 GRAPH_DB=neo4j
 NEO4J_HOST=neo4j
 NEO4J_BOLT_PORT=7687
 NEO4J_USERNAME=neo4j
 NEO4J_PASSWORD=<change_me>    
 GRAPH_QUERY_TIMEOUT=600
 PLATER_TITLE='Plater'
 PLATER_VERSION='1.5.1'
 BL_VERSION='4.1.6'

Run Script

./main.sh

DOCKER

Or build an image and run it.

  cd PLATER
  docker build --tag <image_tag> .
  cd ../

 docker run --env-file .env\
  --name plater\
  -p 8080:8080\
  --network <network_where_neo4j_is_running>\
  plater-tst

Clustering with Automat Server [Optional]

You can also serve several instances of plater through a common gateway(Automat). On specific instructions please refer to AUTOMAT's readme

Miscellaneous

/about Endpoint

The /about endpoint can be used to present meta-data about the current PLATER instance. This meta-data is served from <repo-root>/PLATER/metadata/about.json file. One can edit the contents of this file to suite needs. In containerized environment we recommend mounting this file as a volume.

Eg:

docker run -p 0.0.0.0:8999:8080  \
              --env NEO4J_HOST=<your_neo_host> \
              --env NEO4J_HTTP_PORT=<your_neo4j_http_port> \
              --env NEO4J_USERNAME=neo4j\
              --env NEO4J_PASSWORD=<neo4j_password> \
              --env WEB_HOST=0.0.0.0 \
              -v <your-custom-about>:/<path-to-plater-repo-home>/plater/about.json \
              --network=<docker_network_neo4j_is_running_at> \    
               <image_tag>