deploy: c3d08a9

dev/_sources/overview/LONG.md.txt

@@ -60,25 +60,29 @@ singularity exec --nv \
                  --3T
 ```
 
-## Behind the Scenes:
+## Single Time Point Cases
+
+Sometimes your longitduianl data set contains participants with only one time point, e.g. due to drop-out or QC exclusion. Instead of excluding single-time point cases completely (which may even bias results), you can include them for better statistics. While this obviously will not help to better estimate longitudinal slopes, linear mixed effects models (LMEs), for example, can include single time point data to obtain better estimates of cross-subject variance. 
+
+HOWEVER, this requires that you process these cases also through the longitudinal stream! This is very important, to ensure that they undergo the same processing steps as data from cases with multiple time points. Only then are the results comparable. The command is the same as above, just specify only the single t1 and time point id. Could not be any easier. 
+
+## Behind the Scenes
 
 `long_fastsurfer.sh` is just a helper script and will perform the following individual steps for you:
-1. It will prepare the subject template by calling `long_prepare_template.sh`:
+1. [Base Init] It will prepare the subject template by calling `long_prepare_template.sh`:
    ```bash
    long_prepare_template.sh \
      --tid <templateID> \
      --i1s <T1_1> <T1_2> ... \
      --tpids <tID1> <tID2>
    ```
-   This will register (align) all time point images into the unbiased mid-space using `mri_robust_template`, after an initial segmentation and skull stripping. It will also create the template image. 
-2. Next, the template image will be segmented via a call to `run_fastsurfer.sh --sid <templateID> --base --seg_only ...` where the `--base` flag indicates that the input image will be taken from the already existing template directory. 
-3. This is followed by the surface processing of the template  `run_fastsurfer.sh --sid <templateID> --base --surf_only ...`, which can be combined with the previous step.
-4. Next, the segmentations of each time points, which can theoretically run in parallel with the previous two steps, is performed `run_fastsurfer.sh --sid <tIDn> --long <templateID> --seg_only ...`,
-5. Again followed by the surface processing for each time point: `run_fastsurfer.sh --<id <tIDn> --long <templateID> --surf_only`. This step needs to wait until 3. and 4. are finished.
-<!-- Maybe reorganize 2. and 3. into 2.A and 2.B and 4. and 5. into 3.A and 3.B -->
-
-<!-- TODO: update this section to better explain the parallelization effects, --parallel_seg is parallelization of segmentation steps, --parallel_surf is the parallelization of surface steps, which is the more impactful option for logitudinal processing explicitly, because parallel segmentation may run into GPU memory limitations. -->
-Internally we use `brun_fastsurfer.sh` as a helper script to process multiple time points (in 4. and 5.) in parallel (if experimental `--parallel_surf` is passed to `long_fastsurfer.sh`). 
+   This will register (align) all time point images into the unbiased mid-space using `mri_robust_template`, after an initial segmentation and skull stripping. It will also create the template image. For single time point cases it will align the input into a standard upright position.
+2. [Base Seg] Next, the template image will be segmented via a call to `run_fastsurfer.sh --sid <templateID> --base --seg_only ...` where the `--base` flag indicates that the input image will be taken from the already existing template directory. 
+3. [Base Surf] This is followed by the surface processing of the template  `run_fastsurfer.sh --sid <templateID> --base --surf_only ...`, which can be combined with the previous step.
+4. [Long Seg] Next, the segmentation of each time point, which can theoretically run in parallel with the previous two steps, is performed `run_fastsurfer.sh --sid <tIDn> --long <templateID> --seg_only ...`,
+5. [Long Surf] Again followed by the surface processing for each time point: `run_fastsurfer.sh --<id <tIDn> --long <templateID> --surf_only`. This step needs to wait until 3. and 4. (for this time point) are finished.
+
+Internally we use `brun_fastsurfer.sh` as a helper script to process multiple time points in parallel (in the LONG steps 4. and 5.). Here `--parallel_seg` can be passed to `long_fastsurfer.sh` to specify the number of parallel runs during the segmentation step (4) which is usually limited by GPU memory, if run on the GPU. Further `--parallel_surf` specifies the number of parallel surface runs on the CPU and is most impactful. It can be combined with `--threads_surf 2` (or higher) to switch on parallelization of the two hemispheres in each surface block. 
 
 ## Final Statistics:
 

dev/overview/LONG.html

@@ -447,27 +447,30 @@ <h2>How to Run Your Data<a class="headerlink" href="#how-to-run-your-data" title
 </pre></div>
 </div>
 </section>
+<section id="single-time-point-cases">
+<h2>Single Time Point Cases<a class="headerlink" href="#single-time-point-cases" title="Link to this heading">¶</a></h2>
+<p>Sometimes your longitduianl data set contains participants with only one time point, e.g. due to drop-out or QC exclusion. Instead of excluding single-time point cases completely (which may even bias results), you can include them for better statistics. While this obviously will not help to better estimate longitudinal slopes, linear mixed effects models (LMEs), for example, can include single time point data to obtain better estimates of cross-subject variance.</p>
+<p>HOWEVER, this requires that you process these cases also through the longitudinal stream! This is very important, to ensure that they undergo the same processing steps as data from cases with multiple time points. Only then are the results comparable. The command is the same as above, just specify only the single t1 and time point id. Could not be any easier.</p>
+</section>
 <section id="behind-the-scenes">
-<h2>Behind the Scenes:<a class="headerlink" href="#behind-the-scenes" title="Link to this heading">¶</a></h2>
+<h2>Behind the Scenes<a class="headerlink" href="#behind-the-scenes" title="Link to this heading">¶</a></h2>
 <p><code class="docutils literal notranslate"><span class="pre">long_fastsurfer.sh</span></code> is just a helper script and will perform the following individual steps for you:</p>
 <ol class="arabic">
-<li><p>It will prepare the subject template by calling <code class="docutils literal notranslate"><span class="pre">long_prepare_template.sh</span></code>:</p>
+<li><p>[Base Init] It will prepare the subject template by calling <code class="docutils literal notranslate"><span class="pre">long_prepare_template.sh</span></code>:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>long_prepare_template.sh<span class="w"> </span><span class="se">\</span>
 <span class="w">  </span>--tid<span class="w"> </span>&lt;templateID&gt;<span class="w"> </span><span class="se">\</span>
 <span class="w">  </span>--i1s<span class="w"> </span>&lt;T1_1&gt;<span class="w"> </span>&lt;T1_2&gt;<span class="w"> </span>...<span class="w"> </span><span class="se">\</span>
 <span class="w">  </span>--tpids<span class="w"> </span>&lt;tID1&gt;<span class="w"> </span>&lt;tID2&gt;
 </pre></div>
 </div>
-<p>This will register (align) all time point images into the unbiased mid-space using <code class="docutils literal notranslate"><span class="pre">mri_robust_template</span></code>, after an initial segmentation and skull stripping. It will also create the template image.</p>
+<p>This will register (align) all time point images into the unbiased mid-space using <code class="docutils literal notranslate"><span class="pre">mri_robust_template</span></code>, after an initial segmentation and skull stripping. It will also create the template image. For single time point cases it will align the input into a standard upright position.</p>
 </li>
-<li><p>Next, the template image will be segmented via a call to <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--sid</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--base</span> <span class="pre">--seg_only</span> <span class="pre">...</span></code> where the <code class="docutils literal notranslate"><span class="pre">--base</span></code> flag indicates that the input image will be taken from the already existing template directory.</p></li>
-<li><p>This is followed by the surface processing of the template  <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--sid</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--base</span> <span class="pre">--surf_only</span> <span class="pre">...</span></code>, which can be combined with the previous step.</p></li>
-<li><p>Next, the segmentations of each time points, which can theoretically run in parallel with the previous two steps, is performed <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--sid</span> <span class="pre">&lt;tIDn&gt;</span> <span class="pre">--long</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--seg_only</span> <span class="pre">...</span></code>,</p></li>
-<li><p>Again followed by the surface processing for each time point: <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--&lt;id</span> <span class="pre">&lt;tIDn&gt;</span> <span class="pre">--long</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--surf_only</span></code>. This step needs to wait until 3. and 4. are finished.</p></li>
+<li><p>[Base Seg] Next, the template image will be segmented via a call to <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--sid</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--base</span> <span class="pre">--seg_only</span> <span class="pre">...</span></code> where the <code class="docutils literal notranslate"><span class="pre">--base</span></code> flag indicates that the input image will be taken from the already existing template directory.</p></li>
+<li><p>[Base Surf] This is followed by the surface processing of the template  <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--sid</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--base</span> <span class="pre">--surf_only</span> <span class="pre">...</span></code>, which can be combined with the previous step.</p></li>
+<li><p>[Long Seg] Next, the segmentation of each time point, which can theoretically run in parallel with the previous two steps, is performed <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--sid</span> <span class="pre">&lt;tIDn&gt;</span> <span class="pre">--long</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--seg_only</span> <span class="pre">...</span></code>,</p></li>
+<li><p>[Long Surf] Again followed by the surface processing for each time point: <code class="docutils literal notranslate"><span class="pre">run_fastsurfer.sh</span> <span class="pre">--&lt;id</span> <span class="pre">&lt;tIDn&gt;</span> <span class="pre">--long</span> <span class="pre">&lt;templateID&gt;</span> <span class="pre">--surf_only</span></code>. This step needs to wait until 3. and 4. (for this time point) are finished.</p></li>
 </ol>
-<!-- Maybe reorganize 2. and 3. into 2.A and 2.B and 4. and 5. into 3.A and 3.B -->
-<!-- TODO: update this section to better explain the parallelization effects, --parallel_seg is parallelization of segmentation steps, --parallel_surf is the parallelization of surface steps, which is the more impactful option for logitudinal processing explicitly, because parallel segmentation may run into GPU memory limitations. -->
-<p>Internally we use <code class="docutils literal notranslate"><span class="pre">brun_fastsurfer.sh</span></code> as a helper script to process multiple time points (in 4. and 5.) in parallel (if experimental <code class="docutils literal notranslate"><span class="pre">--parallel_surf</span></code> is passed to <code class="docutils literal notranslate"><span class="pre">long_fastsurfer.sh</span></code>).</p>
+<p>Internally we use <code class="docutils literal notranslate"><span class="pre">brun_fastsurfer.sh</span></code> as a helper script to process multiple time points in parallel (in the LONG steps 4. and 5.). Here <code class="docutils literal notranslate"><span class="pre">--parallel_seg</span></code> can be passed to <code class="docutils literal notranslate"><span class="pre">long_fastsurfer.sh</span></code> to specify the number of parallel runs during the segmentation step (4) which is usually limited by GPU memory, if run on the GPU. Further <code class="docutils literal notranslate"><span class="pre">--parallel_surf</span></code> specifies the number of parallel surface runs on the CPU and is most impactful. It can be combined with <code class="docutils literal notranslate"><span class="pre">--threads_surf</span> <span class="pre">2</span></code> (or higher) to switch on parallelization of the two hemispheres in each surface block.</p>
 </section>
 <section id="final-statistics">
 <h2>Final Statistics:<a class="headerlink" href="#final-statistics" title="Link to this heading">¶</a></h2>
@@ -571,7 +574,8 @@ <h2>References<a class="headerlink" href="#references" title="Link to this headi
 <li><a class="reference internal" href="#">Longitudinal Processing</a><ul>
 <li><a class="reference internal" href="#what-is-longitudinal-processing">What is Longitudinal Processing</a></li>
 <li><a class="reference internal" href="#how-to-run-your-data">How to Run Your Data</a></li>
-<li><a class="reference internal" href="#behind-the-scenes">Behind the Scenes:</a></li>
+<li><a class="reference internal" href="#single-time-point-cases">Single Time Point Cases</a></li>
+<li><a class="reference internal" href="#behind-the-scenes">Behind the Scenes</a></li>
 <li><a class="reference internal" href="#final-statistics">Final Statistics:</a></li>
 <li><a class="reference internal" href="#references">References</a></li>
 </ul>

dev/overview/index.html

@@ -470,7 +470,8 @@ <h1>User Guide<a class="headerlink" href="#user-guide" title="Link to this headi
 <li class="toctree-l1"><a class="reference internal" href="LONG.html">Longitudinal Processing</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="LONG.html#what-is-longitudinal-processing">What is Longitudinal Processing</a></li>
 <li class="toctree-l2"><a class="reference internal" href="LONG.html#how-to-run-your-data">How to Run Your Data</a></li>
-<li class="toctree-l2"><a class="reference internal" href="LONG.html#behind-the-scenes">Behind the Scenes:</a></li>
+<li class="toctree-l2"><a class="reference internal" href="LONG.html#single-time-point-cases">Single Time Point Cases</a></li>
+<li class="toctree-l2"><a class="reference internal" href="LONG.html#behind-the-scenes">Behind the Scenes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="LONG.html#final-statistics">Final Statistics:</a></li>
 <li class="toctree-l2"><a class="reference internal" href="LONG.html#references">References</a></li>
 </ul>