Using JupyterLab from within the OpenSAFELY Python environment

[iaindillingham]

Here at OpenSAFELY, we use Docker to ensure that our code is run in the same environment, or container, whether it's run on our computer, on another researcher's computer, or on a backend-provider's computer. However, interacting with Docker containers can be confusing; it's tempting to use an alternative workflow, when one's available, to develop our code.

For example, a common use case is to develop our code in a Jupyter notebook, using JupyterLab—which we may have installed with Anaconda—or Visual Studio Code. However, the environments created by Anaconda and Visual Studio Code are unlikely to match the OpenSAFELY Python environment; that is, the environment within an OpenSAFELY Python container. Versions of important packages, such as Pandas, may be different. Indeed, some packages may be present in an Anaconda environment but absent from the OpenSAFELY Python environment. What should we do?

One solution is to be very careful: we could develop our code in an Anaconda environment, test it by running opensafely run, and fix any errors as we encounter them. However, this solution isn't interactive, and the errors lack context, making them hard to interpret.

Another solution is to develop our code in a Jupyter notebook, using JupyterLab, from within the OpenSAFELY Python environment. This solution is more interactive than the previous solution, and the errors are in context, making them easier to interpret. From within Git Bash (Windows) or the Terminal (macOS), we should navigate to the folder that contains our study files and run:

docker run -p 8888:8888 --rm -v /$(pwd)://mnt/opensafely -w //mnt/opensafely ghcr.io/opensafely-core/python jupyter lab --ip 0.0.0.0 --allow-root

We should look for a URL (http://127.0.0.1:8888/?token=...) and paste it into a web browser. We should now see JupyterLab, with our study files in the File Browser, to the left.

---

Thanks @HelenCEBM and @Jongmassey for their help. For background, see: https://github.com/opensafely/covid-vaccine-preliminary-uptake-study/issues/162#issuecomment-974178947.

[iaindillingham]

Good news! It's now possible to use JupyterLab within the OpenSAFELY Python environment. Run the following command within your study directory

opensafely jupyter

to open JupyterLab in your default web browser.

[ZijingY]

hi,
After installing collected opensafely sucessfully (pip install opensafely), when I try to confirm everything is working, type opensafely and press Enter in Jupyter, it shows that

NameError Traceback (most recent call last)
in
----> 1 opensafely

NameError: name 'opensafely' is not defined
I have know idea how to fix it.
Thank you.

Zijing

[iaindillingham]

Hello @ZijingY. Thanks for your question. opensafely isn't a Python library, so you can't run it from a Jupyter notebook. It's a command line tool, so you should run it from a Terminal or shell. You can find out more in the Getting Started Guide.