Session Instructions

Warning

When you first open the repository in VSCode, you may be asked if you want to reopen the folder in a container.

Ignore this message and close the prompt.

The container is just provided for those who will need a web-based backup for running the exercises - more guidance will be given during the HSMA session.

Installing the environment

1. Open the Anaconda Prompt

2. Navigate to the folder you’ve stored the environment folder in using the cd (change directory) command.

e.g.

cd C:\HSMA\h6_8a_quarto_and_reproducible_reporting\environment

3. Install the environment from the yml file

conda env create -f environment.yml

Click here if you’re having issues with installing the environment via Anaconda

If you receive an error about exceeding the maximum number of retries or having a SSL error, try editing the environment.yml file to replace ‘conda-forge’ with ‘defaults’.

Before

After

Save the file and try again.

If the environment has partially installed before reaching this failure point, it may tell you that you cannot install the environment due to the prefix already existing. If this is the case, run the following command:

conda env remove -n hsma_reproducible_reporting

Then you can rerun the conda env create -f environment.yml command.

Installing Quarto

Your organisation should have already installed Quarto as part of the initial set of software that was requested at the start of the programme.

If you are using your own machine and have not yet installed it, you can install the Quarto CLI tool from this address: https://quarto.org/docs/get-started/

Choose the relevant installer for your operating system.

Installing the Quarto Extension in VSCode

Head to the extensions tab in VSCode.

Search for and install the Quarto extension by clicking on the install button.

Running a sample Quarto document

Selecting the hsma_reproducible_reporting environment

First, we need to make sure we’ve selected the correct environment.

To access the interpreter/environment select from any file within VSCode, click CTRL + SHIFT + P and choose ‘Python: Select Interpreter’ from the dropdown list that appears.

You may need to start typing ‘interpreter’ to get it to show up.

:::

Select the hsma_reproducible_reporting environment from the list. Your list will contain different environments to the above.

Preview the ‘hello_quarto.qmd’ document

Open up the document hello_quarto.qmd and click on the Quarto preview button (highlghted in orange on the image below).

Tip

This button only appears when you are in a .qmd (Quarto markdown) file.

If this has not appeared when you have opened the hello_quarto.qmd document, check that you have installed the Quarto extension (see above).

If this runs successfully, it will open up a Quarto Preview terminal at the bottom of your screen and bring up a document, either within VSCode (the default in the Quarto extension) or in a new web browser window.

If you run into problems…

Troubleshooting

If it is not successful, take a look at the error messages at the bottom of the screen. It may indicate some additional files that you need to install. Try to follow any instructions provided in the terminal.

You can also try running the quarto check command in a terminal window in VSCode. This will run a series of basic checks relating to Quarto and its ability to see other things on your machine, like Python. Reading through the output of that may help to indicate any issues with the setup, and should give you an indication of any commands that may resolve issues you are having.

The backup option - GitHub Codespaces

If you are not able to successfully run the above and if there are no obvious details provided, you will be able to use Gihub Codespaces on the day of the training.

This will provide you with an online machine running VSCode with Quarto, the hsma_reproducible_reporting environment and the Quarto extension already installed, as well as access to all of the files stored in the github repository for the session. Your experience should be almost identical to someone who is running VSCode on their local machine.

To initialize a new codespace on the repository, first make sure you are logged into a Github account.

Then, from the repository, choose ‘Use this template’ –> ‘Open in a codespace’.

You will need to wait a few minutes while it loads. During this time, no files will be visible in the explorer bar.

When it finishes loading, it will look something like this:

You can then use this just like a local install of VSCode.

All code examples have been tested on both Windows and Github Codespaces (which is running Linux behind the scenes).

Accessing your codespace again

If you close down your codespace and wish to reopen it, including any changes you’ve made to files, you can return to the repository and choose ‘Code’ –> ‘Codespaces’, and then click on the codespace name to access it again. The codespace name is randomly generated when you first set up the codespace.