Skip to main content

Explaining Risks

/explain POST​

This endpoint allows generating an explanation for risk assessment provided by the Kyla API.

Parameters​

This is a POST endpoint, and it takes information about a node identifier for a condition node and a patient encoded as the evidence data structure as the input.

note

The explanations can be only generated for nodes that are of a category CONDITION.

Example of evidence for a 35-year-old patient who is an active smoker (N00004), decided not to disclose his drinking habits (N00007) and with diagnosed hypertension (node id C00020) and complaining about cough that lasts over a month (N04116). The explanations are generated for Acute Bronchitis (C00139) which is one of the top diagnoses. 

{
  "conditionNodeId": "C00139",
  "evidence": {
    "sex": "MALE",
    "age": 35,
    "observations": [
      {
        "nodeId": "C00020",
        "outcome": "present"
      },
      {
        "nodeId": "N00004",
        "outcome": "active_smoking"
      },
      {
        "nodeId": "N00007",
        "outcome": "unknown"
      },
      {
        "nodeId": "N04116",
        "outcome": "cough_more_4_weeks"
      }
    ]
  }
}

Response​

As the endpoint is intended to provide explanations in the form of qualitative statements, where each observation from the provided evidence can be classified as supporting the diagnosis, disproving it or being neutral (no influence).

The response structure is defined as follows:

  • success - indicates if the query was successfully executed (values true or false)
  • data - query specific data
    • evidenceFor - a list of nodes from the provided evidence, that increase the likelihood of the diagnosis
      • id - node identifier (of a node from the evidence)
      • title - a human-friendly description of the node
    • evidenceAgainst - a list of nodes from the provided evidence, that decrease the likelihood of the diagnosis
      • id - node identifier (of a node from the evidence)
      • title - a human-friendly description of the node
    • evidenceNeutral - a list of nodes from the provided evidence, that have no effect on the likelihood of the diagnosis
      • id - node identifier (of a node from the evidence)
      • title - a human-friendly description of the node
  • errors - a list of (possibly non-critical) errors that occurred during the query processing
    • code - code for type of error (e.g. INVALID_UUID)
    • message - human-friendly description of the error

A representative response to the query presented above may look like:

{
  "success": true,
  "data": {
    "evidenceFor": [
      {
        "id": "N04116",
        "title": "Cough Duration"
      },
      {
        "id": "N00004",
        "title": "Smoking"
      }
    ],
    "evidenceAgainst": [
      {
        "id": "C00020",
        "title": "Hypertension"
      }
    ],
    "evidenceNeutral": []
  },
  "errors": []
}