QRISK3

From Endeavour Knowledge Base
Revision as of 13:02, 9 February 2024 by DavidStables (talk | contribs)

QRISK3 APIs and local run time ccomponents are now registered as a class 1 device with the MHRA and available for use

UK-CA.png


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:

  1. 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 , as well as information relating to the calculation of the scores.
  2. A local run time C# or Java jar version for integration into local systems that prefer not to use a web UI.
  3. 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.
  4. 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.

Concept (Value) sets and FHIR API

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 API call

Alternatively, the concept sets can be downloaded from the IM application in excel CSV , or TSV

Within Endeavour each concept is given a unique identifier or IRI in line with semantic Web. Users will be more familiar with the use of the concept's code and this is provided as well as maps to alternative code schemes.

the concept sets are available as FHIR value sets at the self sign up developer portal

https://dev.endeavourpredict.org/

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.

APIs (Web and local)

A developer portal for qrisk3 is available at https://dev.endeavourpredict.org/

The algorithms are available over the internet via REST API calls or a locally deployed .NET assembly, or a locally deployed Java jar. In all 3 variations the input format (JSON) and parameters are the same and the result format (JSON) is the same. Consequently suppliers using local versions may use the developer portal to test input and output formats.

When using a locally deployed implementation, a test pack SDK is provided to enable unit and integration testing by end suppliers.

Source code

The open source code available under Lesser General Public License on the https://qrisk.org/src.php

Please note that the use of QRISK3 (as a registered trademark) is not available to be used under the LGPL license as this trademark is owned by EMIS and Nottingham University and a license to use is required. Endeavour-Predict has a license and is able to sublicense along with the deployed implementation under commercial or academic terms.

User instructions

The REST API instructions are available at a Swagger at https://dev.endeavourpredict.org/

To the local batch processor the instructions for Windows are:

  1. Unzip the published pack to any folder
  2. Unzip the test data to another folder

To test

  1. Take a copy of the test data and place in another folder
  2. using the windows command line execute the EP_QRisk3.Batch.exe with a parameter pointing to the test folder
  3. Note that the output is regenerated as output files. The can, if wished be compared against the original provided result files as they should be identical

To run

  1. Generate source data as JSON files in the format as provided (which is the same as the API format)
  2. Using the command console, execute the EP_QRisk3.Batch.exe with a parameter pointing to the source folder.

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 10
qr:17081 Other Asian 11
qr:17090 Caribbean 12
qr: 17083 Black African 13
qr:17091 Other Black 14
qr:17985 Chinese 15
qr:17086 Other ethnic group 16
qr:17087 Not stated and not classified 17


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)

Retrieved from ‘https://wiki.endeavourhealth.org/index.php?title=QRISK3&oldid=7000’
Last modified
This page was last modified on 9 February 2024, at 13:02.