Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve example codelist use in ehrql example docs #2266

Open
madwort opened this issue Dec 2, 2024 · 1 comment
Open

Improve example codelist use in ehrql example docs #2266

madwort opened this issue Dec 2, 2024 · 1 comment

Comments

@madwort
Copy link
Contributor

madwort commented Dec 2, 2024

somehow I'd not seen this paragraph before

https://docs.opensafely.org/ehrql/how-to/examples/#some-examples-using-codelist_from_csv

For example, instead of:

asthma_codelist = codelist_from_csv("XXX", column="YYY")

you will need a line more like:

asthma_codelist = codelist_from_csv("your-asthma-codelist.csv", column="code")

which provides the filename your-asthma-codelist.csv and the name of the CSV column with codes.

It was previously clear to me that XXX/YYY were placeholders, but I'm not sure that it would be to researchers, especially as the rest of the document is all example usage rather than placeholders. I propose going through the examples & replacing the placeholders with example usage, e.g.

https://docs.opensafely.org/ehrql/how-to/examples/#does-each-patient-have-a-clinical-event-matching-a-code-in-a-codelist

from ehrql import create_dataset, codelist_from_csv
from ehrql.tables.core import clinical_events, patients

asthma_codelist = codelist_from_csv("XXX", column="YYY")

dataset = create_dataset()
...

to

from ehrql import create_dataset, codelist_from_csv
from ehrql.tables.core import clinical_events, patients

asthma_codelist = codelist_from_csv("asthma-codelist.csv", column="code")

dataset = create_dataset()
...
@evansd
Copy link
Contributor

evansd commented Dec 2, 2024

I'd be happy to see the XXX placeholders go, but whatever we replace them with it needs to be obvious that, when a researchers copies it verbatim into their project and it doesn't work, it's because they haven't changed something they were supposed to change rather than that there's something wrong with the example.

Of course, when we finally fix codelist management we'll be able to use real codelists here 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants