TranslatorReasonersAPI.yaml

    Query:
      x-body-name: request_body
      type: object
      properties:
        query_message:
          type: object
          description: Message object that represents the query to be answered
          items:
            $ref: '#/definitions/QMessage'
      additionalProperties: true
      example:
        message:
          query_options:
            table: patient
            year: 2010
            cohort_features:
              AgeStudyStart:
                operator: "="
                value: "0-2"
            feature:
              EstResidentialDensity:
                operator: "<"
                value: 1
            maximum_p_value: 1
          query_graph:
            nodes:
              - id: n00
                type: population_of_individual_organisms
              - id: n01
                type: chemical_substance
            edges:
              - id: e00
                type: association
                source_id: n00
                target_id: n01
    QueryOverlay:
      x-body-name: request_body
      type: object
      properties:
        query_message:
          type: object
          description: Message object that represents the query to be answered
          items:
            $ref: '#/definitions/QMessage'
      additionalProperties: true
      example:
        message:
          knowledge_graph:
            nodes:
              - id: n00
                curie: "PUBCHEM:2083"
                type: drug
              - id: n01
                type: chemical_substance
                curie: "PUBCHEM:281"
            edges:
              - id: e00
                type: association
                source_id: n00
                target_id: n01
    QueryOneHop:
      x-body-name: request_body
      type: object
      properties:
        query_message:
          type: object
          description: Message object that represents the query to be answered
          items:
            $ref: '#/definitions/QMessage'
      additionalProperties: true
      example:
        message:
          query_graph:
            nodes:
              - id: n00
                curie: "PUBCHEM:2083"
                type: drug
              - id: n01
                type: chemical_substance
            edges:
              - id: e00
                type: association
                source_id: n00
                target_id: n01
    QMessage:
      type: object
      properties:
        query_options:
          type: object
          example: 
            coalesce: true
            threshold: 0.9
          description: >-
            Dict of options that can be sent with the query. Options are tool
            specific and not stipulated here
        query_graph:
          type: object
          description: >-
            QueryGraph object that contains a serialization of a query in the form
            of a graph
          $ref: '#/definitions/QueryGraph'
      additionalProperties: true
    Message:
      type: object
      properties:
        reasoner_id:
          type: string
          example: ICEES
          description: >-
            Identifier string of the reasoner that provided this message (one of
            RTX, Robokop, Indigo, Integrator, etc.)
        tool_version:
          type: string
          example: ICEES 2.0.0
          description: Version label of the tool that generated this message
        datetime:
          type: string
          example: '2018-01-09 12:34:45'
          description: Datetime string for the time that this message was generated
        n_results:
          type: integer
          example: 42
          description: >-
            Total number of results from the query (which may be less than what is
            returned if limits were placed on the number of results to return)
        message_code:
          type: string
          example: OK
          description: >-
            Set to OK for success, or some other short string to indicate and
            error (e.g., KGUnavailable, TermNotFound, etc.)
        code_description:
          type: string
          example: 9 results found
          description: >-
            Extended description denoting the success or mode of failure in the
            generation of the message
        results:
          description: List of all returned potential answers for the query posed
          type: array
          items:
            $ref: '#/definitions/Result'
      additionalProperties: true
    Result:
      type: object
      description: One of potentially several results or answers for a query
      properties:
        score:
          type: number
          format: float
          example: 163.233
          description: Any type of score associated with this result
        score_name:
          type: string
          example: Jaccard distance
          description: Name for the score
        node_bindings:
          type: object
          description: >-
            Lookup dict that maps QNode identifiers in the QueryGraph to
            Node identifiers in the KnowledgeGraph
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
        edge_bindings:
          type: object
          description: >-
            Lookup dict that maps QEdge identifiers in the QueryGraph to
            Edge identifiers in the KnowledgeGraph
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
    KnowledgeGraph:
      type: object
      description: >-
        A thought graph associated with this result. This will commonly be a
        linear path subgraph from one concept to another, but related items aside
        of the path may be included.
      properties:
        nodes:
          type: array
          description: List of nodes in the KnowledgeGraph
          items:
            $ref: '#/definitions/Node'
        edges:
          type: array
          description: List of edges in the KnowledgeGraph
          items:
            $ref: '#/definitions/Edge'
      additionalProperties: true
      required:
        - nodes
        - edges
    QueryGraph:
      type: object
      description: >-
        A graph intended to be the thought path to be followed by a reasoner to
        answer the question. This graph is a representation of a question.
      properties:
        nodes:
          type: array
          description: List of nodes in the QueryGraph
          items:
            $ref: '#/definitions/QNode'
        edges:
          type: array
          description: List of edges in the QueryGraph
          items:
            $ref: '#/definitions/QEdge'
      additionalProperties: true
      required:
        - nodes
        - edges
    QNode:
      type: object
      description: A node in the QueryGraph
      properties:
        id:
          type: string
          example: n00
          description: >-
            QueryGraph internal identifier for this QNode. Recommended form: n00,
            n01, n02, etc.
        type:
          type: string
          description: 'Entity type of this node (e.g., protein, disease, etc.)'
          example: disease
      additionalProperties: true
    QEdge:
      type: object
      description: An edge in the QueryGraph
      properties:
        id:
          type: string
          example: e00
          description: >-
            QueryGraph internal identifier for this QEdge. Recommended form: e00,
            e01, e02, etc.
        type:
          type: string
          example: affects
          description: Higher-level relationship type of this edge
        source_id:
          type: string
          example: 'https://omim.org/entry/603903'
          description: Corresponds to the @id of source node of this edge
        target_id:
          type: string
          example: 'https://www.uniprot.org/uniprot/P00738'
          description: Corresponds to the @id of target node of this edge
      additionalProperties: true
      required:
        - source_id
        - target_id
    Node:
      type: object
      description: A node in the thought subgraph
      properties:
        id:
          type: string
          example: 'OMIM:603903'
          description: CURIE identifier for this node
        uri:
          type: string
          example: 'https://www.uniprot.org/uniprot/P00738'
          description: URI identifier for this node"
        name:
          type: string
          example: Haptoglobin
          description: Formal name of the entity
        type:
          type: array
          description: 'Entity type of this node (e.g., protein, disease, etc.)'
          example:
            - protein
          items:
            type: string
        description:
          type: string
          example: 'Haptoglobin captures, and combines with free plasma hemoglobin...'
          description: One to three sentences of description/definition of this entity
        symbol:
          type: string
          example: HP
          description: Short abbreviation or symbol for this entity
        node_attributes:
          type: array
          description: A list of arbitrary attributes for the node
          items:
            $ref: '#/definitions/NodeAttribute'
      additionalProperties: true
      required:
        - id
    NodeAttribute:
      type: object
      description: A generic attribute for a node
      properties:
        type:
          type: string
          example: article
          description: Entity type of this attribute
        name:
          type: string
          example: Wikipedia article
          description: Formal name of the attribute
        value:
          type: string
          example: '7.23e-12'
          description: Value of the attribute
        url:
          type: string
          example: 'https://en.wikipedia.org/wiki/Malaria'
          description: A URL corresponding to this attribute
      additionalProperties: true
    Edge:
      type: object
      description: An edge in the thought subgraph linking two nodes
      properties:
        id:
          type: string
          example: '553903'
          description: >-
            Local identifier for this node which is unique within this
            KnowledgeGraph, and perhaps within the source reasoner's knowledge
            graph
        type:
          type: string
          example: affects
          description: Higher-level relationship type of this edge
        relation:
          type: string
          example: upregulates
          description: Lower-level relationship type of this edge
        source_id:
          type: string
          example: 'https://omim.org/entry/603903'
          description: Corresponds to the @id of source node of this edge
        target_id:
          type: string
          example: 'https://www.uniprot.org/uniprot/P00738'
          description: Corresponds to the @id of target node of this edge
        is_defined_by:
          type: string
          example: reasoner
          description: A CURIE/URI for the translator group that made the KG
        defined_datetime:
          type: string
          example: '2018-11-03 15:34:23'
          description: >-
            Datetime at which the KG builder/updater pulled the information from
            the original source. Used as a freshness indicator.
        provided_by:
          type: string
          example: OMIM
          description: A CURIE/URI for the knowledge source that defined this edge
        confidence:
          type: number
          format: float
          example: 0.99
          description: >-
            Confidence metric for this edge, a value between (inclusive) 0.0 (no
            confidence) and 1.0 (highest confidence)
        weight:
          type: number
          format: float
          example: 0.99
          description: >-
            Weight metric for this edge, with no upper bound. Perhaps useful when
            formal confidence metrics are not available
        publications:
          type: array
          description: List of CURIEs for publications associated with this edge
          example:
            - 'PMID:12345562'
          items:
            type: string
        evidence_type:
          type: string
          example: 'ECO:0000220'
          description: >-
            A CURIE/URI for class of evidence supporting the statement made in an
            edge - typically a class from the ECO ontology
        qualifiers:
          type: string
          example: 'ECO:0000220'
          description: >-
            Terms representing qualifiers that modify or qualify the meaning of
            the statement made in an edge
        negated:
          type: boolean
          example: true
          description: >-
            Boolean that if set to true, indicates the edge statement is negated
            i.e. is not true
        edge_attributes:
          type: array
          description: A list of additional attributes for this edge
          items:
            $ref: '#/definitions/EdgeAttribute'
      additionalProperties: true
      required:
        - id
        - source_id
        - target_id
    EdgeAttribute:
      type: object
      description: A generic additional attribute for an edge
      properties:
        type:
          type: string
          example: localization
          description: Entity type of this attribute
        name:
          type: string
          example: Cell type limitation
          description: Formal name of the attribute
        value:
          type: string
          example: MFC cells
          description: >-
            Value of the attribute. While all attributes should have a name, many
            will not have a value
        url:
          type: string
          example: 'https://www.ncbi.nlm.nih.gov/pubmed/29309293'
          description: A URL corresponding to this attribute
      additionalProperties: true