#pragma section-numbers 1
{{{#!html
<h1>Longitudinal Edits</h1>
}}}

'''<<TableOfContents(2)>>'''

 * This page describes how edits are done in the longitudinal stream of FreeSurfer versions 5.1 and up. 

 * If you use this software for your study, please cite our papers (see [[FreeSurferMethodsCitation]] )! Specifically Reuter et al. !NeuroImage 2012 describing the longitudinal pipeline should be cited.

 * Please read the general description of edits first: [[Edits]].

 * Also make sure you understand the Longitudinal Stream: [[LongitudinalProcessing]].

 * You can also take a look at the [[FsTutorial/LongitudinalTutorial|Longitudinal Tutorial]] that also describes edits.

Generally, '''edit stuff as early in the stream as possible'''. That means first edit the cross sectional runs, rerun from that point to complete the cross sectional run, recreate the base (from scratch, i.e. remove or rename that directory). Check and edit the base, reprocess the base from that point, finally recreate the longitudinal from scratch (removing or renaming the directory if it existed) with the new base. Optimally there should be no editing necessary in the long runs, but it is recommended to check them. For exceptions and special treatment in specific cases see the detailed description below. Note, if you rerun a base or longitudinal from the start, make sure you '''delete or rename''' any existing directories to assert that edits are correctly copied over.

Since the surfaces in the long are initialized with surfaces from the base, it is '''important to edit and fix surfaces in the base'''! Instead of doing everything the nice and clean way (editing as early as possible), you probably get away with just editing the base in many cases.

After editing the base, you need to rerun the base before running the longitudinals (again). When you re-run a base (template) or long run, even partially, you still '''need to pass -base or -long flags''' with the required arguments in addition to the desired parameters (e.g. -autorecon2 -autorecon3). For example:
{{{
recon-all -base <templateid> -tp <tp1id> -tp <tp2id> ... -autorecon2 -autorecon3
}}}
(here replace '...' with more time point flags, if you have them). Then for all time points you run the longitudinals as usual:
{{{
recon-all -long <tpNid> <templateid> -all
}}}

Also note, you '''cannot rename''' any of the time points (cross or long) and rerun during this process. Renaming is only possible if you are recreating the base AND all longitudinal runs from scratch. Instead of renaming, when editing you might want to first '''create a backup copy''' of the existing directory for comparison and to have the option to go back to the earlier results later.

If you just want to quality check results, you would start in the reverse order. First QC the longitudinal runs, if they are fine, there is no need to look at the base or cross results. If you find problems, go up a step to see if these problems exist in the base or cross runs already.

So the rule is:

QC from back to front (long -> base -> cross), once you find where problems occur, edit from front to back (cross -> base -> long).

----

== Cheat Sheet ==

 1. Surfaces in Long are initialized from surfaces in Base (need to be accurate in base)
 1. Edits get usually automatically transferred from Cross to Long (within the time point)
 1. It should rarely be necessary to edit the Long
 1. control points: optional flag -uselongbasectrlvol copies control points from base to long (if only little longitudinal change is expected)
 1. brainmask.mgz: shortcut might be to edit only the base

