Why I teach a workshop on codelists

Imagine that you are a new PhD student or post-doc who has just been given access to a large primary care dataset and a research question about patients with a cough. The first thing you need to do is figure out how to identify patients with a cough in the dataset. The data contains SNOMED CT codes for each clinical event, so you need to find the codes that correspond to a cough. How do you go about doing this?

If you were to google “SNOMED CT cough codes”, you would get a mix of resources, and you might find your way to a SNOMED browser. In the UK, we often use the SNOMED CT browser - which is provided free of charge by the NHS. You open the browser, type in “cough”, and get back 1115 matches (as of autumn 2026). Some of these are obviously what you want and some are definitely not. The problem is that there are a great many that sit somewhere in between, such as “history of whooping cough” or “psychogenic cough”. Decisions about whether to include these codes are individual to the study design and research question and require careful consideration. At this point, you might start clicking through the list, and noting down the ones that seem right. You have just started building a codelist, and whilst the process may seem straightforward, even tedious, the choices you are making while clicking will decide which patients are in your study.

What is a codelist and why does it need teaching?

So as we just saw, a codelist is a list of clinical codes that together represent a single clinical concept, such as “cough” or “type 2 diabetes”. It allows researchers to systematically identify patients with that concept in electronic health records. I have written about this in more detail in What is a Codelist?.

But why do we even need codelists? Surely there is only one way to record that a patient has a cough? Alas, no. The reality is that there are many different codes that can represent a cough and the choice of which ones ends up being in the clinical record, and hence your dataset, is determined by clinicians and their coding practices. Clinicians record what happens in a consultation primarily for clinical care rather than for research. They start typing “cough” into the software, and select the term that best matches what they observed. This is usually a dropdown menu of options within the electronic health record system. The term they select is then recorded as a code, and this is what ends up in the dataset you are working with. Clinicians will pick whatever term they think best represents the patient’s condition, and this can vary widely between clinicians and contexts.

This variability in coding practices means that if you want to identify all patients with a cough in your dataset, you cannot rely on a single code. You need to consider all the possible codes that clinicians might have used to record this condition. This is where a codelist becomes essential: it is a curated collection of all relevant codes that together capture the concept you are studying. Each code you include or leave out is a scientific decision about who counts as having the condition of interest. Two researchers studying the same condition can end up with different populations if their codelists differ.

Despite this, building a codelist is often treated as a mundane task rather than a methodological challenge, and importantly it is rarely given the attention it deserves in research training.

When I first started in epidemiology, I had to learn how to build codelists on the fly, often by looking at what others had done - for example inheriting a spreadsheet of codes from a colleague and trying to make sense of it - or trying to figure it out from scratch by searching the code browser and making judgement calls about which codes to include. The issue that you quickly run into is that you need a systematic approach to ensure that your codelist is comprehensive and reproducible. It is too easy to think you will remember why you included or excluded a particular code, but without documentation, this reasoning is quickly lost.

Teaching codelists explicitly helps students and early career researchers understand that this is a methodological decision, not just a clerical task. It gives them the tools to approach codelist building systematically, document their reasoning, and critically evaluate existing codelists rather than accepting them at face value.

Why did I start teaching codelists?

I started teaching codelist workshops somewhat accidentally after I was asked to give a session on health data methods and realised that many students and early career researchers had little understanding of how to build codelists systematically. I found that by focusing on this often-overlooked aspect of research, I could provide practical skills that were immediately useful and also highlight the methodological thinking behind it. It also allows me to teach about reproducibility and the importance of documenting research decisions - which extends far beyond just codelists themselves.

In the last couple of years, I have been asked more and more to run codelist workshops. This has reinforced my belief that there is a real need for explicit training in this area.

What the workshop covers

The workshop is 3 hours long, for up to 30 people, and is made up of short lectures of 10 to 20 minutes with group work in between, plus around 30 minutes of pre-reading. I have delivered this at multiple universities, including the University of Glasgow and Queen Mary University of London.

We work through a single scenario for the whole session, which is building the codelists for an epidemiology study that asks:

Do Type 2 diabetics receive more oral antibiotics for their coughs than non-diabetics?

I like this question for teaching because it needs several codelists that are quite different from each other - one for the population of Type 2 diabetics, one for the exposure of cough and one for the outcome of oral antibiotics - and so it gives us a reason to try different approaches to making them. We start with why health data requires codelists at all and how a clinical encounter becomes coded data, and then work out which codelists the study needs before building anything.

From there, the groups work up a new codelist from scratch, which means writing down inclusion and exclusion criteria first and then searching for codes systematically. We then look at reusing a codelist that someone else has already made, including how to find one, the pros and cons of doing so, and what to look out for, as a codelist that was built for an asthma study might not suit a question about diabetes and antibiotics. I walked through both of these approaches in How to Create a Codelist, which uses the same scenario.

The last part of the session covers the existing tools for managing, sharing and comparing codelists, and how to document a codelist so that someone else could understand the decisions behind it and reproduce it. By the end, participants should be able to define what a codelist is, describe how clinical encounters become coded data, construct a codelist using a systematic search, refine it with inclusion and exclusion criteria, and document what they did in enough detail for it to be reproduced.

Running it for your group

I run this workshop through my company, Parakeet Consulting, and I provide the slides, worksheets, reading material and references so that they can be distributed afterwards. The format above is the one I have delivered so far, but I am happy to modify it to suit a particular course or team. The details are on the codelist workshop page.

Conclusion

Codelists decide which patients end up in a study, and so I think the skill of building one should be taught deliberately, with time to practise on a real question and to argue about the borderline codes in a group. So far I have run this workshop for university students, and I would like to adapt it for teams in industry who work with the same kind of data.

If you have questions about codelists or would like to discuss running a workshop for your team, feel free to get in touch.

Further Reading

• What is a Codelist? - why codelists are needed and why they are hard to get right
• How to Create a Codelist - building from scratch and adapting an existing codelist
• SNOMED and Friends - a deeper dive into SNOMED CT and its quirks
• Citing and Crediting Codelists - a post I wrote with Dr Jess Morley on provenance and reuse
• OpenCodelists - a repository of reusable codelists