Explain

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.

Request

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

    curl "https://api.infermedica.com/v3/explain" \
      -X "POST" \
      -H "App-Id: XXXXXXXX" \
      -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
      -H "Content-Type: application/json" \
      -H "Interview-Token: XXX.XXXXXX.XXXX" \
      -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.

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"),
unknown_evidence – a list of observations that may be linked with the given condition but were reported as unknown.

JSON

    {
        "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 in adaptive ranking

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.

Extras

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.

Rationale Concepts