||<rowstyle="background-color: #E0E0FF;"> '''Edits''' || '''Cross'''|| '''Base'''|| '''Long'''||
||<style="background-color: #FFFFE0;"> '''control points'''||<style="background-color: #E0FFE0;"> 1. fix here (better norm.mgz will improve base)||<style="background-color: #E0FFE0;"> 2. fix, if still necessary ||<style="background-color: #E0FFE0;"> 3. get transferred from cross, fix if still necessary (unlikely)||
||<style="background-color: #FFFFE0;"> '''talairach.xfm'''||<style="background-color: #E0FFE0;"> 1. fix here||<style="background-color: #E0FFE0;"> 2. fix here||<style="background-color: #FFE0E0;"> ''Cannot be edited in long, is the same as base''||
||<style="background-color: #FFFFE0;">  '''brainmask.mgz'''||<style="background-color: #E0FFE0;"> 1. fix (will improve base, which is the union of all masks)||<style="background-color: #E0FFE0;"> 2. computed from all cross, fix if still necessary||<style="background-color: #E0FFE0;"> 3. gets transferred from base, fix if necessary||
||<style="background-color: #FFFFE0;">'''wm.mgz'''|| (maybe here)||<style="background-color: #E0FFE0;"> 1. fix here, should fix longs|| Fix in cross or here, if still necessary||
||<style="background-color: #FFFFE0;"> '''aseg.mgz'''||<style="background-color: #E0FFE0;"> Usually not necessary||<style="background-color: #E0FFE0;"> fix here: if surfaces need to be changed due to incorrect labeling||<style="background-color: #E0FFE0;"> Here: if you want to correct volume of structures||
||<style="background-color: #FFFFE0;"> '''brain.finalsurfs.mgz'''||<style="background-color: #E0FFE0;"> 1. fix here||<style="background-color: #E0FFE0;"> 2. fix here (to fix surfaces in long)||<style="background-color: #E0FFE0;"> 3. edits get transferred from cross and uses surfaces from base. Fix if still necessary.||
||<style="background-color: #FFFFE0;">'''fill/cut seed points'''||<style="background-color: #E0FFE0;"> Usually not necessary||<style="background-color: #E0FFE0;"> 1. fix here|| untested||
||<style="background-color: #FFFFE0;">'''watershed seed points'''||<style="background-color: #E0FFE0;"> 1. only here||<style="background-color: #FFE0E0;"> ''Not possible in base (brainmask is union)''||<style="background-color: #FFE0E0;"> ''Not possible in long''||
||<style="background-color: #FFFFE0;">'''cw256'''||<style="background-color: #E0FFE0;"> 1. only here||<style="background-color: #FFE0E0;"> ''Inherited''||<style="background-color: #FFE0E0;"> ''Inherited'' ||


----
== control points ==

Control points edits can be done to the cross, the base and the long runs.

''Recommendation'': Edit in cross and base.

First CP edits should be done in the cross if necessary. They will influence the norm.mgz and therefore the base, so base and later the long runs need to be rerun (from scratch). If edits have been done to the cross, they are mapped and used in the long runs by default, so also editing the longitudinals should not be necessary! However it might be necessary to also edit the base if the same problem still exists there. It should be asserted that the surfaces in the base are correct, because they are used to initialize surfaces in the longitudinal runs.

''Special cases with little longitudinal change'':
Optionally, CP edits can transferred from the base (instead of the cross runs) into specific longitudinal runs by specifying the ''-uselongbasectrlvol'' in the -long run. This can be helpful if longitudinal structural differences are expected to be very small (e.g. test-retest data). Then the CPs from the base are meaningful in ''all'' affected time points and can be copied, instead of editing each TP individually. To check if an edit in the base is meaningful in several time points, you can open all these images on top of each other (e.g. using freeview), as they are in the same voxel space (since FS 5.1).

In both cases (mapping CP from the cross, or transferring them from the base), it is recommended to check if all CPs are accurately placed in the long. They might move into a neighboring voxel when mapped from the cross, due to the resampling of the mapping, or they might not be meaningful due to longitudinal change when taken from the base.

----
== talairach.xfm ==

''Recommendation'': Edit in cross and base.

A broken talairach.xfm can badly influence many downstream results. Therefore it is important to edit these problems if they occur, as early as in the cross sectionals.

The talairach.xfm is common for all longitudinal runs. It is taken from the base and therefore also needs to be checked and edited there.

----
== brainmask.mgz ==

The brainmask.mgz can be edited in the cross, base and long.

''Recommendation'': Edit the cross and base.

''QA Shortcut'': instead of inspecting the brainmask.mgz in all time points, you can instead inspect the brainmask.mgz in the base of each subject. If it is incorrect, check all cross time points of that subject and fix brainmask there, re-run cross with -autorecon2 -autorecon3 and re-run base from scratch. The base brainmask should be OK now, if not, repeat.

''Info'': The brainmask in the base is a union (logical OR) of the brainmasks from the cross. Therefore, if the base is started after the cross have been edited and re-run, it will contain edits from the cross (delete the base if it already existed, before recreating it). The longitudinals all use the brainmask from the base, therefore the brainmask should be edited first in the cross, then manually in the base if it is still not correct there.

''Possible Edit Shortcut'':
It might be enough to only edit the base, the brainmask will then be copied to the longitudinal runs and should fix things there.

''Edits to Long'':
In rare occasions it might be problematic to use a single brainmask (from the base) for all time points due to significant longitudinal change in the images. In that case the individual brainmask in the long runs can be edited as a last resort.

''Warning'': if the brainmask.mgz is available in the <tp>.long.<template>/mri directory it is assumed that it contains manual edits and will be kept untouched (i.e. edits from base will not be transferred). Therefore, you should either rerun the longitudinals from scratch or delete the brainmask.mgz to make sure your edits are correctly transferred after editing cross or base.

