Explain

Explain is an endpoint that allows you to see how reported observations are linked with the final diagnoses. For example, you can use this endpoint in the results page to display "reasons for" and "reasons against" particular conditions. This feature provides insights into why certain diagnoses were considered by the reasoning engine and it increases credibility of the results presented to the end-user.

Please note that the free trial plan of the Infermedica API allows for only a limited number of calls to the /explain endpoint. Please contact us for other plan options.

Request

The /explain endpoint responds to a modified form of POST requests to the /diagnosis endpoint. Apart from the usual structure of the request, you need to add an additional attribute called target and assign it the ID of the condition that you want to explain.

curl "https://api.infermedica.com/v2/rationale" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" -d '{
    "sex": "male",
    "age": 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",
    "extras": {
        "enable_triage_5": true
    }
}'

The example above describes the case of a 40-year-old male patient suffering from chest wall pain.

Response

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"),
  • unkown_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"
        }
    ]
}

Target condition not ranked

The /explain endpoint may return 400 Bad Request response in situations where probability of the target condition hasn't reached the minimum threshold. This behavior has been introduced to prevent reverse-engineering attempts. The probability threshold is dynamic and may depend on several factors but as the rule of thumb a high probability target can be explained. However, you should always check the response code before attempting to display the response of the /explain request.