Commit 9da59273 authored by Jeremy Cohen's avatar Jeremy Cohen
Browse files

README updated

parent 3da1be48
......@@ -6,32 +6,32 @@ Welcome to the **Introduction to Medical Image Computing Tutorial** being held a
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
#### Tutorial Content
The content for this tutorial is provided in two [Jupyter Notebooks](https://jupyter.org/). 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.
To get the most out of this tutorial, you should have at least a basic knowledge of Python software development.
#### Prerequisites
##### 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](https://www.anaconda.com/distribution/) that comes with many of the required package dependencies installed by default.
- **Virtualenv**: It is strongly recommended that you create a Python virtual environment for undertaking this tutorial. If you are using a standard 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`
- **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](https://www.anaconda.com/distribution/) that comes with almost all of the required package dependencies installed by default.
##### Preparing your environment
- **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.**
*The instructions in this section relate to Linux or Mac OS-based systems. If you are using Windows and are unclear how to set up your environment for the tutorial, please speak to one of the helpers.*
**_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](https://www.anaconda.com/distribution/#windows). 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 dependencies required for the tutorial are included in the repository's `requirements.txt` file. The steps for preparing your environment are as follows:
The steps for preparing your environment are as follows:
- Clone the repository from GitLab
- (optional) Set up a virtual environment
- Install dependencies
- Set up a virtual environment and install dependencies
- Prepare the data
- Start Jupyter Notebook server
###### 1. Clone the repository
##### 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:
......@@ -39,37 +39,63 @@ Open a terminal window and create a directory in which to place the tutorial mat
$ git clone https://gitlab.doc.ic.ac.uk/bglocker/rcs-summer-school.git
```
###### 2. (optional) Set up a virtual environment
##### 2. Set up a virtual environment and install dependencies
If you are using a standard Python install with the `pip` package manager and you have the `virtualenv` tool installed, within `$TUTORIAL_DIR`, create and activate a virtual environment as follows:
* 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:
```shell
$ 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...
done.
$ source env/bin/activate
[rcs-tutorial] $
```
* Change to `$TUTORIAL_DIR/rcs-summer-school`
* Install the dependencies using `pip`:
```shell
$ 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...
done.
$ source env/bin/activate
[rcs-tutorial] $
```
###### 3. Install dependencies
```shell
[rcs-tutorial] $ pip install -r requirements.txt
```
Change to `$TUTORIAL_DIR/rcs-summer-school`
Continue with **Section 3 - Prepare the data**
Using `pip`:
##### 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:
```shell
[rcs-tutorial] $ pip install -r requirements.txt
$ 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
```
Using `conda`:
Now install the required additional package:
```shell
$ conda install --file requirements.txt
$ conda install -c simpleitk simpleitk
```
###### 4. Prepare the data
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.*
......@@ -77,7 +103,7 @@ A [ZIP file](https://www.doc.ic.ac.uk/~bglocker/teaching/rcs/data.zip) is availa
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.
###### 5. Start Jupyter Notebook server
##### 4. Start Jupyter Notebook server
```shell
$ cd ${TUTORIAL_DIR}/rcs-summer-school
......@@ -86,6 +112,8 @@ $ 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:
......@@ -102,6 +130,6 @@ or, using `bash`:
$ source /vol/lab/course/416/venv/bin/activate
```
##### Starting the tutorial
#### 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