...

Instructions with explanations

...

The reasoning for each step is shown in red text.

Initial setup

This is for people who have not previously configured Anaconda or Jupyter on their desktops.

1. Log on to your SAIL desktop.
2. Click on the Start menu (the little Windows icon on the bottom left) → Anaconda3 (64-bit) → Anaconda Prompt (Anaconda3). This will open a command line window with a line of text like:
   1. (base) C:\Users\<your username will be here>
3. Now we need to make an environment to use. In this command line window, type the following and then hit 'Enter':
   1. conda create -p P:\<your username here>\<name of your new environment> –-channel=anaconda --channel=conda-forge nb_conda_kernels pandas numpy jupyterlab
   2. For example, if my username is 'leal' and I want to create an environment called 'mynewenv' in a folder called 'conda-envs', the command I would run would be:
      1. conda create -p P:\leal\conda-envs\mynewenv –-channel=anaconda --channel=conda-forge nb_conda_kernels pandas numpy jupyterlab
   3. We create a new environment because you cannot install packages to the base environment as it is on the C: and your user account doesn't have permission to write there.
   4. We use the '-p' flag to tell Anaconda to put all your environment files and folders in a specific location and not in its default location on the C:.
   5. The environment path has to be somewhere that won't get cleared during the maintenance window, which rules out the C:, and also somewhere you have permission to write to. 
      This is why we use our P:\<username> folder.
   6. The --channel flags tell Anaconda where to look for the libraries that we want it to install in our new environment
   7. The libraries we want to be installed by default are:
      1. nb_conda_kernels - This extension enables a Jupyter Notebook or JupyterLab application in one conda environment to access kernels for Python, R, and other languages found in other environments. When a kernel from an external environment is selected, the kernel conda environment is automatically activated before the kernel is launched. This allows you to utilize different versions of Python, R, and other languages from a single Jupyter installation.
      2. pandas and NumPy - are very useful Python libraries for dealing with data.
      3. jupyterlab - the complete Jupyter distribution is needed so we can use Jupyter.
4. Wait while your new environment is created and all requested packages are installed.
5. You might get a pop-up saying, "this app has been blocked by your system administrator" this is fine, and it all worked. Just click 'Close' on the message.
   1. This is related to python.exe permissions; it is a known issue but shouldn't cause any problems.
6. After your environment is created, you need to activate it by typing the following in the same command line window:
   1. conda activate P:\<your username here>\<name of your new environment>
   2. So, if my username is 'leal' and I created an environment called 'mynewenv' in a folder called 'conda-envs', I would use the command:
      1. conda activate P:\leal\conda-envs\mynewenv
   3. You need to activate an environment every time you open a fresh Anaconda Prompt window; otherwise, Anaconda will try and use the base environment.
7. Congratulations, you can now move on to the next part of the guide.

Starting Jupyter

This assumes that you have done the initial setup and have an environment saved on your P: (pronounced 'P drive').

Suppose you've just completed the initial setup and have your new environment activated in an open command line window. In that case, you can skip steps 1-3.

1. Log on to your SAIL desktop.
2. Click on the Start menu (the little Windows icon on the bottom left) → Anaconda3 (64-bit) → Anaconda Prompt (Anaconda3). This will open a command line window with a line of text like:
   1. (base) C:\Users\<your username will be here>
3. Activate your conda environment by typing the following in the same command line window:
   1. conda activate P:\<your username here>\<name of your new environment>
   2. So, if my username is 'leal' and I created an environment called 'mynewenv' in a folder called 'conda-envs', I would use the command:
      1. conda activate P:\leal\conda-envs\mynewenv
   3. You will know when the environment is activated because the window will show a line of text like:
      1. (P:\<your username>\<your environment name>) C:\Users\<your username>
   4. You need to activate an environment every time you open a fresh Anaconda Prompt window; otherwise, Anaconda will try and use the base environment.
