Dashboard stats v3 specification

The aim of this piece of work is to align the dashboard stats library to align with the current (2026) pivot away from solely powering the visualisations in the ukrdc app and more use in the ukka core activities.

1. Dashboard Stats Library

1.1 Generic Calculators

The current pattern of the dashboard stats ties the generation of cohorts very closely the calculators themselves. Furthermore the generation of unaggrated data is retrofitted to the mechanics of producing visualisations for the ukrdc-app. In this release the different components will be decoupled and the calculators will largely be used to compose together the functionality for convenance.

The core calculators, KRT and CKD will remain however they will be instances of a generic pattern which will allow easy and rapid prototype and development of custom calculators, cohorts and measures.

An unaggregated cohort containing the patient identifiers labelled by the attributes used to aggregate them will be more central and will include caching functionality to allow reports to be produced without the requirement to re-query the database.

1.1.1 Scale and Granularity

The sendingfacility level calculator will continue to be central however it may be useful to supplement with different geographical sub division. These could be country, region or “all ukrdc”. There may be more subtleties here if we go beyond the practical “who is sending patient” to “where is patient from”.

1.1.2 Caching of data

To support the performance of the library a configurable cache which stores the dataframe for an unique set of parameters for which it has been called. This should be configurable so that they can be stored both in redis and as local files.

1.2 Cohorts

Cohorts will be calculated with self contained stand alone functions which input the run parameters and output a dataframe containing (at least) one row per patient with identifiers.

UKKA cohort definition

1.2.1 CKD

https://renalregistry.atlassian.net/wiki/x/AQAd2Q

Regarding CKD.i is CKD patient who turns 18 incident or prevalent?

SS: They would appear as incident CKD paeds at the age they first met the remaining parts of the definition, and would be part of prevalent CKD adult from when they turn 18.

Do we require CKD.iv when CKD.iii is true?

SS: Yes I think think so but I’m not sure if you would have anyone on conservative care with an eGFR over 30.

The UKRDC definition where CKD.iv is true isn’t strictly true to the UKKA definition. If changed to the most recent creatinine what is the reference date? are we comfortable with the idea of patients hopping in and out of the CKD cohort. Should we use knowledge of the future to correct the cohort i.e if a patient recovers kidney function at a later date than the reference date should the be reclassified as AKI

SS: I think that in clinic a patient can move to less severe CKD stage if kidney function recovers, so I think that we should be happy with them coming out of the cohort. I am not sure about the recvery as the definitions for AKI are different to CKD.

Should the concept of proper start be included within the CKD.ii and CKD.iii definitions?

SS: Do you mean “do they comply with the definition for at least 90 days” similarly to the idea of a proper KRT start? If we did that, I think we might as well use the chronicity (2 eGFR<30 separated by at least 90 days) as that is the standard definition.

Incident cohort definition

CKD.i AND (CKD.ii or CKD.iii with no prior record of treatment and beginning within the incidence window) AND CKD.iv

SS: I think we could leave age out of the definition, and just subset by age as needed. Is it possible for someone to be in the UKRDC with an eGFR<30, no KRT code, but also no CKD/CONS modality? Do we need to add time point conditions to CKD.iv? I think this measurement needs to be in the window, with no prior CKD.iv - though this is complicated if we allow people to drop in and out.

Prevalent cohort definition

CKD.i AND (CKD.ii or CKD.iii overlapping with the prevalence point) AND CKD.iv

SS: Ditto above comments. For CKD.iv, do we need to put a time condition on the measurement?

1.2.2 KRT

Incident

new_dialysis = ( IN_KRT.i AND IN_KRT.ii AND (KRT.iv OR KRT.viii)) SS: don’t quite follow the logic of requiring iv and viii

new_transplant = (KRT.iii AND KRT.i) SS: also need to not be on dialysis prior to transplant, or have a previous transplant. Or do you mean any new transplant?

incident_krt = (new_dialysis OR new_transplant ) NOT KRT.iix NOT KRT.vii SS: Again I’m a bit confused about the extra conditions vii and iix

KRT.vi is not currently part of the definitions but it should be.

Need to add a distinction between acute and chronic codes. In the existing annual report cohorts, we treat these differently because those who die or stop treatment without recovery before 90 days are counted as incident if they are coded as chronic, but not if they are coded as acute.

Prevalent

