From 0baa724c6b57caacded8777156d4ff2ecb2ce4b8 Mon Sep 17 00:00:00 2001
From: Vincent Beaudoin <77688542+VincentBeaud@users.noreply.github.com>
Date: Thu, 24 Oct 2024 17:24:22 -0400
Subject: [PATCH 1/4] Update DEMO.md
---
docs/fibertube/DEMO.md | 50 +++++++++++++++++++++++-------------------
1 file changed, 28 insertions(+), 22 deletions(-)
diff --git a/docs/fibertube/DEMO.md b/docs/fibertube/DEMO.md
index bdd0ecfaa..96d8ffff4 100644
--- a/docs/fibertube/DEMO.md
+++ b/docs/fibertube/DEMO.md
@@ -1,19 +1,19 @@
-# Demo Workshop
+# Demo
In this demo, you will be introduced to the main scripts of this project as you apply them on simple data.
-Our main objective is better understand and quantify the fundamental limitations of tractography algorithms, and how they might evolve as we approach microscopy resolution where individual axons can be seen, tracked or segmented. To do so, we will be evaluating tractography's ability to reconstruct individual white matter fiber strands at various simulated extreme resolutions.
+Our main objective is better understand and quantify the fundamental limitations of tractography algorithms, and how they might evolve as we approach microscopy resolution where individual axons can be seen. To do so, we will be evaluating tractography's ability to reconstruct individual white matter fiber strands at various simulated extreme resolutions.
## Terminology
Here is a list of terms and definitions used in this project.
General:
- Axon: Bio-physical object. Portion of the nerve cell that carries out the electrical impulse to other neurons. (On the order of 0.1 to 1um)
-- Streamline: Virtual object. Series of equidistant 3D coordinates approximating an underlying fiberous structure.
+- Streamline: Virtual object. Series of 3D coordinates approximating an underlying fiber structure.
Fibertube Tracking:
-- Centerline: Virtual object. Series of equidistant 3D coordinates representing the directional information of a fibertube.
-- Fibertube: Virtual representation of an axon. It is composed of a centerline and a single diameter for its whole length.
-- Fibertube segment: Because centerlines are made of discrete coordinates, fibertubes end up being composed of a series of equally lengthed adjacent cylinders. A fibertube segment is any single one of those cylinders.
-- Fibertube Tractography: The application of a tractography algorithm directly on fibertubes to reconstruct them. Contrary to traditional white matter fiber tractography, fibertube tractography does not rely on a discretized grid of fODFs or peaks.
+- Fibertube: Virtual representation of an axon. Tube obtained from combining a diameter to a streamline.
+- Centerline: Virtual object. Streamline passing through the center of a tubular structure.
+- Fibertube segment: Cylindrical segment of a fibertube that comes as a result of the discretization of its centerline.
+- Fibertube Tractography: The computational tractography method that reconstructs fibertubes. Contrary to traditional white matter fiber tractography, fibertube tractography does not rely on a discretized grid of fODFs or peaks. It directly tracks and reconstructs fibertubes, i.e. streamlines that have an associated diameter.
@@ -33,7 +33,7 @@ This project can be split into 3 major steps:
The data required to perform fibertube tractography comes in two files:
- `./centerlines.trk` contains the entire ground-truth of the DISCO dataset.
-- `./diameters.txt` contains the diameters.
+- `./diameters.txt` contains the diameter to be applied to each centerline in the centerlines.trk file above.
@@ -69,6 +69,12 @@ After a short wait, you should get something like:
As you may have guessed from the output name, this script automatically combines the diameter to the centerlines as data_per_streamline in the output tractogram. This is why we named it "fibertubes.trk".
+If you wish to know how many fibertubes are left after filtering, you can run the following command:
+
+```scil_tractogram_print_info.py fibertube.txt```
+
+
+
## Visualising collisions
By calling:
```
@@ -88,7 +94,6 @@ Before we get into tracking. Here is an overview of the metrics that we saved in
Ex: max_voxel_anisotropic: (3, 5, 5) => max_voxel_isotropic: (3, 3, 3)
- `max_voxel_rotated`: Largest possible isotropic voxel obtainable if the tractogram is rotated. It is only usable if the entire tractogram is rotated according to [rotation_matrix].
Ex: max_voxel_anisotropic: (1, 0, 0) => max_voxel_rotated: (0.5774, 0.5774, 0.5774)
-- `rotation_matrix`: 4D transformation matrix representing the rotation to be applied on the tractogram to align max_voxel_rotated with the coordinate system (see scil_tractogram_apply_transform.py).
@@ -101,7 +106,7 @@ Ex: max_voxel_anisotropic: (1, 0, 0) => max_voxel_rotated: (0.5774, 0.5774, 0.57
We're finally at the tracking phase! Using the script `scil_fibertube_tracking.py`, you are able to track without relying on a discretized grid of directions or fODFs. Instead, you will be propagating a streamline through fibertubes and degrading the resolution by using a `blur_radius`. The way it works is as follows:
### Tracking
-When the tracking algorithm is about to select a new direction to propagate the current streamline, it will build a sphere of radius `blur_radius` and pick randomely from all the fibertube segments intersecting with it. The larger the intersection volume, the more likely a fibertube segment is to be picked and used as a tracking direction. This makes fibertube tracking inherently probabilistic.
+When the tracking algorithm is about to select a new direction to propagate the current streamline, it will build a sphere of radius `blur_radius` and pick randomly from all the fibertube segments intersecting with it. The larger the intersection volume, the more likely a fibertube segment is to be picked and used as a tracking direction. This makes fibertube tracking inherently probabilistic.
Theoretically, with a `blur_radius` of 0, any given set of coordinates has either a single tracking direction because it is within a fibertube, or no direction at all from being out of one. In fact, this behavior won't change until the diameter of the sphere is larger than the smallest distance separating two fibertubes. When this happens, more than one fibertubes will intersect the `blur_radius` sphere and introduce partial volume effect.
@@ -129,31 +134,31 @@ IC: "Invalid Connection": Represents a streamline that ended in the final
NC: "No Connection": Contains streamlines that have not ended in the final
segment of any fibertube.
-A "coordinate absolute error" is the distance in mm between a streamline
+The "absolute error" of a coordinate is the distance in mm between this streamline
coordinate and the closest point on its corresponding fibertube. The average
of all coordinate absolute errors of a streamline is called the "Mean absolute
error" or "mae".
Computed metrics:
- - truth_vc_ratio
+ - truth_vc_ratio
Proportion of VC.
- - truth_ic_ratio
+ - truth_ic_ratio
Proportion of IC.
- - truth_nc_ratio
+ - truth_nc_ratio
Proportion of NC.
- - res_vc_ratio
+ - res_vc_ratio
Proportion of VC at the resolution of the blur_radius parameter.
- - res_ic_ratio
+ - res_ic_ratio
Proportion of IC at the resolution of the blur_radius parameter.
- - res_nc_ratio
+ - res_nc_ratio
Proportion of NC at the resolution of the blur_radius parameter.
- - mae_min
+ - mae_min
Minimum MAE for the tractogram.
- - mae_max
+ - mae_max
Maximum MAE for the tractogram.
- - mae_mean
+ - mae_mean
Average MAE for the tractogram.
- - mae_med
+ - mae_med
Median MAE for the tractogram.
Let's do:
@@ -177,6 +182,7 @@ giving us the following output in `reconstruction_metrics.txt`:
}
```
-This data tells us that none of our streamline managed to stay within the fibertube in which it was seeded (`"truth_vc_ratio": 0.0`). However, 40% of streamlinea are at most one `blur_radius` away from the end of their respective fibertube (`"res_vc_ratio": 0.4`). Lastly, we notice that the streamline with the "worst" trajectory was on average 5.5um away from its fibertube (`"mae_max": 0.0055722481609273775`). We can suspect that it started very good early on, but eventually drifted further than 10um, rendering it a NC.
+This data tells us that none of our streamline managed to stay within the fibertube in which it was seeded (`"truth_vc_ratio": 0.0`). However, 40% of streamlines are at most one `blur_radius` away from the end of their respective fibertube (`"res_vc_ratio": 0.4`). Lastly, we notice that the streamline with the "worst" trajectory was on average 5.5um away from its fibertube (`"mae_max": 0.0055722481609273775`). We can suspect that it started very good early on, but eventually drifted further than 10um, rendering it a NC.
## End of Demo
+
From b2cba05094070339d86c20828a06ca1ca0c0f3be Mon Sep 17 00:00:00 2001
From: Vincent Beaudoin <77688542+VincentBeaud@users.noreply.github.com>
Date: Fri, 25 Oct 2024 11:53:38 -0400
Subject: [PATCH 2/4] Update DEMO.md
---
docs/fibertube/DEMO.md | 14 +++++++++-----
1 file changed, 9 insertions(+), 5 deletions(-)
diff --git a/docs/fibertube/DEMO.md b/docs/fibertube/DEMO.md
index 96d8ffff4..9d75b9d60 100644
--- a/docs/fibertube/DEMO.md
+++ b/docs/fibertube/DEMO.md
@@ -15,7 +15,9 @@ Fibertube Tracking:
- Fibertube segment: Cylindrical segment of a fibertube that comes as a result of the discretization of its centerline.
- Fibertube Tractography: The computational tractography method that reconstructs fibertubes. Contrary to traditional white matter fiber tractography, fibertube tractography does not rely on a discretized grid of fODFs or peaks. It directly tracks and reconstructs fibertubes, i.e. streamlines that have an associated diameter.
-
+
+
+
## Methodology
This project can be split into 3 major steps:
@@ -35,7 +37,7 @@ The data required to perform fibertube tractography comes in two files:
- `./centerlines.trk` contains the entire ground-truth of the DISCO dataset.
- `./diameters.txt` contains the diameter to be applied to each centerline in the centerlines.trk file above.
-
+
The first thing to do is resample `centerlines.trk` so that each centerline is formed of
segments no longer than 0.2 mm.
@@ -50,7 +52,7 @@ scil_tractogram_resample_nb_points.py centerlines.trk centerlines_resampled.trk
Next, we want to filter out intersecting fibertubes, to make the data anatomically plausible and remove any partial volume effect.
-
+
This is accomplished using `scil_tractogram_filter_collisions.py`.
@@ -95,9 +97,11 @@ Ex: max_voxel_anisotropic: (3, 5, 5) => max_voxel_isotropic: (3, 3, 3)
- `max_voxel_rotated`: Largest possible isotropic voxel obtainable if the tractogram is rotated. It is only usable if the entire tractogram is rotated according to [rotation_matrix].
Ex: max_voxel_anisotropic: (1, 0, 0) => max_voxel_rotated: (0.5774, 0.5774, 0.5774)
-
+
-
+
+
+
> [!NOTE]
> This information can be useful for analyzing the reconstruction obtained through tracking, as well as for performing track density imaging.
From ba51e6017fc661fe839f165ccd8b6ebb9891c078 Mon Sep 17 00:00:00 2001
From: Vincent Beaudoin <77688542+VincentBeaud@users.noreply.github.com>
Date: Fri, 25 Oct 2024 11:56:23 -0400
Subject: [PATCH 3/4] Update DEMO.md
---
docs/fibertube/DEMO.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/fibertube/DEMO.md b/docs/fibertube/DEMO.md
index 9d75b9d60..c634bd324 100644
--- a/docs/fibertube/DEMO.md
+++ b/docs/fibertube/DEMO.md
@@ -88,7 +88,7 @@ In white and lower opacity is the original tractogram passed as `--ref_tractogra
### Fibertube metrics
-Before we get into tracking. Here is an overview of the metrics that we saved in `metrics.txt`:
+Before we get into tracking. Here is an overview of the metrics that we saved in `metrics.txt`. They are all expressed in mm:
- `min_external_distance`: Smallest distance separating two fibertubes, outside their diameter.
- `max_voxel_anisotropic`: Diagonal vector of the largest possible anisotropic voxel that would not intersect two fibertubes.
From 2fa2574fb5d68103444ea9a02ffca9da69c47706 Mon Sep 17 00:00:00 2001
From: Vincent Beaudoin <77688542+VincentBeaud@users.noreply.github.com>
Date: Fri, 25 Oct 2024 13:10:16 -0400
Subject: [PATCH 4/4] Update DEMO.md
---
docs/fibertube/DEMO.md | 20 +++++++++++++-------
1 file changed, 13 insertions(+), 7 deletions(-)
diff --git a/docs/fibertube/DEMO.md b/docs/fibertube/DEMO.md
index c634bd324..4ba5f849e 100644
--- a/docs/fibertube/DEMO.md
+++ b/docs/fibertube/DEMO.md
@@ -133,10 +133,10 @@ By using the `scil_fibertube_score_tractogram.py` script, you are able to obtain
VC: "Valid Connection": Represents a streamline that ended in the final
segment of the fibertube in which it was seeded.
-IC: "Invalid Connection": Represents a streamline that ended in the final
- segment of another fibertube.
-NC: "No Connection": Contains streamlines that have not ended in the final
- segment of any fibertube.
+IC: "Invalid Connection": Represents a streamline that ended in the first or
+ final segment of another fibertube.
+NC: "No Connection": Contains streamlines that have not ended in the first or
+ final segment of any fibertube.
The "absolute error" of a coordinate is the distance in mm between this streamline
coordinate and the closest point on its corresponding fibertube. The average
@@ -151,11 +151,17 @@ Computed metrics:
- truth_nc_ratio
Proportion of NC.
- res_vc_ratio
- Proportion of VC at the resolution of the blur_radius parameter.
+ Proportion of VC at the resolution of the blur_radius parameter. The
+ streamline passes at a distance of at most [blur_darius] away from
+ the last segment of its fibertube.
- res_ic_ratio
- Proportion of IC at the resolution of the blur_radius parameter.
+ Proportion of IC at the resolution of the blur_radius parameter. The
+ streamline passes at a distance of at most [blur_darius] away from the
+ first or last segment of another fibertube.
- res_nc_ratio
- Proportion of NC at the resolution of the blur_radius parameter.
+ Proportion of NC at the resolution of the blur_radius parameter. The
+ streamline does not pass below [blur_radius] away from the first or
+ last segment of any fibertube.
- mae_min
Minimum MAE for the tractogram.
- mae_max