Explain

The /explain endpoint 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.

ℹ️

Trial access to Infermedica API limits calls to the /explain endpoint. Contact us for more plan options.

Request

The /explain endpoint responds to POST requests and accepts a JSON object similar to that used for the /diagnosis endpoint. In addition to the standard request structure, an attribute named target should be added, which is assigned the ID of the condition you want explained.

To prevent reverse-engineering attempts, the maximum allowed size of evidence list is set to 60.

The example of a 40-year-old male patient suffering from chest pain (represented here by symptom s_50):

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-Id: d083e76f-3c29-44aa-8893-587f3691c0c5" \
  -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"
  }'

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.

Rationale Intent Survey