(KRT.ix or KRT.x)

1.2.3 Quarterly extract / catch all cohort

Possibly can be deprecated. Was aimed at the demographics visualisation on the app.

1.2.4 Custom Cohorts

Within the constraints outlined custom cohorts can easily be created using stand alone functions.

1.3 Labellers

Labellers will take as an argument a patient cohort and will output the same cohort with additional columns containing information describing the data. Some preconditioned will be required along with the associated error handling to ensure that the required columns are in place. Sometime the column may already exist in which case the labeller will replace it.

Unless otherwise specified the data will be extracted from the feed from the unit to which the patient belongs. There may be other instances where existing columns in the cohort may be overwritten by a labeller. The labellers may also filter the rows of the cohort.

1.3.1 Demographics

Appends the gender, age and ethnicity to a cohort.

1.3.2 Adult/Paed

UKRDC patients aren’t explicitly labelled as Paediatric patients. If they are contained within a feed which logically maps to a paediatric centre the centre_code (sendingfacility) is mapped to it. This is relatively imprecise currently and should be formalised in the UKRDC as a feedshare relationship. Conversely where this is the case, i.e where the healthcarefacilitycode is a paediatric centre the patient should also be labelled as paed.

Where a patient is under 18 and is at an adult centre they should be filtered out of the cohort.

1.3.3 IMD

The index of multiple deprivation is available as a lookup against postcode on the ons website. This data will be linked to the postcode data in the UKRDC address table. These should be deduplicated in order of addressuse = ('H', ‘PST', 'TMP', null).

1.3.4 Dialysis frequency

Patients coded as HD will be labelled with a binned dialysis frequency. This is calculated by querying the dialysis session count (from the dialysis session table) per week. This is then used for the calculation of the median figure for each patient which is then binned using pandas.cut.

1.3.5 Time on dialysis

As above but with the time dialysed.

1.3.6 KRT Care planning

This is calculated from the UKRDC adjacent removed_xml_archive. This contains data from version 4+ of the RDA schema which is removed from the xml before being loaded into the UKRDC. The KRT careplanning information will be linked to the UKRDC data using the mrn (usually the nhs number). The assessments are filtered by outcome code in ["1", "2", "3"] and assessmenttypecode == "KRTassess"

1.3.7 TPLT Care planning

As above but assessmenttypecode = ““

1.3.8 Custom measures

The new pattern should allow new labellers to easily extend existing.

1.3.9 Record Completeness

To be specified.

1.4 Utilities

1.4.1 Cohort aggregation

1.5 Feed Deduplication

In the UKRDC there can be competing information for individuals as there is one per patient per centre (See here and here). This means a patient (ukrdcid) which has been seen at multiple centres will have multiple feed (pid) so there may be multiple sources of truth for things like demographic information. In theory the validation should flag some discrepancies in things like dob.

The dashboard stats library will treat the record from the first centre a patient is seen at as the canonical one. The practical consequence of this is that data should generally be linked with the pid rather than the ukrdcid.

Linking with the ukrdcid is important when it comes to constructing a continuous treatment timeline and identifying to which centre a patient belongs to.

1.6 Validation

Possibly a future/nice to have but this could be functions which run on a cohort that has been extracted to determine if the data is good enough. Perhaps in a similar vein to how data isn’t published in the annual report if the completeness isn’t above a certain threshold.

On a patient level you can imagine validating the way they are labelled. For example, HD patients could be validated by vascular access procedures or dialysis sessions. Validating acute starters by checking whether they have dialysis sessions and observations would improve the accuracy of incident cohorts.A simple addition would be to validate totime against death dates.

1.7 Caching

To revisit the ideas around not running every query all the time.

2. UKRDC App

2.1 Continued support and expansion of visualisations

The ukrdc dashboard app frontend is written in vue and the backend is python-fastapi. This leans heavily on the current pydantic structure to automatically produce documentation and the typescript client required by the frontend. To continue supporting the visualisations in the dashboard the parts that aggregate the data will need to be moved to fastapi along with their relevant pydantic structures.

2.2 Reporting against cohorts

The expanded use of unaggregated cohorts should allow for downloadable reports on the frontend to allow units to drill down into the data for individual patients.

3. Tableau Extracts / Public Dashboard

To be expanded.

3.1 Simplify with new library interface

3.2 Static webapp / dashboard

Successor to tableau