NHSRPySOC 2025 - NHS-R/NHS.pycom Open Source Conference - Keynote

Friday 14th November 2024

Recording

Coming Soon!

Slides

Click here to open the slides in a new window.

Click here to open the code for the slides.

The Healthcare Services Analytics & Decision Science Atlas

Access the Atlas

Click here (https://atlas.hsma.co.uk/) to open the atlas in a new window.

Click here (https://github.com/hsma-programme/decision_intelligence_atlas) to open the code for the atlas.

Contribute to the Atlas

Head to the readme for the atlas to find out how you can contribute. You don’t need to know Quarto or GitHub to get involved in populating it!

Atlas Readme

Resources

The tapestry of reusability

GitHub

• HSMA session 7A details how to get used to GitHub with VSCode. You can find the session recording and slides on the HSMA modules page.
• The NHS-R statement on tools (Git and GitHub) page provides a range of useful resources relating to Git, including detailing a number of organisations who make use of Git/GitHub.
• There are also various NHS-R webinars available to help you get started with git/GitHub
  • NHS-R/NHS.pycom Conference Workshop 2023: Introduction to Version Control (Git/GitHub)
  • May 2023 Webinar: Version Control and RStudio

Template repositories

A lot of NHS organisations have created their own template repositories.

You may wish to use these as inspiration for setting up your own template, or just borrow them!

• NHS Digital rap-package-template: github.com/NHSDigital/rap-package-template
• NHS England SW Region template: github.com/nhsengland/SWRegionTemplate
• NHS England Repository template: github.com/nhsengland/nhse-repository-template
• Birmingham and Solihull ICS template: github.com/Birmingham-and-Solihull-ICS/BSOLproject
• Countess of Chester:
  • Python template: github.com/Countess-of-Chester-Hospital-NHS-FT/Project-Template-Python
  • R template: github.com/Countess-of-Chester-Hospital-NHS-FT/Project-Template-R

LICENCEs

Creating a licence via the GitHub ‘add file’ web interface

If you create it via Github, it helps you choose one and make the file!

What licence should I use?

• MIT and GPL3 are pretty decent options to start with
• ChooseALicence helps if you’re unsure

README.md

• A file called README.md in the repository root (i.e. the main folder of your repository), a ‘docs’ folder or a ‘.github’ folder will be picked up and rendered by GitHub when users open your repository
• Here are some tips from GitHub about writing a readme: docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
• GitHub readmes use markdown, similar to Quarto/rmarkdown, but with some of its own features and quirks: docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
• It’s also possible to draw attention to particular parts of your readme with special sections: github.com/orgs/community/discussions/16925

Bonus - a readme of you (or your organisation)

You

• If you create a repository and give it the same name as your GitHub username, then create a README.md file in this repository, this will show up as a readme when people visit your GitHub profile.
• This can be a great way to give visibility to certain projects you are working on or would like people to know about, with more flexibility than the pinned repositories feature.
• As someone who has been involved in recruitment of coders, I think this can really help you to shine. I wouldn’t necessarily be looking for it to be creative or pretty - but I’d value knowing which of your projects you think are worth highlighting and what they do.
• Here’s an example of mine.
  • I’m Bergam0t on Github.
  • My readme is in this repository: github.com/Bergam0t/Bergam0t
  • You can see it on my profile: github.com/Bergam0t
  • 
• Here are some more details from GitHub on this: docs.github.com/en/account-and-profile/how-tos/profile-customization/managing-your-profile-readme
• There are lots of cool examples out there
  • This is a great one from one of my colleagues: github.com/amyheather
  • And another one: github.com/TomMonks
  • Here’s a collection someone created: github.com/abhisheknaiidu/awesome-github-profile-readme
  • And another collection: github.com/coderjojo/creative-profile-readme

An organisation (e.g. your trust/ICB/team GitHub)

• For organisations, the repo name and structure is a little different, but the principle is similarThe HSMA organisation is similar
  • it’s hsma-programme on GitHub
  • The readme is in this repository: https://github.com/hsma-programme/.github
  • You can see it on our profile: https://github.com/hsma-programme
• Here are some more details from GitHub on this: https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile

Writing Docstrings

Python

• My preferred style is the numpydoc style, which is very human readable and is also supported by a range of documentation creation engines
  • you can see an example numpydoc docstring here
• Tools such as Claude.ai, Google Gemini, and ChatGPT are pretty good at
• Extensions for various IDEs exist to
  • e.g. autoDocstring for Python doctrings in VSCode

R

This isn’t my area of expertise!

But I believe the combo you are looking for is roxygen comments plus the roxygen2 package: r-pkgs.org/man.html

Documentation

Creating Documentation

Python

• pdoc is a pretty easy documentation package to get started with
• sphinx is very powerful, but has a bit of a steeper learning curve
• my favourite - and recommendation if you use Quarto or rmarkdown in any other capacity - is quartodoc
  • you can use all of your favourite Quarto extensions
• see some examples of how I’ve set it up:
  • example 1: the stlitepack documentation. _quarto.yml, repository, documentation
  • example 2: the vidigi documentation. _quarto.yml, repository, documentation

R

This isn’t my area of expertise!

But I believe the combo you are looking for is roxygen comments plus the pkgdown package: r-pkgs.org/website.html

Hosting Documentation

Various free options exist for hosting your sites.

I plan to write a slightly fuller walkthrough for this in future! But here are a few jottings to get you started.

GitHub pages

My favourite option is GitHub pages. If your work is already hosted on GitHub, this often makes a lot of sense.

Warning

Note that this is only possible only public repositories and the resulting site will also be publicly accessible (unless you are using GitHub enterprise).

In your repo, go to ‘settings’.

Select ‘pages’ in the menu on the left.

The quickest/easiest option is to ‘deploy from a branch’.

I prefer to publish from the /docs folder as this keeps everything neater. This will then look in the relevant folder for a file called index.html, which will become the homepage of your document.

Once you’ve done this, head over to the settings cog of your repository.

Opening this will give you a space to add a description of your repository, as well as add the link.

Ticking the ‘use your GitHub pages site’ option will automatically put a link to the site in the description.

Quarto and GitHub pages

If you’re using quarto/quartodoc, to achieve this, in your quarto.yml, you’ll want to add an output-dir to the project section.

e.g

project:
  type: website
  output-dir: docs

You’ll then render your quarto site with the quarto render command and commit the contents of the docs folder.

You will also need to commit a blank file called .nojekyll to your repository root. This prevents any post-processing being applied to your quarto site when GitHub pages builds it, which generally causes errors.

Quartopub

Alternatively you can use the quartopub publishing services.

Details can be found here.

Warning

Note that the site will be publicly visible

Hosting your personal site

If you like, you can also make yourself a portfolio site. This is another great way to showcase work you’ve done, talks you’ve given, etc.

• Make a repository called yourusername.github.io
• Use one of Quarto’s about page templates
• Feel free to use my site as a template!
  • You’re on the site right now: sammirosser.com
  • The code can be found at github.com/Bergam0t/bergam0t.github.io
  • I used Cloudflare for a cheap domain name (<£10 a year) - drop me an email at hi@sammirosser.com if you’d like some tips on setting this up.

Auto-linting

• Ruff is a brilliant option for Python linting in VSCode: https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
  • scroll down to the section ‘settings’ –> ‘Configuring VSCode’ to see how to set it up to lint-on-save. It’s well worth it!
• Air is apparently a great option for R in both VSCode and Positron, though I haven’t used it myself: posit-dev.github.io/air/editor-vscode.html
  • Again, you’d want to turn on ‘format on save’: posit-dev.github.io/air/editor-vscode.html#editor-vs-code-format-on-save
• While there is some support for Air in RStudio, you may be better off with the styler package
  • There’s some good information on R for the rest of us about using styler via the RStudio command palette (towards the end of the article)
  • It should also be possible to set it to style on save via the R settings (image credit: kevinushey on GitHub: github.com/rstudio/rstudio/issues/2563)

Tests

Don’t be afraid to start extremely simple and build up your tests over time. One test is better than none!

And even though tests are often talked about in the context of packages, they don’t have to be used in that way. You can use the functions from the testing packages mentioned in other scripts too!

Python

pytest is the most recommended testing framework for Python.

There’s a nice introduction to tests in the HSMA DES book here (des.hsma.co.uk/tests.html) - even though it’s in the context of simulation models, it’s a good general overview of the concepts - thanks Amy!

I’ve also found this free eBook to be really useful: pytest-with-eric.com/

R

In r, the testthat package is the most popular option.

There’s a nice overview of using it in the R packages free eBook by Hadley Wickham and Jennifer Bryan: r-pkgs.org/testing-basics.html

Issues + Projects

We provide an overview of issues in one of our HSMA presentations: hsma-programme.github.io/h6_march_2025_forum_presentation/#/github-issues

There are also some details on projects here: hsma-programme.github.io/h6_march_2025_forum_presentation/#/projects

Packages

Python

For Python, the best introduction I’ve found is by Professor Tom Monks, in his eBook written for students on his health data science MSc. It’s approachable and thorough, and takes you from creating a local package all the way to publishing it on PyPi. It’s the document I always return to for a new package.

pythonhealthdatascience.com/content/03_mgt/02_packaging/01_python_packages.html

R

The r packages ebook by Hadley Wickham and Jennifer Bryan is a great resource

I think the welcome page has a great bit of advice:

Writing a package can seem overwhelming at first. So start with the basics and improve it over time. It doesn’t matter if your first version isn’t perfect as long as the next version is better.