Documentation

Welcome to the documentation for OpenSAFELY Codelists.

OpenSAFELY Codelists is an open platform for creating and sharing codelists of clinical terms and drugs.

Status of the project

OpenSAFELY Codelists is in active development. It's still rough around the edges, but has been used to create 1874 codelists since April 2020.

Anybody can use OpenSAFELY Codelists to create and share codelists.

See the section on future plans for upcoming features.

Viewing a codelist

The homepage of a codelist shows information about what the codelist contains and how it was created, as well as links to any references and details of who created the codelist.

The Full list tab shows a searchable list of codes and terms.

Most codelists have a Tree tab, showing all of the codes in the codelist in the context of other codes in the coding system. Codes that are not in the codelist are shown greyed out. This is helpful for seeing whether there are any accidental gaps in the codelist.

For codelists that were created with the builder, there will also be a Searches tab, showing the search terms that were used to create the codelist.

For all codelists, there are links for downloading a CSV of the codelist and a CSV containing a definition of the codelist.

If there are multiple versions of a codelist, links to these will be displayed on the left hand side.

Creating an account

You do not need an account to view codelists, but you do to create one.

Anybody can create an account. To do so, click Sign up in the top right of any page.

Creating a codelist from scratch with the builder

Our codelist builder tool helps you create a codelist from scratch, by searching terms and choosing which matching concepts should be included.

When signed in, click My codelists in the top right of any page.

Then click Create a codelist.

Choose a name for the codelist, and select a coding system from the dropdown. We currently support codelists using the following coding systems:

  • SNOMED-CT
  • ICD-10
  • CTV3 (Read V3)
  • BNF (British National Formulary codes)

Then click Create.

You'll be taken to a page that is nearly blank.

You build your codelist by searching for terms, and then choosing which of the matching concepts should be included in the codelist.

Any concepts that match your search term, and their descendants, are shown in a hierarchy.

In order to keep the page managable, only two levels of the hierarchy are initially visible. You can drill down the hierarchy by clicking the ⊞ button next to a concept.

You include a concept by clicking the + button, and exclude a concept by clicking the - button. When you include or exclude a concept, all of its descendants are also included or excluded. Explicity included/excluded concepts have buttons highlighted blue; their descendants have buttons highlighted grey.

If you have included or excluded a result by mistake, you can undo this by clicking on the include or exclude button again.

Sometimes a code can be in conflict. This happens when one of its ancestors in included and another is excluded. For instance, Acute severe exacerbation of mild persistent allergic asthma is a descendant of both Mild asthma and Acute asthma.

You can click on the ... to the right of the term to see more details.

There is a link to see just the concepts that are unresolved or in conflict.

Once you have included or excluded every search result, you are able to save your changes.

This takes you to the codelist's homepage, where you can edit metadata to provide a description, methodology, and links to references.

Creating a codelist from a CSV file

As well as creating a codelist from scratch, you can create one by uploading a CSV file.

From the My codelists page, click Create a codelist.

Choose a name for the codelist, select a coding system from the dropdown, and choose a file to upload from your hard drive.

Note that the CSV file should not have a header, and its first column must contain valid codes in the chosen coding system. (This limitation will be lifted.)

When you click Create the codelist will be created and you will be taken to the codelist homepage.

From here, you can edit any metadata. You can also edit the codelist.

Editing a codelist

You can edit a codelist that you have created. To do this, click Create new version on the left hand side of the codelist homepage.

This will open the builder, with all of the codes from your codelist selected. Additionally, if you created your codelist through the builder, then any terms you searched for will be present.

You can search for new terms, and you can change whether any concepts are included or excluded.

You can discard your changes by clicking Discard changes. You can also save a draft version of your codelist by clicking Save as draft. And when all concepts have been resolved, you can save your changes and create a new version by clicking Save changes.

Importantly, the original version of your codelist is still accessible at the same URL.

Using a codelist in OpenSAFELY research

Codelists are central to the research that is carried out in OpenSAFELY.

For more information about using codelists in OpenSAFELY research, see the OpenSAFELY documentation.

Future plans

Our future plans include:

  • improving curation of codelists
  • allowing users to record, within the tool, the reasons for their decisions
  • adding a system to let users subscribe to a codelist to be notified when it has changed
  • making it possible to build a new codelist based on a one that somebody else has made
  • building a system to ensure that codelist creators get credit for their work
  • and much more

Reporting bugs, requesting features, and asking for help

If you've found a bug or would like to request a feature, please raise an issue in the issue tracker on GitHub.

It you'd like support, try asking in the OpenSAFELY discussion forum.