Rationale

The /rationale endpoint enhances transparency and insight into the internal logic of the question selection process that determines which observation to ask about next. An “observation” refers to a medical concept (opens in a new tab) in our knowledge base, representing one of the patient’s health parameters: symptom or risk factor. Once the algorithm selects an observation, the /rationale endpoint can provide the reasoning behind that choice. The reasoning can then be displayed to end-users during the interview to improve their overall understanding of and confidence in the system.

Request

The /rationale endpoint responds to POST requests and accepts the same JSON object as the /diagnosis endpoint.

curl "https://api.infermedica.com/v3/rationale" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Interview-ID: d083e76f-3c29-44aa-8893-587f3691c0c5" \
  -d '{
        "age" : {"value": 25},
        "evidence" : [ 
            {
                "choice_id" : "present",
                "id" : "s_44"
            }
        ],
        "sex" : "female"
  }'

The example above describes the case of a 25-year-old female patient who has already reported joint pain (represented here by symptom s_44).

Extras

The extras attribute found in the /diagnosis endpoint is also available with /rationale. For more information, see Extras (opens in a new tab).

Response

Rationale is an object comprised of the following attributes:

• type: string - a well defined code (r0-r6)
• observation_params: list[string] - a list of observation IDs, relevant to prioritizing a question
• condition_params: list[string] - a list of condition IDs, relevant to prioritizing a question

The response is represented by a JSON object that uses the previously mentioned data model.

{
    "type": "r6",
    "observation_params": [
        {
            "id": "s_44",
            "name": "Joint pain",
            "common_name": "Joint pain"
        }
    ],
    "condition_params": []
}

This response indicates that the question asked by the algorithm is an important observation directly related to one of the pieces of evidence already provided. In this case - to joint pain.

Types of rationale

The different rationale types are as follows:

• r0 – Current question has the highest inferred statistical relevance. Returned possible values include:

  • observation_params - a one-element list containing the observation in question
  • condition_params - all of the rankings conditions that are related to the observation in question

• r1 – Current question is based on a custom rule that’s been used to refine the algorithm. This will be one of four variants:

  • the observation is both considered important by our medical experts and has a sufficiently high inferred relevance. Returned possible values include:

    • observation_params - a one-element set, the observation
    • condition_params - empty

  • the observation is crucial for the improvement of confidence in several key conditions. Returned possible values include:

    • observation_params - empty
    • condition_params - the set of conditions that more confidence is needed for

  • the observation is a child node of another relevant observation and has a sufficiently inferred relevance value. Returned possible values include:

    • observation_params - a one-element set, the parent observation of the prioritized observation
    • condition_params - empty

• r2 – Current question is about one of a few pre-defined “key symptoms” and is relevant for a condition that is sufficiently high in statistical relevance. Returned possible values include:

  • observation_params - a one-element set, the key symptom
  • condition_params - a one-element set, the condition that the key symptom is relevant for

• r3 – Current question is about a mandatory observation for a condition that is sufficiently probable in relevance. Returned possible values include:

  • observation_params - empty
  • condition_params - a one-element set, the condition that the observation is mandatory for

• r4 – Current question is about a risk factor that, depending on its state, may change the statistical relevance of the conditions significantly. Returned possible values include:

  • observation_params - a one-element set, the risk factor
  • condition_params - a one-element set, the condition the risk factor is most significant to

• r5 – No longer used.

• r6 – Current question is about the most important observation out of those directly related to the evidence provided. Returned possible values include:

  • observation_params - a one-element set, the source observation
  • condition_params - empty