----
== wm.mgz ==

WM edits can be done in cross, base and long.

''Recommendation'': Edit in base.

The wm.mgz (and consequently the filled.mgz) are used to create the surfaces. Since the final surfaces of interests will be created in the long, and since those are initialized from surfaces in the base, it is essential to edit the base and fix any surface problems there. Otherwise a longitudinal run might not recover from the incorrect initial surface placement even if it contains WM edits.

It is possible to edit WM in the cross sectionals to fix surfaces there, but these surfaces are ''currently'' not used later in the process. If cross is edited, WM edits will be automatically transferred to the longitudinals. Note that, if the wm.mgz in the long already contains edits (either manually or due to earlier transfer) it will not be updated (merging is not possible). WM edits only have a very limited influence on the surfaces in the longitudinal runs, therefore it should be sufficient to edit only the base. 

----
== aseg.mgz ==

ASEG edits can be done in cross, base and long.

''Recommendation'': Edit in long only if you want to correct the volume of important structures. Edit in base if surfaces need to be changed due to incorrect labeling of aseg. Not necessary to edit in cross.

The segmentation in the long runs is initialized with a fused aseg (a weighted average of the cross sectional asegs). Thus any edits done to the cross sectionals are incorporated indirectly into the long stream. But since the fused aseg is used only for the initialization, it can happen that manual edits from the cross get removed again. Therefore, to correct the volume, just edit the long.

----
== brain.finalsurfs.mgz ==

brain.finalsurfs.mgz edits can be done in cross, base and long.

''Recommendation'': Steps to follow:  1. Edit in cross, re-run cross  2. Edit in base, re-run base  3. Use new base and cross to create new long. If this long still contains errors, edit in long re-run long.  

When editing make sure you copy brain.finalsurfs.mgz to brain.finalsurfs.manedit.mgz and edit that file! Cross should be edited in the timepoints with errors. These edits will not be transferred to base, so base should be checked separately and edited as needed. Use the newly constructed cross and base to create new longs (from scratch). Edits from cross should be transfered to long and the fixed surfaces from the base will also be used in the longs. Check the resulting long data-set: if errors still exist, edit in long and re-run.  
NOTE: If edits were made directly to the long initially, the manedit file created in the long should be removed before re-creating the long from scratch (when using an edited cross and base). Doing this will allow the edits from cross and base to take effect. The surfaces in long are initialized by the surfaces in base. So edits in the base are necessary to make sure they are accurate there.

----
== fill and cut seed points ==

Seed points for cut/fill can be specified in cross, base and long.

''Recommendation'': Edit in base.

The surfaces in long are initialized from the surfaces in base. Edit the base to make sure surfaces are accurate in the base.
So far seed points are not transferred.

----
== watershed seed point ==

Seed points for watershed can be specified in cross only.

In base and long the brainmasks are created from the cross sectional masks (union = logical OR).

----
== cw256 ==

cw256 is specified only in cross.

Both base and long will indirectly inherit this setting as they create their orig in the unbiased template space, cronstructed by
registering the norm.mgz from the cross (which are FOV corrected).

----
== expert options ==

Expert options are currently not supported in base or long. Feel free to try if it works (and let us know).

----

== Rerunning Edits Commands ==

Depending on at which part of the stream you make your edits, here are example commands (for WM edits) you will need to run afterward.

 * If WM edits were made on the cross, run (for all timepoints where edits were made):
{{{
recon-all -s tpN -autorecon2-wm -autorecon3
}}}

Then delete or rename the base, and rerun (here '...' means more time points if you have them):
{{{
recon-all -base templateID -tp tpN1 -tp tpN2 ... -all
}}}

Then delete or rename the longs and recreate them (for all timepoints):
{{{
recon-all -long tpN templateID -all
}}}
----
 *If WM edits were made on the base, run (here '...' means more time points if you have them):
{{{
recon-all -base templateID -tp tpN1 -tp tpN2 ... -autorecon2-wm -autorecon3 
}}}

Then delete or rename the longs and recreate them (for all tpNs):
{{{
recon-all -long tpN templateID -all
}}}
----
 *If WM edits were made on the long only, run (for all the longs that were edited):
{{{
recon-all -long tpN1 templateID -autorecon2-wm -autorecon3
}}}

----

MartinReuter