Explain is the endpoint that allows you to see how reported observations are linked with the final list of most probable conditions. For example, you can use this endpoint in the results page to display "reasons for" and "reasons against" particular conditions. It also provides insights into why certain conditions were considered by the inference engine and it increases the credibility of the results presented to the end-user.
Please note that Infermedica API's trial access allows only a limited number of calls to the /explain
endpoint. Please contact us
for other plan options.
The /explain endpoint responds to a modified form of POST requests to the /diagnosis endpoint. In addition to the usual structure of the request, you also need to add an additional attribute called target and assign it the ID of the condition that you want explained.
curl "https://api.infermedica.com/v3/explain" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" -d '{
"sex": "male",
"age": {
"value": 40
},
"evidence": [
{
"id": "s_50",
"choice_id": "present",
"initial": true
},
{
"id": "s_1197",
"choice_id": "present"
},
{
"id": "s_1601",
"choice_id": "unknown"
},
{
"id": "s_1925",
"choice_id": "unknown"
},
{
"id": "s_2096",
"choice_id": "unknown"
},
{
"id": "s_2019",
"choice_id": "present"
},
{
"id": "s_1763",
"choice_id": "unknown"
},
{
"id": "s_35",
"choice_id": "present"
},
{
"id": "s_30",
"choice_id": "present"
},
{
"id": "s_2051",
"choice_id": "unknown"
},
{
"id": "s_1178",
"choice_id": "unknown"
},
{
"id": "s_2006",
"choice_id": "unknown"
}
],
"target": "c_746"
}'
The example above describes the case of a 40-year-old male patient suffering from chest wall pain.
The maximum size of evidence equals 60 evidence records.
The response is represented by a JSON object with the following attributes:
supporting evidence – a list of confirmed observations that are the "reasons for" the given condition,conflicting evidence – a list of observations that may be positively linked with the given condition but were reported as absent ("reasons against"),unknown_evidence – a list of observations that may be linked with the given condition but were reported as unknown.{
"supporting_evidence": [
{
"id": "s_50",
"name": "Chest pain",
"common_name": "Chest pain"
},
{
"id": "s_1197",
"name": "Chest pain, severe",
"common_name": "Severe chest pain"
},
{
"id": "s_2019",
"name": "Chest pain, lasting between 30 minutes and 8 hours",
"common_name": "Chest pain lasting between 30 minutes and 8 hours"
},
{
"id": "s_35",
"name": "Chest pain, during exertion",
"common_name": "Chest pain on exertion"
},
{
"id": "s_30",
"name": "Chest pain, exacerbating with deep breath or cough",
"common_name": "Chest pain worsening with deep breath or cough"
}
],
"conflicting_evidence": [],
"unconfirmed_evidence": [
{
"id": "s_1601",
"name": "Chest pain, stabbing",
"common_name": "Stabbing chest pain"
},
{
"id": "s_1763",
"name": "Chest pain, exacerbated by stress",
"common_name": "Chest pain worsened by stress"
},
{
"id": "s_2051",
"name": "Chest pain, exacerbated by chest wall movement",
"common_name": "Chest pain worsening during chest wall movement"
},
{
"id": "s_1178",
"name": "Chest pain, worsens on palpation",
"common_name": "Chest pain worsening when touching or pressing"
},
{
"id": "s_2006",
"name": "Chest pain, exacerbating when lying down",
"common_name": "Chest pain worsening when lying down"
}
]
}The /explain endpoint may return 400 Bad Request response in situations where the target condition is not included in the conditions' ranking. This behavior has been introduced to prevent reverse-engineering attempts. The probability threshold is dynamic and may depend on several factors but, generally speaking, a high probability target should be explainable. That said, you should always check the response code before attempting to display the response of the /explain request.
The extras attribute may contain additional or experimental options that control the behavior of the inference engine. Some are only valid with custom models or selected partners.
enable_symptom_duration
Enables duration for evidence. For details about using symptom durations, see the /diagnosis page.