@@ -22,6 +22,8 @@ The points intent to give a high-level overview of the steps, which are further
...
@@ -22,6 +22,8 @@ The points intent to give a high-level overview of the steps, which are further
6. (optional) If the results are not satisfactory, repeat steps 2-5 by providing more annotations and training more neural network models.
6. (optional) If the results are not satisfactory, repeat steps 2-5 by providing more annotations and training more neural network models.
7. (optional, currently BigBrain1 only) Send the results of your quality control to Christian Schiffer to attempt a 3D reconstruction of the segmented areas.
7. (optional, currently BigBrain1 only) Send the results of your quality control to Christian Schiffer to attempt a 3D reconstruction of the segmented areas.
[This videw](./atlasui_demo.mp4) demonstrates the use of the website.
## Pre-requisites
## Pre-requisites
The following pre-requisites have to be met to enable use of ATLaSUI:
The following pre-requisites have to be met to enable use of ATLaSUI:
...
@@ -82,6 +84,149 @@ Note that mixing approaches is always possible, as described in the previous sec
...
@@ -82,6 +84,149 @@ Note that mixing approaches is always possible, as described in the previous sec
*Example use case for training deep learning models. This example shows the last case indicated above: Models are trained for each section interval, and for one specific area.*
*Example use case for training deep learning models. This example shows the last case indicated above: Models are trained for each section interval, and for one specific area.*
## Using ATLaS
This section assumes that you have an idea how you want to approach the segmentation of the areas you are interested.
We will now detail how to use ATLaSUI to define these tasks.
### Start
1. Navigate to the [website](http://medpc076.ime.kfa-juelich.de:5001/microdraw/microdraw.html?source=data/brainmap/B20.json).
2. Click the `Log in button` at the top left corner. If not already registered, do so. Remember your username and password.
3. When logged in, click the blue `ATLaS UI` button in the left toolbar. This will open the ATLaSUI main menu.
### Creating a project
The next step is to create a project.
A project can contain multiple tasks, and each task corresponds to one neural network training.
Projects can be particularly useful if you want to try different subdivision approaches, or if you want to work with different areas independently.
1. To create a project, click the `New project...` button in the ATLaSUI main menu. The project dialogue opens.
2. Enter a name for the project. The brain identifier usually does not need to be changed.
3. Click `Save` at the bottom row.
4. The project now shows up in the ATLaSUI main menu. It can be edited using the `Edit` button, or deleted using the `Delete` button. The project gets an ID. Please specify this ID when requesting support.
5. Now click `Edit` to add some tasks to the created project.
### Creating tasks
Projects contain tasks.
Each task corresponds to a neural network model that is trained to perform segmentation of one or multiple brain areas (see "Core concepts" sections).
The suggested way to create tasks is the `Task wizard`. Open it using the green `Task wizard` button in the lower left corner of a project's menu.
__Note:__ Loading of the task wizard can take a while, be patient.
The task wizard assists you in creating many tasks in an automated fashion.
The left `Sections` pane shows the brain sections for which annotations exist in your account (note: should the pane be empty, check that you logged in, and try to close and re-open the task wizard).
By default, none of the available sections are selected, indicated by the red color of the section buttons. Clicking on one of the section buttons enables a section.
The buttons `Enable all` and `Disable all` can be used to enable or disable all sections at the same time, respectively.
When a section is selected, annotations found for this section are added to the `Annotations` pane in the center of the dialogue.
Each annotation is represented by a section number, its name, and a `+` button, allowing to add the annotation to a task.
The `Annotation filter` field at the bottom can be used to filter annotations, for example to only take specific brain areas or a single hemisphere into account.
The field supports [regular expressions](https://en.wikipedia.org/wiki/Regular_expression), allowing very fine-grained selection of annotations.
The website [regex101](https://regex101.com/) is a useful tool to test and learn regular expressions.
The right pane is subdivided into two sections:
The upper part shows the current task, i.e., the task that is currently being defined.
You can give the task a name, and add annotations to the task by clicking the `+` button next to annotations.
Alternatively (and recommended), you can click `Add annotations` to add all currently visible annotations to the current task.
In this way, you can use the filtering ability of the `Sections` and `Annotations` panes to filter the annotations you are interested in, and simply click `Add annotations` to create a task from them.
The checkboxes below the task name further ease task creation.
`Enable auto-rename` automatically removes suffixes from annotation names, typically an indicator of the hemisphere (i.e., `_l` or `_r`) and/or an index (e.g., `_0` or `_1`).
It is important to remove these parts of the annotation names when adding them to a task, because brain regions are defined by their name.
For example, two annotations called `hOc1_l` and `hOc1_r` will be treated as different areas due to their different names, which is most likely undesirable.
Keeping `Enable auto-rename` enabled will ensure that most common suffixes are automatically removed when adding annotations.
In cases that cannot be handled by this feature, you can (and have to) rename the annotations manually in the `Annotations` pane.
The `No auxiliary labels` flag determines whether the segmentation task should include so called auxiliary labels, i.e., cortex and white matter.
As a rule of thumb, isocortical areas should leave the box disabled, while subcortical structures should enable this flag.
Ask for support if you are unsure about this flag.
`Name by sections` is useful to automatically name tasks based on the sections that are included in the contained annotations.
This saves you the time of manually entering the name of the task.
It is recommended to enable this flag for easy task creation, in particular when using different intervals.
Note that this flag has to be enabled before adding annotations to take effect.
After adding annotations and defining a name for the task, use the `Save task` button to add the task to the `Tasks` pane in the bottom right.
After doing so, the current task will be cleared, and you can continue with creating new tasks.
When you are finished creating tasks, click the `Save` button to add the created tasks to the project.
#### The `Import` feature
Creating many tasks can be tedious, especially for many intervals.
The `Import` button in the lower left corner opens a text window, which allows you to easily define intervals.
For example, the following text will automatically create three tasks, one for each of the given intervals.
```bash
100-200
200-300
300-400
```
It is important to note that the `Import` feature only works if a filter is specified in the `Task wizard`.
This is a safety measure to prevent accidentally add incorrect annotations.
Use the filter `.*` to force add all annotations, independent of their name (typically not recommended).
### Starting training jobs
After creating tasks, it is time to actually start the training of the neural network models for segmentation.
During training, the neural network learns the structure of selected area(s) from the provided annotations, so it can later be used to automatically segment new brain sections.
The easiest way to start the training and prediction this is by clicking the `Train+Predict all` button in the project menu.
This will start training and prediction jobs on the HPC system JURECA-DC (JSC, Jülich).
It is important to note that submitted jobs do not necessarily start immediately.
Depending on the load of the HPC system, jobs may take some time to start.
You can check the status of submitted jobs by clicking on the `Jobs` button next to a task.
There, you will see a list of submitted jobs, as well as their state.
Jobs can be `Pending`, `Running`, `Completed`, or `Failed`.
If a job is pending or running, you need to wait until the job is finished.
Typically, training takes between 10 and 20 minutes, while prediction can take between a few minutes up to two hours, depending on how many sections are being predicted.
If both training and prediction jobs are completed, predictions are ready to be viewed.
If a job fails, ask for support.
__Note:__ The system only provides status information for the most recent jobs.
Jobs that finished too long ago will have the status `Unknown`.
In case you see this status, assume that the job finished successfully, if you do not receive a mail that tells you otherwise.
If a job has unknown status, and you have problems viewing the results, ask for support.
### Viewing results
Prediction results can be inspected for each task by clicking on the clipboard icon next to each task.
Clicking on this button will open a new tab with a new microdraw page.
Navigate to the sections with predictions available to view the segmentation results as overlay.
Use the slider on the left to control the opacity of the overlay.
Segmentations are available for all sections in-between the annotated sections.
For example, if a task uses annotations on sections 200 and 300, segmentations will be created for sections 200 to 300.
## What's next?
After you obtained predictions, the next step is to quality check the predictions.
View them and try to find out if the prediction results are satisfactory.
If not, consider trying a different approach for subdividing sections and areas (see "Core concepts" section).
If results are satisfactory, a possible next step is attempting a 3D reconstruction.
Currently, this is only possible for the BigBrain dataset.
The prerequisite for the 3D reconstruction is a systematic quality check of the predictions.
The quality check consists of a classification of the section into "good" or "bad" segmentations.
It is important to note that not all segmentations need to be of good quality to obtain a good reconstruction.
As long as there is a sufficient amount of good quality segmentations, the 3D reconstruction can be created by interpolating between good segmentations.
In practice, the quality check is performed by filling a simple excel table.
You should use the template provided [here](./classification.xlsx).
Create the relevant section range in the first column, and classify each section by entering "0" for bad quality and "1" for good quality.
If you are unsure about individual sections, ask for support.
Repeat the classification for each project you want to create a reconstruction for.
__Important:__ Do not modify the structure of the table, and do not enter additional information. Only use "0" and "1" for classification. Any other information may prevent automatic processing and will slow down the reconstruction process.
When you are finished with the classification, send the classification file to Christian Schiffer, so he can attempt a reconstruction.
Please include the following information in your request.
- The filled out quality check table.
- The ID (__not__ the name!) of the project to pull annotations from.
- If not all tasks of a project should be used, a comma separated list of task IDs to use (e.g., "1,2,3,5,6,10").
- A comma separated list of areas to consider for reconstruction (e.g., "hOc1,hOc2,hOc5").
