# average-dofs¶

## Synopsis¶

average-dofs <dofout> <dofin>...       [options]
average-dofs <dofout> -dofnames <file> [options]


## Description¶

This command averages a number of input transformations. It can be used to construct a brain image atlas and has been utilized for the construction of the spatio-temporal fetal/neonatal brain atlases available at http://brain-development.org/brain-atlases/.

The transformations which can be averaged by this program are listed below, commonly expressed as “sum of global and local transformations”, i.e.,

$T(x) = T_{global}(x) + T_{local}(x)$
 Linear $$T(x) = Ax, T_{global}(x) = A x, T_{local}(x) = 0$$ FFD $$T(x) = x + d(x), T_{global}(x) = I x, T_{local}(x) = d(x)$$ MFFD $$T(x) = Ax + d(x), T_{global}(x) = A x, T_{local}(x) = d(x)$$ Fluid $$T(x) = x + d(Ax), T_{global}(x) = A x, T_{local}(x) = d(Ax) - (Ax - x)$$

where A is a linear 4x4 transformation matrix, and d(x) is a non-linear displacement. Note that in case of the fluid transformation, d(x) is the total displacement instead of the local displacement only. By subtracting the displacement induced by the global transformation, the displacement corresponding to the local deformation only is obtained. Note that in case of MFFDs, the total displacement introduced by all local transformation levels is used to compute the average local transformation and thus multiple levels are allowed. Representing all transformations as sum of global and local transformations enables the computation of an average transformation for a given target domain from an arbitrary mix of input transformations.

Accordingly, the resulting average transformation is set to be equal the sum of the Log-Euclidean means of the global transformation matrices, A, of the input transformations and the corresponding local transformations. The bi-invariant global mean is computed instead using the barycentric fixed point iteration when average-dofs -bi-invariant is given. Before the computation of the local mean transformation, any dependency of the local displacement on the global component is removed by pre-multiplying the displacement vectors by the inverse matrix of the global transformation . Moreover, the (optional) local component of the final average transformation has to be taken into consideration as well. Therefore, all local input displacements are made relative to the same position after global transformation, i.e.,

$d(x) = \bar{A} \circ A^{-1} \circ T_{local}(x)$

The average of all transformation parameters is computed in the “log-space” by default. Thus, in case of the local displacement fields, d(x), the corresponding stationary velocity fields, $$v(x) = log(d(x))$$, are averaged instead. If the input transformation itself is parameterized by stationary velocities, these velocities are used directly when possible to avoid the redundant $$log(exp)$$ computation and its numerical error. The resulting average velocity field is then either combined with a suitable velocity-based transformation model or exponentiated again to obtain the final average displacement field, $$\bar{d}(x)$$.

The output transformation will be an affine transformation if only the global transformation parameters were averaged, or a MFFD with one level corresponding to the average FFD otherwise. The type of the output FFD depends on the type of the input transformations. If all transformations are either a linear transformation or a FFD with cubic B-spline or linear interpolation kernel (may also be contained in a one-level MFFD), the ouput FFD will contain the average parameters of the input FFDs. If the average is computed in the log-space, this only applies if all input FFDs are parameterized by stationary velocity fields. In all other cases, the output FFD will be either defined in the image domain of the input target image or the first encountered input FFD with a linear interpolation kernel and a control point spacing corresponding to the voxel size. In other words, the output FFD is in general a dense (“non-parametric”) displacement field.

  Rueckert et al., Automatic construction of 3-D statistical deformation models of the brain using nonrigid registration, IEEE TMI, 22(8), 1014-25 (2003)

## Input options¶

-type <name>

Common type/class name of input transformations. If not specified or when -target is not used, the input transformations may need to be opened and read twice from disk. Use this option when all input transformations have the same known type to avoid the extra I/O. Not needed when -nodofs option given.

-target <file>|common

Either file name of reference image or (M)FFD transformation. When all input (M)FFDs have the same type and attributes, “common” can be specified to use the attributes of the first input FFD. When used together with the -type, this avoids reading all input transformations twice, where during the first pass it is determined whether and which type all input transformations have in common and on what discrete lattice to possibly average the parameters directly. If not specified and local transformations are to be averaged, the attributes of the first local transformation are used.

-dofnames <file>

Text file listing input transformations and associated values.

-dofdir <dir>

Directory used to make relative paths in -dofnames text file absolute. (default: cwd)

-prefix <string>

Prefix for transformation name entries in -dofnames text file. (default: none)

-suffix <string>

Suffix for transformation name entries in -dofnames text file. (default: none)

-gaussian <mean> <sigma>

Use Gaussian kernel weights. Requires -dofnames to specify transformation values. By default, if -dofnames is used or <sigma> is 0, the values specified in the text file are directly used as kernel weights for the averaging instead of using these values as arguments for the Gaussian kernel function.

-epsilon <value>

Weight threshold. (default: 0.001)

-add-identity

Assume additional identity transformation as part of input transformations. (default: none)

-add-identity-with-weight <value>

Assume additional identity transformation with given value/weight. (default: none)

-add-identity-for-dofname <name>

Assume identity transformation for named input transformation. Note that if this option is used, the named input transformation file which is listed in the -dofnames list does not need to exist. (default: read input transformation from file)

## Average transformation options¶

-rotation, -norotation

Average rotation or assume none to be present. (default: off)

-translation, -notranslation

Average translation or assume none to be present. (default: off)

-scaling, -noscaling

Average scaling or assume none to be present. (default: on)

-shearing, -noshearing

Average shearing or assume none to be present. (default: on)

-deformation, -nodeformation

Average deformation or assume none to be present. (default: on)

-local, -nolocal

Alias for -deformation.

-log, -nolog

Whether to average local transformations in log-space. (default: no, unless the -dofs of a SV FFD are averaged directly)

-log-euclidean

Compute Log-Euclidean means. (default: off)

-bi-invariant

Compute global bi-invariant mean, i.e., exponential barycenter. (default: on)

-dofs, -nodofs

Average the local transformation parameters directly. When this option is off, the corresponding (dense) displacement fields are averaged instead. (default: yes, unless input contains mixed FFD types or common type does not support this)

-inverse-dofs

Average inverse input transformations and invert the average again. (default: off)

-rigid

Enables averaging of -translation and -rotation components, and disables averaging of -scaling, -shearing, and -deformation.

-norigid

Disables averaging of -translation and -rotation components.

-affine, -global

Enables averaging of -translation, -rotation, -scaling, and -shearing, components and disables output of average -deformation.

-noaffine

Disables averaging of -rotation, -translation, -scaling, and -shearing components.

-noglobal

Same as -noaffine, but also forces output of non-MFFD.

-all

Enables averaging of -rotation, -translation, -scaling, -shearing, and -deformation.

-linear

Force average output transformation to use linear interpolation.

-cubic

Force average output transformation to use cubic B-spline interpolation.

## Standard options¶

-v, -verbose [n]

Increase/Set verbosity of output messages. (default: 0)

-debug [level]

Increase/Set debug level for output of intermediate results. (default: 0)

-version [major.minor]

Print version and exit or set version to emulate.

-revision

Print revision (or version) number only and exit.

-h, -help

Print help and exit.