4. VERY IMPORTANT: Before starting Jupyter, we must ensure we're on the P: in the command line window. To do this, type the following into the window and press Enter:
   1. P:
   2. You cannot change drive letters from within Jupyter. If you start Jupyter when you're on the C: it will only be able to save your notebooks on the C:. The C: gets cleared whenever
      your desktop restarts, so you'd lose all your notebooks if you saved them here.
5. Then type the following and press Enter:
   
   1. cd <your username here>
   2. So if my username is 'leal', I would type:
      1. cd leal
   3. Jupyter needs to be able to write to wherever it starts, and making sure it starts in your user folder avoids several common "permission denied" problems.
6. (Optional) You might want to navigate to the specific folder in which you'll be working/saving this work, but that is out of the scope of this simple guide.
7. We are now ready to start Jupyter. In the command line window, type and hit Enter with either of the following commands:
   1. jupyter notebook
      1. This will give you the 'classic' Jupyter interface.
   2. jupyter lab
      1. This gives you a more modern Jupyter interface.
8. Jupyter will automatically open in a Microsoft Edge tab. You can navigate wherever you want to save your notebooks, create folders, make your notebooks, etc.
   1. You need to leave the Anaconda Prompt window open while you're using Jupyter.
      1. If you close the Anaconda Prompt window, it shuts down the local server that Jupyter is using, crashing Jupyter.
9. To ensure that you're using the correct environment kernel in Jupyter, you need to pay attention when creating notebooks.
   1. In the 'classic' interface:
      1. Click on 'New' in the top right.
      2. In the drop-down window that opens, make sure you choose the option called 
         1. Python \[conda env: <name of your conda env here>\]*
   2. In the modern interface:
      1. Under the 'Notebook' heading in the launcher tab, select the one with the name
         1. Python \[conda env: <name of your conda env here>\]*
   3. We want any notebook that we use to use the specific version of everything that we installed in our Anaconda Environment.
      Doing this means that you can use packages installed in your Anaconda Environment inside Jupyter too.
10. When you're done and want to exit Jupyter, click on the 'Anaconda Prompt' window on the taskbar, click somewhere in the window, and press Ctrl+C twice.
11. Please wait a few seconds; Jupyter should shut down, making it safe to close your notebook.

Installing packages

This assumes that you've completed the initial setup and have an environment saved on your P: .

Suppose you've just completed the initial setup and have your new environment activated in an open command line window. In that case, you can skip steps 1-3.

We strongly recommend users try installing from Anaconda sources for package installation. You should only use pip if a package isn't available from Anaconda channels.

1. Log on to your SAIL desktop.
2. Click on the Start menu (the little Windows icon on the bottom left) → Anaconda3 (64-bit) → Anaconda Prompt (Anaconda3). This will open a command line window with a line of text like:
   1. (base) C:\Users\<your username will be here>
3. Activate your conda environment by typing the following in the same command line window:
   1. conda activate P:\<your username here>\<name of your new environment>
   2. So, if my username is 'leal' and I created an environment called 'mynewenv' in a folder called 'conda-envs', I would use the command:
      1. conda activate P:\leal\conda-envs\mynewenv
   3. You will know when the environment is activated because the window will show a line of text like:
      1. (P:\<your username>\<your environment name>) C:\Users\<your username>
4. Outside your SAIL desktop, go to Google and search '<name of the package you want to install> anaconda'.
   1. For example, if I want to install the package 'recordlinkage', I would search on Google for 'recordlinkage anaconda'.
5. Select the Google result from anaconda.org; this should take you directly to the Anaconda page for the package.
6. On the page, there will be a command that tells you how to install it. Sticking with the recordlinkage example, the webpage shows me that the command to install is:
   1. conda install -c conda-forge recordlinkage
7. Go back to your SAIL desktop and type this installation command into your Anaconda Prompt window, hitting 'Enter'.
8. Wait for Anaconda to ask you if you want to proceed - hit 'y' on your keyboard and then press 'Enter'.
9. Your package is installed!