Introducing the `opensafely exec` command for interactive sessions.
16 February 2023
New opensafely command: opensafely exec
There is new opensafely exec command in recent versions of the opensafely
tool. It is designed to aid in development of analysis code using the published
OpenSAFELY docker images.
The need to add your your work-in-progress code to project.yaml in order to test it is awkward. This leads some users to use their own locally installed R/python/stata tooling to develop their code. However, this means they may end up inadventantly using a library (or version of library) which is not available in the relevant OpenSAFELY image, and then the code fails when running with project.yaml.
We previously added the opensafely jupyter
command
to help improve this workflow when working with Jupyter notebooks, but with
opensafely exec, we’ve extended this support to other tools.
What does it do?
Running opensafely exec IMAGE COMMAND does the following:
- runs the relevant docker IMAGE (r, python, stata-mp, cohortextractor)
- shares the files in your current directory
- executes COMMAND (or the default command for the image if you don’t supply one)
This might sound fairly simple, but it opens up some convenient new workflows.
Examples
To run an interactive R session in your current directory, just do:
opensafely exec r R
This will start the opensafely R image, run R, and make the files in your
current directory available to you. So you can load, test, and develop against
your current code and data locally, and save your changes. It’ll even save your
R workspace if you want it to.
For python, you might like to run an interactive ipython session:
opensafely exec python ipython
And similarly for stata:
opensafely exec stata-mp
You can also run cohortextractor directly, which can help testing study definitions:
opensafely exec cohortextractor --help
You can actually run any command you want by passing it as an argument.
For example, you can open an interactive bash shell in any of our images with, if you want to look around inside the image:
opensafely exec $IMAGE bash
For more information, you can run opensafely exec --help, or see the
documentation
Further work
We are always looking for ways to make developing with OpenSAFELY tools easier.
opensafely exec is a key feature to help acheive this. Using it as a base,
some other improvements we may be able to explore in future:
- An option to confgure Rstudio use the opensafely R image for OpenSAFELY projects
- Possibly running the graphical version of Stata
- VSCode integration to run your code automatically with
opensafely exec - Tooling to make testing your analysis code much easier.