Please note that at this current time, these services are not available for use in a live environment and must not be used. The following information is made available in advance of go-live
At this time, the APIs and algorithms are not registered as devices by the MHRA.
Background
Information about the research and algorithms that resulted in QRISK3, as well as the free to use Web site can be viewed at https://qrisk.org and a related presentation, a CVD lifetime risk at https://qrisk.org/lifetime/index.php
Predict Services
QRISK3 risk score can be calculated using Endeavour Predict services, which consist of:
- A set of Web based APIs for submitting requests for a prediction and receiving a response, the response including a risk score, and other score specific information for example in QRISK3, a heart age , and information relating to the calculation of the scores.
- A set of FHIR APIS to enable system suppliers to know which Snomed-CT concepts should be used when deriving information from records. These are part of the Endeavour information model services
- A REST API for deriving a Townsend deprivation score from a post code, the Townsend score being then submitted as part of the QRISK request payload.
- Source code repositories of open source code used by 1) and 2) and 3)
Concept sets
Concept sets for use in QRISK3 can be seen in the Endeavour Information manager at
https://im.endeavourhealth.net/#/directory/folder/http:%2F%2Fapiqcodes.org%2Fqcodes%23QPredict_331
In line with FHIR an semantic web standards, each set is given a unique IRI and it is the IRI that is used as identifiers in the APU call
Alternatively, the concept sets can be downloaded from the IM application in excel, at
APIs
A developer portal for qrisk3 is available at https://dev.endeavourpredict.org/
With FHIR value sets at
https://im.endhealth.co.uk/nodeapi/doc/#/default/get_ValueSet
The concepts sets contain subsets so that recursive calls can be made to obtain each set. Alternatively, using the $expand operation, the entire subset can be obtained as one.
Source code
The source code for the APIs can be viewed on Github at
https://github.com/endeavour-predict/qrisk3-dotnet
Note that the source code is made available under the GNU public license.
However, the use of QRISK3 as a registered trademark is not an open license and terms and conditions apply to its use.
Query Rules for health records
Systems may have access to longitudinal health records, in particular those held in General Practice. In that case those systems may elect to query the health record data in a way that provides likely values for the variables, passed to the function as parameters to the QRISK function.
In this case, a set of query criteria and rules are applied to the record entries and the values of the variables derived from those entries. These are then presented to a user for confirmation or amendment before being submitted via the API.
It is strongly recommended that for any individual decision, or when an entry of a risk score is into a record is being considered, that each set of assumptions are confirmed by the user. However, purely automated calculations may be used for population based risk stratification.
Reference date
Scores may be calculated in real time or retrospectively. The reference date (current date or past date) is used for all time dependent values, which means values as they would have been on the reference date. For example when looking for dates within 6 months this means 6 months prior to, or at the time of, the reference date and all entries subsequent are ignored.
Patient inclusion criteria
This section documents the criteria for a person suitable for the application of QRISK3
- Aged between 25 and 84 inclusive at the reference date
• Free from a diagnosis of cardiovascular disease (qr: group 411 see below) on or before the reference date
Independent variables as function parameters
QRISK® operates as a function whose parameters represent independent variables. The API accepts these arguments as JSON key value pairs (or lists) in the payload of the request.
The values of those variables, when used in the algorithm are derived in one of two ways
a) By direct entry by a user
b) By a query of a health record.
When passed into the algorithms as arguments to the function, the values are presented either as a double, an integer, a boolean 1 or 0, or a character. The client must convert to these formats before submitting in the payload using the maps as documented below.
If variables are unknown (missing) or their values are out of range, the algorithm may either reject the request, provide a default value for the parameter, or adjust an out of range value to an outer limit. The way the algorithm handles these parameters are documented below in the relevant parameter.
Health records contain entries that have a property of a main concept (e.g. a systolic blood pressure), an effective date (the date of relevance to the observation or action), and a numeric value. For the purpses of these rules, concepts are grouped into named sets
Each concept set is universally identified with an IRI (which is in the format of a URL) and the base iri namespace for Q concept sets is http://apiqcodes.org/qcodes#. When used in the below tables, for clarity, the iri prefix "qr:" is used.
Input parameters needed to calculate a QRISK3® score and their handling are as follows:
Row ID
Optional Integer.
Used by the client as a reference when a batch API is used. i.e. returned by the result. It has no scope beyond the API request/response
Age
Mandatory Integer. Age of the person in years at the reference date
Gender
Mandatory Character 'M' or 'F'.
Male or female.
Binary values only accepted. QRISK does not have information on transgender or indeterminate gender risks at this stage. It is the responsibility of the requester as to whether to apply the higher risk M gender e.g. For Trans Women and to explain the rationale.
Cardiovascular disease
Optional Boolean
Cardiovascular disease prior to the reference date
This is an inclusion criteria and should therefore be 0. The request will be rejected if this is set to 1
Default handling of unknown is false Rule
Observation concept qr:411 effective date < reference date
Atrial fibrillation
Optional Boolean.
Atrial fibrillation at any time prior to reference date.
QRisk does not differentiate a single one off AF event from chronic or intermittent AF. Clinical interpretation may be required for those with a single event many years ago.
Default handling of unknown is false
Rule
Observation concept qr:24 effective date < reference date
Erectile dysfunction (impotence)
Optional Boolean.
Erectile dysfunction at any time prior to reference date or treatment with drugs for dysfunction with at least 2 issue, the latest of which is within 28 days of the reference date.
QRisk does not differentiate a single one off dysfunction event from chronic or dysfunction. Clinical interpretation may be required for those with a single event many years ago.
Default handling of unknown is false
Rule
Observation concept qr:59 effective date < reference date or ( MedicationRequest medication qr:1683 effectiveDate <= reference date count (entries)>1 latest 1 as LastImpotenceDrug and LastImpotenceDrug effectiveDate range -20 to 0 days before reference date )
Atypical anti psychotics
Optional Boolean
Second generation ‘atypical’ antipsychotic - prescribed two or more issues in the previous 6 months (includes amisulpride, aripiprazole, clozapine, lurasidone, olanzapine, paliperidone, quetiapine, risperidone, sertindole, or zotepine)
Default handling of unknown is false
Rule
Medication request medication in qr:1169 effective date range -6 to 0 months relative to reference date Count(entries)>=2
Systemic corticosteriods
Optional Boolean
Systemic corticosteroids –prescribed two or more issues in the previous 6 months
Default handling unknown is false
Rule
Medication requests medication in qr: 1194 effective date range -6 to 0 months relative to reference date Count(entries) >=2
Migraine
Optional boolean
Diagnosis of migraine prior to the reference date.
Default handling of unknown is false
Rule
Observation concept in qr:39 effective date <= reference date
Rheumatoid arthritis
Optional boolean
Diagnosis of Rheumatoid arthritis prior to the reference date
Default handling of unknown is false
Rule
Observation concept in qr:58 effective date <=reference date
Chronic renal disease
Optional boolean
Chronic renal disease at any time prior to the reference date
Default handling of unknown is false
Rule
Observation concept in qr:322 effective date <= reference date
Severe mental Illness
Optional boolean
Diagnosis of severe mental illness (psychosis, severe depression, manic depression, schizophrenia) at any time prior to the reference date
Default handling of unknown is false
Rule
Observation concept in qr:3187 effective date <=reference date
Systemic lupus erythematosus
Optional boolean
Diagnosis of systemic lupus erythematosus at any time prior to the reference date
Default handling of unknown is false
Rule
Observation concept in qr:70 effective date <= reference date
Treated hypertension
Optional boolean
Diagnosis of hypertension at any time in the patient’s records AND On antihypertensive treatment if 1 or more medication requests within 6 months prior to the reference date.
Default handling of unknown is false
Rule
Observation concept in qr:21 effective date <= reference date) AND Medication request medication in (medication qr:740 qr:751 qr:759 qr:760 qr:765 to be revised) effective date range -6 to 0 months relative to reference date
Body mass index
Optional double
The most recently recorded body mass index for the patient recorded prior to the reference date recorded in the last 5 years.
Default handling of unknown is estimate.
Rule
Observation concept in, qr:200 effective date range -5years to 0 time relative to reference date. Most recent entry
Handling of out of range values by the calculator
<18 is set to 18, >47 is set to 47
Diabetes Category
Optional integer 0 or 1 or 2
Categorical variable to denote no diabetes, type 1 diabetes or type 2 diabetes diagnosed at any time prior to the reference date
Default handling of unknown is 0
Rule
Match Observation concept in qr:1913,qr:2411 isMemberOf DiabetesSet effective date <=reference date Most recent entry Return DiabetesSet map
SetMap | Name | Map |
---|---|---|
qr:1913 | Type 1 diabetes | true |
qr:2411 | Type II diabetes | 2 |
Ethnicity
Optional integer between 0 and 17
Ethnic category
Default handling of unknown is 0
Rule
Match Patient ethnicity in (qr:17071, qr:17072, qr:17073, qr:17074, qr:17075, qr:17076, qr:17077, qr:17089, qr:17079, qr:17080, qr:17081, qr:17090, qr:17985, qr:17086, qr: 17087) isMemberOf EthnicitySet Return EthnicitySet Map
Ethnicity set | Name | Map |
---|---|---|
null | 0 | |
qr:17071 | White british | true |
qr:17072 | White Irish | 2 |
qr:17073 | Other White Background | 3 |
qr:17074 | White & Black Caribbean | 4 |
qr:17075 | White & Black African | 5 |
qr:17076 | White & Asian | 6 |
qr:17077 | other mixed | 7 |
wr:17089 | Indian | 8 |
qr:17079 | Pakistani | 9 |
qr:17080 | Bangladeshi | true0 |
qr:17081 | Other Asian | true1 |
qr:17090 | Caribbean | true2 |
qr: 17083 | Black African | true3 |
qr:17091 | Other Black | true4 |
qr:17985 | Chinese | true5 |
qr:17086 | Other ethnic group | true6 |
qr:17087 | Not stated and not classified | true7 |
Family history of Coronary heart disease
Optional boolean
Family history of coronary heart disease in a first degree relative under the age of 60 years recorded before the reference date
Default handling of unknown is false
Rule
Observation concept in qr:404 effective date <= reference date
Total cholesterol HDL ratio
Optional double
The most recent ratio of total serum cholesterol/HDL recorded in the last 5 years. The ratio is either directly directly recorded (eg using group 405) or can be calculated using total cholesterol divided by hdl.
Note that the person must either have a ratio or both a total and hdl value.
Default handling of unknown is estimate
Rule
Observation concept in qr:16 (total cholesterol TC) effective date <=reference date - MOST recent as TC Observation concept in qr:367 (HDL) effective date <=reference date - MOST recent as HDL Observation concept in qr:405 (CHDL ratio) effective date <=reference date MOST recent as TCHDL If TCHDL effective date > TC effective date OR TCHDL effective date >HDL effective date then value= TCHDL numeric value else if TC effective date > TCHDL AND HDL effective date >TCHDL effective date then value = TC / HDL else value = null
Handling of out of range values by calculator <1 is set to 1, >12 is set to 12
Smoking category
Optional integer 0, 1 ,2 ,3 or 4 default 0
Category variable The most recently recorded smoking status with 5 levels
This categorisation has one group for ex-smokers rather than trying to distinguish between ex light, ex moderate and ex heavy smokers.
This categorisation does not distinguish between cigarette/cigar and pipe smokers
Special consideration should be given to records that contain both numeric values for the number of cigarettes smoked, and concepts that categorise into light moderate or heavy.
The logic on non smoker is that from the entry of the most recent if it has a numeric value or if there other codes on the same day with numerics take the numeric value on the same day as the most recent, unless the most recent is non smoker
Default handling of unknown is 0
Rule
Observation concept in (qr:2239 -(NONE), qr:2238 (EX) , qr:2244 (LIGHT), qr:2242 (MODERATE), qr:2243 (HEAVY) isMemberOf SmokingSet effective date <=reference date numeric value is NULL as NOVALUE Observation concept in (qr:2239 -(NONE), qr:2238 (EX) , qr:2244 (LIGHT), qr:2242 (MODERATE), qr:2243 (HEAVY) isMemberOf SmokingSet effective date <=reference date numeric value not null as HASVALUE Sort by effective date time descending. If most recent is NOVALUE (as MOSTRECENT) if most recent HAS VALUE effective date= MOSTRECENT effective date // non value and value on same date! then value is numeric map of HASVALUE numeric value else value is concept map of NOVALUE concept else if most recent is HAS VALUE value is numeric map of MOSTRECENT numeric value else no record value is null
Smoking set Map
Code Group | Name | Map |
---|---|---|
qr:2239 | None smoker | 0 |
qr:2238 | Ex Smoker | true |
qr:2244 | light smoker | 2 |
qr:2242 | Moderate smoker | 3 |
qr:2243 | Heavy smoker | 4 |
Numeric map
Range from to | Map |
---|---|
0 -9 | 2 |
true0- 19 | 3 |
>= 20 | 4 |
Systolic blood pressure
Optional integer
The most recent systolic blood pressure within 5 years prior to the reference date
Default handling of unknown is estimate
Rule
Match Observation concept in qr:198 Systolic blood pressure effective date >- -5 years to 0 time relative to reference date Most recent entry Return numericValue
Handling of values out of range <70 is set to 70, >210 is set to 210
Standard deviation of systolic blood pressures
Optional double
The SAMPLE style Standard deviation of all of the available systolic blood pressures prior to the reference date recorded in the last 5 years
Rule
Match Observation concept in qr:198 Systolic blood pressure effective date >- -5 years to 0 time relative to reference date as Systolics Return Standard deviation (sample) (Systolics)
Townsend score
Optional double
The Townsend score associated with the output area of a patient’s postcode based on the 2001 census data.
Available via API
Default handling of unknown is 0 (the mean of the national scores)