README.md 4 KB
Newer Older
Tom Whyntie's avatar
Tom Whyntie committed
1
# TUSCANI Machine Learning Workshop
Vaanathi Sundaresan's avatar
Vaanathi Sundaresan committed
2

Tom Whyntie's avatar
Tom Whyntie committed
3
This repository is for the TUSCANI Machine Learning Workshop.
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Here you will find workshop materials, example data,
and code you need to get started with Machine Learning for
neuroimaging.

## Installation and Setup

### Install Conda
[Conda](https://conda.io/docs/) provides an easy way of getting
Python working on your computer, allowing you to set up Python
environments with specific software requirements independent of your
native Python installation (i.e. whatever is on there already).

We recommend using Conda for this workshop.  If not installed already,
you can find instructions here:

https://conda.io/docs/user-guide/install/index.html

21
22
23
24
You'll also need to run this from a **terminal** on your machine.
If you don't know what this means, please ask us for help
or work with someone who does until you get the hang of it.

25
26

### Create a new conda environment
27

28
29
30
31
The following commands should create a Conda environment
with Python 3.6 and all of the software you'll need for the workshop:

```bash
32
# Create a directory for working in.
33
34
35
36
37
38
39
40
41
export WORKING_DIR=[The directory in which you will be working]
mkdir -p ${WORKING_DIR}
cd ${WORKING_DIR}

# This will create the Conda environment in your working directory, rather
# than the conda directory in your your home folder.
conda create python=3.6 matplotlib seaborn jupyter pandas xlrd scikit-learn -p ./mlpython
```

42

43
44
45
46
47
48
49
### Activate your environment
Tell your machine to use your shiny new Conda environment with this command:

```bash
source activate mlpython
```

50
51
52
53
54
55
56
### Add some neuroimaging packages
NiBabel isn't in the standard Conda distributions, so we need to add this after activating the environment:

```bash
conda install -c conda-forge nibabel
```

57

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
### Clone this repository

You'll need a copy of this code, which can be retrieved from the FMRIB
GitLab server with the following command:

```bash
git clone https://git.fmrib.ox.ac.uk/vaanathi/ml_worshop_tng-tuscani
cd ml_worshop_tng-tuscani
```


### Set the Jupyter Notebook server running

You can launch the Jupyter Notebook server with the following command:

```bash
jupyter notebook
```

This will launch the notebook server home in your default browser.

### Open the appropriate notebook

Once running in your browser,
you can select the appropriate notebook to open it and get going!

_Note: to run a cell in the workbook, select it and press the
Shift and Enter key_


### Finishing and tidying up

Once you're done, 
click on the "Save" icon in the top-left of the notebook
page (which is still a 3.5-inch floppy disk, aw),
close the tab(s) in your browser, return to the
terminal from which you launched the Jupyter Notebook server,
and press Ctrl+c twice to shut down the server.
You can then close the terminal.


99
100
## The workshop material

101
* `ML_workshop_notebook1.ipynb`: The Jupyter notebook for session 2 - an introduction to Machine Learning with (fake) Parkinson's data;
102
103
* `ML_workshop_notebook2.ipynb`: The Jupyter notebook for session 3 - an introduction to ML with (real!) imaging data;
* `augmentations.py`: A Python file with various image and volume augmentation functions (ND).
Tom Whyntie's avatar
Tom Whyntie committed
104
105


106
107
108
109
110
111
112
113
114
115
116
## Data

### FPAR (Fake Parkinson's Data)

This dataset can be found in `data/fpar`. You have:

* `data/fpar/demographics.xls` : an Excel spreadsheet of the demographic information associated with each subject;
* `data/fpar/idps.csv` : a Comma-Separated Value (CSV) file of Image Derived Phenotypes (IDPs) extracted from the subject's T1 and T2 FLAIR structural scans.

Can you identify the patients with Parkinson's Disease?

117
118
119
120
121
122
### BIANCA WML sample data

This dataset can be found in `data/Segmentation`.
See the workshop session 3 notebook for more information.


Tom Whyntie's avatar
Tom Whyntie committed
123
124
## Workshop Dates

125
126
127
128
* `2018-11-26`: _ML Workshop Part I - Introduction_
* `2018-12-03`: _ML Workshop Part II - Pitches_
* `2018-12-10`: _ML Workshop Part III - Group Work_
* `2018-12-17`: _ML Workshop Part IV - Group Work_
Tom Whyntie's avatar
Tom Whyntie committed
129
130
131
132

## Useful links

* [TUSCANI schedule](https://docs.google.com/spreadsheets/d/1Cmf0HuyQh7Ggk1H5OOrScyECTT5RSOUnL9W1BL35eak/edit#gid=514131059)