Performing Risk Assessment
/risks POST
This endpoint allows to generate assessment of personalized risks for a patient.
Parameters
This is a POST endpoint, and it takes information about a patient encoded as the evidence data structure as the input.
Example of evidence for a 35-year-old patient who is an active smoker (N00004), decided not to disclose his drinking habits (N00007) and with diagnosed hypertension (node id C00020) and complaining about cough that lasts over a month (N04116). Additionally, to show error reporting, we included an incorrect node identifier that is present in the API (N09999).
{
"sex": "MALE",
"age": 35,
"observations": [
{
"nodeId": "C00020",
"outcome": "present"
},
{
"nodeId": "N00004",
"outcome": "active_smoking"
},
{
"nodeId": "N00007",
"outcome": "unknown"
},
{
"nodeId": "N04116",
"outcome": "cough_more_4_weeks"
},
{
"nodeId": "N09999",
"outcome": "present"
}
]
}
Response
The endpoint is intended to provide risk assessment and predictive health overview information based on the patient data. The response consists of a list of medical conditions and statistics related to predicted overall state of the patient's current and the future health.
As a part of response, a personalized list of conditions is returned. It is ranked by the influence on the patient's overall health using the risk grade. The risk grade is a combination of personalized likelihood of a condition, it's lethality, and severity of influence on the quality of life, etc.
The health score is an abstract indicator of patient's health based on provided information about the patient. It is an integer value in the range of 0 to 1000, where higher values indicate better overall health. A representative value of a generally healthy individual is in range of 700-800. The value is derived from the evidence provided and personalized risk assessment. As the health score is affected by age an average value for a person of the same age and sex as the patient but without any additional information provided, can be calculated and used as a reference value.
The lifetime is intended to represent an average expected lifetime based on information provided on the patient. This assessment will change as more information is provided. The value is calculated based on patient's age, sex, assessment of personalized predicted risks, etc. This assessment will change with additional information provided. It is worth noting that the estimation is currently based on the US life expectancy statistics, for the use on the population from the outside of the US please contact Kyla team. The API provides additionally an average lifetime estimation which is based on a person of the same age and sex as the patient but with no other information provided.
To help interpreting the health score, the API provides a basic definition of suggested value ranges. The ranges currently are: Bad, Poor, Fair, Good, Excellent. They are defined as key-value pairs, where the key is a number and the value is a text. The key is an upper limit of range (e.g. Excellent has always 1000.0) and the value is a description (e.g. Excellent).
The response structure is defined as follows:
- success - indicates if the query was successfully executed (values true or false)
- data - query specific data
- conditions -
- nodeId - node identifier of a node related to a suggested diagnosis
- title - a human-friendly description of the node
- probability - a numeric value between 0 and 1 corresponding to the likelihood of the diagnosis
- riskGrade - an integer value between 0 and 100 corresponding to the risk assessment related to this condition
- healthscore - an integer value between 0 and 1000 capturing overall health of the patient
- averageHealthscore - an integer value between 0 and 1000 capturing average value of healthscore for the population of the same age and sex as the patient
- lifetimeYears - a numeric value that corresponds to estimated patient's life span in years (fractional values are provided)
- averageLifeTimeYears - a numeric value that corresponds to estimated life span in years (fractional values are provided) for a person of the same age and sex as the patient but with no other information provided
- healthscoreRanges - definition of ranges for the health score to help interpret it:
- key - a numeric value indicating upper bound for the link, a real value greater than 0 and up to 1000.0, sorted ascending
- value - description of the range (e.g. poor)
- conditions -
- errors - a list of (possibly non-critical) errors that occurred during the query processing
- code - code for type of error (e.g. INVALID_UUID)
- message - human-friendly description of the error
A representative response to the query presented above may look like:
{
"success": true,
"data": {
"conditions": [
{
"nodeId": "C00020",
"title": "Hypertension",
"probability": 1,
"riskGrade": 5
},
{
"nodeId": "C02120",
"title": "Laryngeal Cancer",
"probability": 0.4761357009410858,
"riskGrade": 2
},
{
"nodeId": "C00871",
"title": "Metabolic Syndrome",
"probability": 0.6290394067764282,
"riskGrade": 2
},
{
"nodeId": "C00857",
"title": "Hyperlipidemia",
"probability": 0.3439311385154724,
"riskGrade": 2
},
... continued ...
{
"nodeId": "C02911",
"title": "Zika Virus Infection",
"probability": 9.978554516010263e-8,
"riskGrade": 0
}
],
"healthscore": 274,
"averageHealthscore": 596,
"lifetimeYears": 66.1703170345557,
"averageLifetimeYears": 82.86906086594102,
"healthscoreRanges": {
"105.11595547309835": "Bad",
"489.7907647907649": "Poor",
"593.6710216320412": "Fair",
"746.6269841269846": "Good",
"1000.0": "Excellent"
}
},
"errors": [
{
"code": "INVALID_UUID",
"message": "No observation with uuid: N09999"
},
{
"code": "INVALID_UUID",
"message": "Invalid uuid: N09999"
}
]
}