Skip to content
Snippets Groups Projects

wrote the file tree section

Merged Saad Jbabdi requested to merge initial_version into main
1 file
+ 125
19
Compare changes
  • Side-by-side
  • Inline
@@ -20,23 +20,23 @@ MyDataFolder
With this type of descriptors, you can use File-Tree to visualise masses of data efficiently in FSLeyes. This will be the first part of this hackathon.
A major strength of file-tree come about when you write analysis scripts. The advantage there is you will be able to write clean code that separates the processing from all the faf around file names / input-ouput descriptors and the like.
A major strength of file-tree comes when you write analysis scripts. The advantage there is you will be able to write clean code that separates the processing from all the faf around file names / input-ouput descriptors and the like.
?> More on File-Tree in the [file-tree documentation](https://open.win.ox.ac.uk/pages/fsl/file-tree/).
?> More on File-Tree in the [documentation](https://open.win.ox.ac.uk/pages/fsl/file-tree/).
## What is FSL-Pipe?
FSL-pipe allows you to write pipelines in a modular way.
You define the steps of the pipelines with separate modules (recipies), and the tools puts them together for you as a pipeline and produces a command-line interface.
You define the steps of the pipelines with separate modules (recipies), and the tool puts them together for you as a pipeline and produces a command-line interface.
FSL-pipe has many cool features. We will only cover some of them here. To give you a flavour, you get access to parallel processing for free without needing to involke it yourself, the pipeline can intelligently only run the bits that are needed in case you re-run it, etc.
?> More on FSL-pipe in the [fsl-pipe documentation](https://open.win.ox.ac.uk/pages/fsl/fsl-pipe/).
?> More on FSL-Pipe in the [documentation](https://open.win.ox.ac.uk/pages/fsl/fsl-pipe/).
## Learning Objectives:
## Learning Objectives for this practical:
- Understand how to create a **file-tree** for your data and use it to effectively visualise a lot of data in FSLeyes.
- Understand how to create a **file tree** for your data and use it to effectively visualise a lot of data in FSLeyes.
- Learn how to write a python script that uses file-tree.
- Learn how to write a python script that uses file-tree AND fsl-pipe.
@@ -50,12 +50,12 @@ We hope that you can get something out of this regardless of your starting knowl
**Let's begin!**
### 0a. Preliminaries - get data for the practical.
We have created a folder with anatomical (T1w) scans for a number of subjects which you can download. Choose on of:
We have created a folder with anatomical (T1w) scans for a number of subjects which you can download. Choose one of:
- [Low resolution version (634MB).](http://www.fmrib.ox.ac.uk/~saad/highres.zip)
- [High resolution version (80MB).](http://www.fmrib.ox.ac.uk/~saad/lowres.zip)
- [High resolution version (634MB).](http://www.fmrib.ox.ac.uk/~saad/highres.zip)
- [Low resolution version (80MB).](http://www.fmrib.ox.ac.uk/~saad/lowres.zip)
Once downloaded, unzip the folder.
Once downloaded, unzip the folder. Probably go for the lowres version!
### 0b. Preliminaries - installing required packages.
@@ -67,9 +67,9 @@ For this WIN-Hack, you need the FSL. We recommand that you install the [latest v
Let's create our first File-Tree descriptor for the data that we have downloaded. The organisation of this data folder is very simple: one folder per subject, and one T1w image per subject inside an `anat` subfolder.
```text
sub-{subjectid}
sub-{subject}
anat
sub-{subid}_T1w.nii.gz (T1w)
sub-{subject}_T1w.nii.gz (T1w)
```
The main things to explain about the above:
@@ -88,24 +88,130 @@ You should be able to see a table with all you subjects. Navigate through to see
We will use this to check our brain extractions later once we have written some scripts.
### 3. Creating a small script for brain extraction.
To make the most out of File-Tree within FSLeyes, we will run BET on some of the subjects and check the results within FSLeyes.
First, write a script that runs BET on a subset of the subjects. Here is a template for you to fill
```python
#!/usr/bin/env fslpython
# List of subjects to run. Fill it with the first 10 subjects
subjects = []
# DataFolder
DataFolder = ''
# Main loop
import os
for sub in subjects:
print(sub)
T1_input = ...
output = ...
# define cmd
bet_cmd = f'bet {T1_input} {output}'
# run cmd
os.system(cmd)
```
Once you have filled in the missing bits of the script, save it into a `my_script.py` and run it.
Then add the brain-extracted file to the File-Tree:
```text
sub-{subject}
anat
sub-{subject}_T1w.nii.gz (T1w)
sub-{subject}_T1w_brain.nii.gz (T1w_brain)
```
Re-load the File-Tree and the data folder onto FSLeyes and check the results. You will notice that the File-Tree table tells you which subjects have the brain extracted results.
Set the display so that the brain extracted image uses a different colourmap (as below), switch between subjects and notice how File-Tree loads the subjects' data for you whilst keeping the display settings unchanged.
<div class="niivue-canvas" thumbnail="thumbnail.png">
<vol url="data/T1.nii.gz"/>
<vol url="data/T1_brain.nii.gz" colormap="red" opacity="0.5"/>
<vol url="../data/T1.nii.gz"/>
<vol url="../data/T1_brain.nii.gz" colormap="red" opacity="0.5"/>
</div>
### 3. Creating a small script for brain extraction.
!> You can use FSLPY to run BET within your script without invoking the `os.system()` call. We will do this in the next section.
We will compare two approaches: The "standard" approach that needs to handle file names etc. And the file-tree approach that solves all your problems. We will then compare the two with fsl-pipe.
### 4. Use File-Tree
But first, let' write a script that runs BET on the structural data for a bunch of subjects.
Now we will use File-Tree inside our python script. As you will see, by using File-Tree, we don't have to worry about specifying the names of the input/output files in our script. It is all taken care of in the File-Tree.
The structure of a python script is as follows:
Here is our new script (we also use the FSLPY wrapper for BET):
```python
#!/usr/bin/env fslpython
from file_tree import FileTree
from fslpy.wrappers import bet
tree = FileTree.read("myfile.tree")
# the command below updates the tree by identifying all the subjects for which the T1w image exists
tree.update_glob("T1w")
# The main loop no longer has to deal with file names
for ft in tree.iter('T1w'):
T1_input = ft.get_('T1w')
T1_output = ft.get_('T1w_brain')
bet(T1_input, T1_output)
# YOUR CODE HERE
```
Notice that our script doesn't contain any information on where the data resides, or what the files are called within the data folder.
All it needs is the file `myfile.tree` and within the script, we use the nicknames of our files of interest (`T1w` and `T1w_brain`).
But in oder to run our script, we do need to specify where the data resides. We can do that within the file tree text file like so:
```text
!/path/to/data
sub-{subject}
anat
sub-{subject}_T1w.nii.gz (T1w)
sub-{subject}_T1w_brain.nii.gz (T1w_brain)
```
Ok, now you are ready to run the script. If you want to run it for a subset of the subjects, you can do that also in the file tree:
```text
subject = 0001, 0002, 0003
!/path/to/data
sub-{subject}
anat
sub-{subject}_T1w.nii.gz (T1w)
sub-{subject}_T1w_brain.nii.gz (T1w_brain)
```
Try to run it now!
Why bother with the file-tree? Making the code independent of the file structure has a great benefit. Imagine you want to hand over your code to someone else, but their data is organised differently. They cannot write onto the data folder, so they need to have the output data in a separate folder to the input data!
With File-Tree, they can run your script with no changes at all! All they need is to specify their own file-tree. For example:
```text
!/path/to/input_data
sub-{subject} (input)
anat
sub-{subject}_T1w.nii.gz (T1w)
!/path/to/output_data
sub-{subject} (output)
anat
sub-{subject}_T1w_brain.nii.gz (T1w_brain)
```
Try to it!
### 4. Use File-Pipe
Loading