Commit d44ce82f authored by Jeremy Cohen's avatar Jeremy Cohen
Browse files

Added requirements.txt and README with environment setup instructions.

parent 8c818f36
# 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](http://www.imperial.ac.uk/computational-methods/news-and-events/hpc-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](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
- **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`
##### 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.*
The dependencies required for the tutorial are included in the repository's `requirements.txt` file. The steps for preparing your environment are as follows:
- Clone the repository from GitLab
- (optional) Set up a virtual environment
- 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:
```shell
$ git clone https://gitlab.doc.ic.ac.uk/bglocker/rcs-summer-school.git
```
###### 2. (optional) Set up a virtual environment
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:
```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
Change to `$TUTORIAL_DIR/rcs-summer-school`
Using `pip`:
```shell
[rcs-tutorial] $ pip install -r requirements.txt
```
Using `conda`:
```shell
$ conda install --file requirements.txt
```
###### 4. 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](https://www.doc.ic.ac.uk/~bglocker/teaching/rcs/data.zip) 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.
###### 5. Start Jupyter Notebook server
```shell
$ 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.
##### 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:
```shell
$ source /vol/lab/course/416/venv/bin/activate.csh
```
or, using `bash`:
```shell
$ source /vol/lab/course/416/venv/bin/activate
```
##### Starting the tutorial
Begin the tutorial by opening the first notebook - `1-Medical-Image-Computing.ipynb`
\ No newline at end of file
jupyter==1.0.0
SimpleITK==1.2.2
numpy==1.17.2
matplotlib==3.1.1
pandas==0.25.1
seaborn==0.9.0
scikit-learn==0.21.3
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