Commit 8050b295 authored by Ben Glocker's avatar Ben Glocker
Browse files

Merge branch 'feature/session_info' into 'master'

Session info and environment setup instructions

See merge request bglocker/rcs-summer-school!1
parents 8c818f36 9da59273
# Research Computing Summer School: Introduction to Medical Image Computing
#### Friday 27th September 2019
Welcome to the **Introduction to Medical Image Computing Tutorial** being held as part of the [Imperial Research Computing Summer School 2019](
This tutorial will introduce you to the basics of handling and working with medical images using Python. Following the introductory material, we look at an example that introduces two different supervised learning approaches for undertaking age regression from brain MRI scans.
#### Tutorial Content
The content for this tutorial is provided in two [Jupyter Notebooks]( If you are not familiar with Jupyter, a Notebook is a web-based interactive environment for creating, sharing and running code that can include visualisations and other graphical content.
#### Prerequisites
- **Python:** To get the most out of this tutorial, you should have at least a basic knowledge of Python software development.
- **System environment:** You will need access to a system with Python 3 installed. Python 3.6+ is recommended. You can use a standard system Python install with the *pip* package manager, or an [Anaconda distribution]( that comes with almost all of the required package dependencies installed by default.
- **Virtual environment**: Regardless of what type of Python distribution you are using, it is strongly recommended that you create a Python virtual environment for undertaking this tutorial. If you are using a standard system Python install (i.e. not an Anaconda distribution), ensure that you have the `virtualenv` command available. If not, you can install `virtualenv` globally using pip, e.g. on Linux/Mac OS run: `sudo pip install virtualenv`
#### Preparing your environment
**If you are a Department of Computing user, you can access a pre-configured environment on Department of Computing systems - see the DoC environment configuration section below. If you wish to configure a local environment on your own system to undertake the tutorial, please read on.**
**_Windows users:_** *The instructions in this section relate to Linux or Mac OS-based systems. If you are using Windows, you can download an Anaconda Windows installer [here]( You should then be able to use the conda install instructions in section 2B below to install the required additional dependencies. If you are using Windows and are unclear how to set up your environment for the tutorial, please speak to one of the tutorial helpers.*
The steps for preparing your environment are as follows:
- Clone the repository from GitLab
- Set up a virtual environment and install dependencies
- Prepare the data
- Start Jupyter Notebook server
##### 1. Clone the repository
Open a terminal window and create a directory in which to place the tutorial materials. This directory will be referred to as `$TUTORIAL_DIR`. Change into `$TUTORIAL_DIR` and clone the repository from GitLab as follows:
$ git clone
##### 2. Set up a virtual environment and install dependencies
* If you are using a **standard system Python install**, continue with **section 2A**
* If you are using an **Anaconda Python distribution**, continue with **section 2B**
###### 2A. Set up a virtual environment and install dependencies (system Python installation)
You should have the `pip` package manager and `virtualenv` tool installed.
* Within `$TUTORIAL_DIR`, create and activate a virtual environment as follows:
$ virtualenv --prompt=rcs-tutorial env
New python executable in /home/user/my-tutorial-dir/env/bin/python3.6
Also creating executable in /home/user/my-tutorial-dir/env/bin/python
Installing setuptools, pip, wheel...
$ source env/bin/activate
[rcs-tutorial] $
* Change to `$TUTORIAL_DIR/rcs-summer-school`
* Install the dependencies using `pip`:
[rcs-tutorial] $ pip install -r requirements.txt
Continue with **Section 3 - Prepare the data**
##### 2B. Set up a virtual environment and install dependencies (Anaconda distribution)
*Creating a conda virtual environment is optional but is recommended as a way to keep any packages installed for this tutorial separate from your main conda environment.*
Using `conda`, create and activate the virtual environment - here we use the name (specified with the -n switch) *img-tutorial*, if you wish, you can use a different name for your virtual environment:
$ conda create -n img-tutorial python=3 anaconda
# You will be prompted to confirm the installation of a number of packages.
$ conda activate img-tutorial
Now install the required additional package:
$ conda install -c simpleitk simpleitk
Continue with **Section 3 - Prepare the data**
##### 3. Prepare the data
**NOTE:** *If you are a DoC user running this tutorial on a DoC system using the pre-configured virtual environment, the data is already in place and you do not need to undertake this step.*
A [ZIP file]( is available containing the data required for this tutorial.
Download the ZIP file to `${TUTORIAL_DIR}` and extract it in this location. This will give you a directory named `data` containing the sample imaging data used in the tutorial.
##### 4. Start Jupyter Notebook server
$ cd ${TUTORIAL_DIR}/rcs-summer-school
$ jupyter notebook
This should open your default web browser with the Jupyter notebook homepage displayed. Providing that you started the notebook server in `${TUTORIAL_DIR}/rcs-summer-school` You should see the two tutorial notebooks `1-Medical-Image-Computing.ipynb` and `2-Brain-Age-Regression.ipynb` in the file list.
**_NOTE:_** *If you are running your jupyter server on a remote system then you may need to specify the --ip= switch on the jupyter command line to get the jupyter server to listen on the public network interface on your server. Likewise, if you want to run the jupyter server on a different port to the default port 8888, you can specify the --port switch.*
##### DoC environment configuration
If you are an Imperial Department of Computing user and have access to DoC systems, you can activate a pre-configured virtual environment an undertake the tutorial on a DoC system:
If you are using `tcsh`, activate the environment by running:
$ source /vol/lab/course/416/venv/bin/activate.csh
or, using `bash`:
$ source /vol/lab/course/416/venv/bin/activate
#### Starting the tutorial
Begin the tutorial by opening the first notebook - `1-Medical-Image-Computing.ipynb`
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment