Performing Diagnosis
/diagnosis POST
This endpoint allows to perform the diagnostic interview process. It is meant to be accessed iteratively till a flag in the response indicates that the interview process is over. For each API call, the user is expected to provide information on the patient, which should be incrementally expanded based on the responses provided so far.
Parameters
This is a POST endpoint, and it takes information about a patient encoded as the evidence data structure as the input.
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). Additionally, to show error reporting, we included a node identifier that is not present in the API (N09999).
{
"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"
},
{
"nodeId": "N09999",
"outcome": "present"
}
]
}
Response
As the endpoint is intended to act as a diagnostic interview, the response represents a step in the interview process consisting with the next question to be asked (if the process is not determined to be over), and additionally a set of tentative diagnostic hypotheses. Note that it is responsibility of the user to expand the evidence with new observations as the interview process carries on. Even if the user decided not to answer the question (or simply ignore it), the evidence should be extended by the unknown state.
The response structure is defined as follows:
- success - indicates if the query was successfully executed (values true or false)
- data - query specific data
- question
- type - the question type. The possible types are: SINGLE, GROUP_LOCATION, GROUP_CHARACTER, GROUP_SEVERITY, and GROUP_DURATION. If the question is SINGLE, it is guaranteed that the list of questions will have exactly one question. If the question is one of the GROUP_ it implies that a group of related questions is suggested.
- text - human-friendly text related to the question.
- nodes - a list of nodes that corresponding to the suggested question(s). The elements of the list are of node definition type.
- conditions - a list of possible diagnoses, ranked by the probability
- nodeId - node identifier of a node related to a suggested diagnosis
- title - a human-friendly description of the node
- probability - numeric value between 0 and 1 corresponding to the likelihood of the diagnosis
- completedDiagnosis - a flag indicating if the interview should be finished or next question (API call to /diagnosis endpoint) should follow. Values: true or false.
- question
- 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
In some cases, such as limited number of observations in the evidence, the size of the conditions list can be restricted to prevent data scraping. In such cases RESULT_SECURITY_PROTECTION error code will be added to the list of errors together with the relevant information. When errors of that type are present, data returned by the call is limited in the number of returned conditions but otherwise as expected for the input provided.
A representative response to the query presented above may look like:
{
"success": true,
"data": {
"completedDiagnosis": false,
"question": {
"type": "SINGLE",
"text": "Dysphonia",
"nodes": [
{
"id": "N02522",
"title": "Dysphonia",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
]
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
},
"conditions": [
{
"nodeId": "C00139",
"title": "Acute Bronchitis",
"probability": 0.6558424234390259
},
{
"nodeId": "C00871",
"title": "Metabolic Syndrome",
"probability": 0.6290392875671387
},
{
"nodeId": "C00074",
"title": "ACE Inhibitor-Induced Cough",
"probability": 0.484191358089447
},
... continued ...
]
},
"errors": [
{
"code": "INVALID_UUID",
"message": "No observation with uuid: N09999"
},
{
"code": "INVALID_UUID",
"message": "Invalid uuid: N09999"
},
{
"code": "INVALID_UUID",
"message": "No observation with uuid: N09999"
}
]
}
Some questions asked during the diagnostic process are so-called group questions. For example, when exploring headache, it makes sense to ask the patient about more specific information such as character, location, duration, etc. Kyla AI may decide to provide a set of questions related to the same concept, such as various descriptions of the character of cough.
When more than one question is provided, the list is sorted by relevance of the questions. Therefore, if the user prefers to use only one question at a time, the first question from the list is the most relevant.
In the example above, an alternative possibility is the questions can be related to the nature of the cough. In that case, the question section of the response would look as below:
{
"question": {
"type": "GROUP_CHARACTER",
"text": "Please describe the character of Cough",
"nodes": [
{
"id": "N06299",
"title": "Chronic Cough",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
},
{
"id": "N04113",
"title": "Cough While Lying Down",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
},
{
"id": "N04112",
"title": "Cough on Exertion",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
},
{
"id": "N01454",
"title": "Hemoptysis",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
},
{
"id": "N00141",
"title": "Productive Cough",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "present"
},
{
"outcome": "absent",
"label": "absent"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
},
{
"id": "N00753",
"title": "Dry Cough",
"outcomes": [
{
"outcome": "unknown",
"label": "Don't know"
},
{
"outcome": "present",
"label": "Yes"
},
{
"outcome": "absent",
"label": "No"
}
],
"type": "DISCRETE",
"unitOfContinuousType": null
}
]
}
}