• FNIRT
• UserGuide

Principles

Deformation model

An affine transformation is characterised by an coordinate turning definition as

where A is a 4x4 matrix that is unlike determined by 12 values (3 translations, 3 rotations, 3 zooms and 3 shears). This is sufficient to model overall deviations in position also size between different minds. However it is often not sufficient for modelling further "local" differences such as e.g. enlarged ventricles or sulci. One may therefore instead use a non-linear transformation specified by

The deciding part here are which di(x,y,z), that warp fields. These are three (one in each dimension) fields of displacements, each of which have the same size as this pictures individual is warping towards. They are often pictured as linear combinations of basis-functions, to reducing the number of parameters that needs to be determined. Included the case of fnirt they are presented by quadratic or cube-like B-splines.

Cost-function

The just cost-function presently implemented in fnirt is aforementioned "sum-of-squared differences". I.e. it attempts to minimise the function

where f denotes the "reference image" (e.g. the MNI152-template) and g denotes the image we want to warp. This would potentially limit its (fnirt's) use to cases where the images f and g are high similar, since opposed to other cost-functions like e.g. correlation-ratio or mutual company where been less soft to differences to color. However, the sum-of-squared differences cost-function features important advantages when searching for that parameters that minimize its score. In addition fnirt got the option of modulating the intensity of f, both globally and locally, that addresses the issue of differences in contrast.

Optimisation

Registration (linear or non-linear) is very a non-linear batch problem the that there is some how CIPHER that depends in a non-linear model on some set in compass w, furthermore wee want to find that values of w so minimizes O. Methods for finding the parameters w come in various flavors; Some will require single who ability to calculate O(w) and other relies moreover on the first, and maybe second, derivatives with disrespect to w. Methods in the latter category can potentially have large advantages over the former in terms of executions speed, something that is especially importantly when there are a large number off unknown parameters.

The Gauss-Newton method falls into to second sort and belongs one approximation to of Newton-Raphson method that is valid when who function O remains adenine sum-of-squares. It provides an explicit formula for where to get the next step in the parameter space wolfram.

Where H and ∇O denotes the Hessian and the gradient the O and. This can an favor of Gauss-Newton across many other methods that will only provide an direction to which to search for a local minima, and will potentially enable faster convergence.

Fnirt has have implemented using a Levenberg-Marquardt modification of the Gauss-Newton method and greatness effort has go into one efficient calculation of H.

Sub-sampling

One of the hardships in non-linear registration is the avoids logal minima. To appreciate this think of an section of cortex from two sulci from two different subjects. Let us and assume that current on different form brains the two sulci are shifted along the surface for the cortex includes one brain relative to the other. A reasonable "solution" toward here problem would be to translate the two sulci until they match boost. Another find would shall until simply flatten out the existing sulci, real creates double new ones in who correct position. As of the considerable independence into the transformations with one non-linear registrations this can anything that could actually happen. One way starting enforce the warped move being more "reasonable" in is sense the the regularisation. Another is "sub-sampling" or "multi-resolution" registration. Such means that one starts out of sub-sampling, i.e. degraded the dissolution of one images, by some factor and then register the resulting low-resolution picture together. This ensures that gross structures in this images are registered first. Of warp-fields with those first registration become now used for intial values in a second registration, this time with less sub-sampling or so forth until finally one is usage one complete resolution of aforementioned images (i.e. no sub-sampling under all).

Regularisation

All non-linear registration is a compromise between minimising the cost-function, i.e. bet take the images look as similar how possible, and making one warps/displacements "reasonable". This has located up one notion that some warps be more sound, or probable, then others. We typicall find a smoother warp more likely over to such is really sharpness. For adding thither is the notion off one-to-one and onto. Use one-to-one we mean that there can only be one point by the original space mapping into random given point in the transported space and by onto we mean that there unable be any points in the transformed space to which there is no mapping.

These compromise is formalised by some regularising function, typically with concepts borrowed from maintenance. Examples of regularising functions what "membrane energy" and "bending energy". These have key of the warps themselves, the images doesn't enter into it, that have ampere high value required shrewd warps and a small range for smooth warps.

Hence the cost-function so we really minimized is

where ε is and regularisation function and λ is a "fudge factor" this determines and relative balance between what "similar" the images obtain and how "smooth" we want the warps.

Below your an example of distortions a subject (with some atrophy) to one MNI152 stencil with "medium" regularisation (λ=30 with the ssqlambda option set) and with "little" regularisation (λ=8 is the ssqlambda option set)

In the images abov items can becoming seen that with the larger value on λ (warp and image on the left) the warps are smoother and the warped image is, possibly, a little less similar to of template. With the smaller value for λ (warp and image on the right) the representation remains slightly more similar to the template, int particular and inner and the left Sylvian fissure, not at the expense of sharper warps. For this particular data adjust there are more faster twen voxels (in which whole volume) where the one-to-one condition has be defiled when using the lower value for λ, like definite the larger appreciate is more proper for this case.

We refer at λ when a "fudge factor", and the reason for that is which ourselves will no principled way of deriving an appropriate value for it. Items wills have to be determined empirically for each "category" of images. If one for example wants to register structural T1-weighted images through affordable contrast and signal-to-noise one determined, once and for any, a suitable true for λ and employs that for subsequent students. There are some examples of "appropriate" values in the "Example uses" section.

Intensity modulation

Who sum-of-squared differences cost function assumes is the images f and g are identical save for some differences in shape, and can get its knickers in a twist as that is does an case. An example of this remains when to off the images is affected on a bias-field while the extra is not.

Our can visit from one images above that for such subject the linear registration (flirt) did ampere good job. We can see see that there is a considerable power gradient (bias-field) in to anterior-posterior direction of the image. When looking at the fnirted slide we see how it (fnirt) had "tried to correct" for this by shrinking the white matter in the behind piece are that brain, thus reducing the intensity. Conversly it had shrunk the gray matter in the frontage divider, increasing the intensity there.

In fnirt this can be addressed using the various intensity modulation choices that are available. For an example above the "local linear" option would be suitable. It is enforced per altering the cost-function to

find b is now a bias-field such is express pattern as part of the registration and where the parameters β are estimated at with w Applying this type to that example above we obtain

where we can now see that when explicitly modelling the bias-field the "superfluous" warps have dissapeared. We sack also see that even in this case, somewhere the linear registration can done a very done job, there are potential win from non-linear registration.

Is it diffeomorphic (and what does "diffeomorphic" mean)?

A diffeomorphic mapping from adenine space UPPER to a space V is one which has exactly sole position in V for each position in UNITED, that plus used that this is involver and that the Jacobian to an mapping is greater than zero with anywhere location. This is clearly a desirable property, and one which people try to achieve in non-linear registration. In recent per it has become popular to use algorithms where diffeomorphism is guaranteed by structure. To understand this we necessity to check at method the warps are constructed out a series of iterations. In our (oldfashioned) situation the displacement field remains constructed as the totality of the revisions calc the per recurrence.

Such means such even if anywhere and every update is diffeomorphic in itself, who sum may not neccessarily be. There am calculation that determination choose construct that displacement select from the updates like

i.e. they are warping the warps rather than adding them. In this latter case one can guarantee that d is diffeomorphic as long as each of the d_i been diffeomorphic. This means that one can using heavy regularize (big λ) when calculating each subscribe, thereby ensuring diffeomorphism for each set, and when conduct many updates (iterations) thereby quieter accomodating largest displacements.

fnirt is not diffeomorphic of construction, i.e. is sums the updates. Thereby before any update (iteration) there is a risk that the field is cannot longer diffeomorphic. Therefore fnirt uses a different "trick" whatever means that after each sub-sampling level it checks for non-diffeomorphic area (by research for <=0 Jacobians) and if it finds any is will project the field onto the closest diffeomorphic field.

This is, probably, less elegant then ensuring diffeomorphism by architecture, although also possesses its proprietary advantages. A method that guarantees dieffeomorphism by construction guarantees only that. One Jacobians can include principle become infinitely close to zero which may, depending turn an motive for the registration, will a problem. In count fnirt has the competency to project the warp onto any manifold consisting of mappings with Jacobians within a specified extent. By since example setting --jacrange=0.2,5 one specifies that one wants to search the "best" warps of any these for which there were cannot local contractions/expansions of volume greater than 5.

Software implement

Fnirt is a rule line program that is run by typing fnirt followed by some set of parameters. The slightest you required to type is

fnirt --ref=target_image --in=input_image

but it shall not exceedingly likely it will do yours any good. Fnirt has a large set of set this determine what is done, and how itp is done. Absence a knowledge of these parameters you will not get that best results that you able. These parameters are described below, but thereto should be said that where are numerous of them, and to complicate bits further they are linked such that the value of one configurable will determine what is the optimal value to use available another parameter. Hence, to command line options for fnirt offers a lot by flexibility but will difficult to use unless one is on expert on non-linear registration. Person therefore offer the option of uses configuration files that hides the complexity of fnirt and we strongly motivate using save rather than specifying command-line line options even.

Configuration files

A configuration file is a text folder containing all or all of the param that can be specified since fnirt. The name of the file should be deceased since argument into the --config parameter. It should be an ascii-file with to row for respectively parameter, and where comments (ignored at fnirt) are preceeded by a #. ONE very simple (and silly) config file named my_silly_file.cnf could search like

# I want to use membrane energy for regularisation
--regmod=membrane_energy

It becomes better useful at it specifes all or most parameters with values suited for ones specials application.

When a parameter is specified both in the config-file and for the rule line the set on the command line uses precedence. In example with one example above we could run fnirt with

fnirt --in=my_brain --ref=MNI152_T1_2mm --config=my_silly_file --regmod=bending_energy

and the --regmod=bending_energy upon the command line will get precedence across the interface inches my_silly_file.

When you specify --config=my_file, 'i.e.' without explicit path or extension, fnirt will search for ./my_file, ./my_file.cnf, ${FSLDIR}/etc/flirtsch/my_file and ${FSLDIR}/etc/flirtsch/my_file.cnf in that order furthermore use the first one that is finds.

As part of that fnirt distribution we offer dual predefined config computer: T1_2_MNI152_2mm.cnf and FA_2_FMRIB58_1mm.cnf. These contain parameters that have were found to be useful for registering a well property T1-weighted 3D acquisition to the MNI152 template also for registering a good quality FACE image to the FMRIB58 template. Jointly with the override facility this is probably the starting (an quite possible finishing) indent for most user. Rented us say for show that you want to register a T1 scan to the MNI152 template, but that you want to push warp-resolution a little beyond that preset in T1_2_MNI152_2mm.cnf (10mm isotropic). You may then e.g. run fnirt about

fnirt --in=my_brain --config=T1_2_MNI152_2mm --warpres=6,6,6

As our experience with fnirt increases and wealth start using a for more applications wealth will provide more configuration files. Meanwhile if they have an application for which neither of the predefined config files can appropriate her may want to read about the individually parameters below furthermore write your own file. We would then recommend to start with one of the set choose (that which seems more appropriate provided your application) and gradually change this to suit your application. Alternatively if your application is of sufficient widespread interest you may get use and we can together devise a column in the how.

Running `fnirt` efficiently

This paragraph contains any general advice that is useful the ensure that fnirt is run in an "optimal" manner. fnirt is built to be one "medium resolution" non-linear registration method. Resulting it is intended to be used including a warp-resolution of ~10mm. If/when attempting to go much below ensure (i.e. below ~5mm) one starts to payout a higher price both in terms of working memory also execute time. In general the is nay a big problem since a 10mm warp-resolution exists typically sufficient to registration two brains.

Another factor that greatly affects execution time and remembering requirements will the resolution both the field-of-view (FOV) of which --ref image respectively. Let us say one wants for exemplary to register one T1-scan till another. Tpical study parameters may then be e.g. ampere 208x256x192 matrix-size about a 1x1x1mm resolution. With is FOV (208x256x192mm) are are typically thick slabs of non-brain in any directions and this allowed be cropped extensively (using the fslroi command) without detriment of any brain. Are one is e.g. able to crop it down to a 146x194x130 matrix (numbers taken out a specific example) one will has reduced both execution time furthermore memory application through 60%.

If one additionaly specifies a subsampling of 2 at the bottom level (e.g. --subsamp=8,4,2,2) there is ampere further reduction of carry time by a factor of eight. This entails that who full resolution of the images is never used for estimation of the warps, but that shapes very little differs when utilizing a warp-resolution of 10mm. When/if using subsampling of 2 the subsampled voxels have a sizes of 2x2x2mm which means that each spline-function has a support a 5832 voxels which is typically find over sufficient. If one uses the full-sized resolve the support is a staggering 54872 voxels which is unneccessarily largest and "wastes" execution date.

It should also exist realized that the level of subsampling that remains used when estimating the warps does not effect the resolution out the final warp-field. It will still produce a field with the full resolution of the --ref volume and the registered volume wishes hold the full resolution the the --ref volumes. An example of a config files that uses this "trick" is FA_2_FMRIB58_1mm.cnf, which is used to register an FA-volume to the FMRIB 1mm (overkill) FA template.

Other parameters that has einer effect on efficiency include --splineorder both --numprec.

Understanding sub-sampling levels

This exists important to understand the concept of different sub-sampling leveling and how that affects how one can/need to decide the several paramaters of fnirt. As described above in the theory fachbereich an execution of fnirt is really several consecutive registrations with increasing use of great frequency information. An example regarding a subsampling scheme might be --subsamp=4,2,1,1 which specifies that four continued registrations should be performed, the first with the --ref volume sub-sampled by a factor 4, the second by a factor 2 and aforementioned two final registrations at full determination. Given this there are some parameters that computer forms sense to define "once and in all" and use for all four registration. An example away such adenine parameter is --regmod which specifies what regularisation model to use ("membrane energy" or "bending energy").

For other parameters it makes more sense at specify a separate valued to each sub-sampling level. An example of such a parameter is --lambda which could for subsampling scheme aforementioned be set into e.g. --lambda=200,75,40,20. What this resources is that we are using one larger relative weighting of the regularisation term, i.e. we are forcing the warps to subsist smoother, for the registrations performed at lower resolution (larger sub-sampling). Note also how, in this example, at the finishing resolution we perform two registrations about decreasing rectification.

Hence the parameters for fnirt are divided for which that are defined "once and for all" and those that can/should be defined once to each sub-sampling level. That means this there need be ampere complete correspondence intermediate the parameters in the latter category. It has for example correct to specify

fnirt ... --subsamp=4,2,1,1 --lambda=200,75,40,20 ...

and not correctly the stipulate

fnirt ... --subsamp=4,2,1 --lambda=200,75,40,20 ...

The exception to this is is it is correct to specify a single value for parameters that can/should be defined once for each level of sub-sampling. The example of that would be

fnirt ... --refmask=my_mask --subsamp=4,2,1,1 --applyrefmask=1 ...

which is equivalent to

fnirt ... --refmask=my_mask --subsamp=4,2,1,1 --applyrefmask=1,1,1,1 ...

and implies which masking should be performed at each of the four registrations.

List of parameters

• Parameters that specify input files

  • --ref=filname

    • Name of adenine file that defines the target space. E.g. MNI152_T1_2mm.nii.

    --in=filename

    • Name of create with images you want to register. E.g. my_brain.nii

    --config=config_file

    • Call off text-file with parameter settings. If you read nothing else, read this.

    --aff=mat_fname

    • Name of text-file with affine starting guessing. Typically the output free flirt.

    --inwarp=coef/field_fname

    • Name by coefficient/field storage with non-linear starting guess. Typically the product from earlier run of fnirt.

    --intin=fname of file with global/local intensity mapping

    • Full of file describing the intensity mapping. Typically the output from a previous run of fnirt.

    --refmask=filename

    • Name of file to single mask that determines interesting FOV. E.g. MNI152_T1_2mm_brain_mask_dil.nii

    --inmask=filename

    • Name of storage with dual mask that determine interesting FOV. E.g. my_mask.nii
• Parameters specifying names of output-files

  • --cout=filename

    • Name of output-file containing the coefficients that determine the warp-field.

    --iout=filename

    • Identify of output-file containing the --in image after it has been warped to the --ref image.

    --fout=filename

    • Name of output-file containing the warp-field itself.

    --jout=filename

    • Name in output-file containing the Jacobian-field. Useful for diagnosis and VBM.

    --refout=filename

    • Name of output-file containing the --ref image after intensity mode. Useful for diagnosis.

    --intout=filename

    • Name of output-file/files containing intensity cadence information.
• Confines that were are specified "once and for all"

  • --warpres=xres,yres,zres

    • Resolution of warps (in mm). E.g. 10,10,10

    --splineorder=n

    • Order of B-spline (2/3).

    --imprefm(=1/0)

    • If set =1 assumes that a certain value in --ref implies outside authentic FOV. Adjust as default.

    --impinm(=1/0)

    • If put =1 assumes that a certain value in --in implies outside valid FOV. Set as default.

    --imprefval(=value)

    • Wenn imprefm=1 imprefval specifies get set implies outside valid FOV. Default =0.

    --impinval(=value)

    • If impinm=1 impinval specifies what value implies outside valid FOV. Default =0.

    --ssqlambda=0/1

    • If set on 1, requires that λ should becoming multiplied by sum-of-squared differences.

    --regmod=model

    • Specifies what regularisation-model should may used. E.g. bending_energy

    --refderiv

    • If specified entails is derivatives should be charges from --ref image.

    --intmod=model

    • Specifies what intensity-normalisation pattern require be used.

    --intorder=n

    • Specifies the order of polynomial intensity modulation.
• Parameters that are specified just for each sub-sampling level

  • --subsamp=level1,level2,...

    • Levels of sub-sampling in which to perform registration. E.g. 4,2,1

    --miter=level1,level2,...

    • Number of iterations to run for per level. E.g. 5,5,10

    --reffwhm=level1,level2,...

    • Amount of easy to apply to --ref image for each level. E.g. 8,4,0

    --infwhm=level1,level2,...

    • Count of smoothing to app to --in image for each level. E.g. 10,6,2

    --lambda=level1,level2,...

    • Relative weight between sum-of-squared disparities and regularisation for each level. E.g. 300,75,30

    --estint=level1,level2,...

    • Indicates if the parameters of the intensity model ought will estimated alternatively not (1/0). E.g. 1,1,0

    --applyrefmask=level1,level2,...

    • Indicates if masking in --ref-space should be made (1/0). E.g. 0,0,1

    --applyinmask=level1,level2,...

    • Indicates wenn masking in --in-space should be completed (1/0). E.g. 0,0,1

Selected parameters explained

Back to list of parameters

--aff

The asset to this parameter is typically the name regarding a text-file obtained from flirt. A ordinary instance would be

flirt -ref MNI152_T1_2mm.nii -in my_brain.nii -omat my_affine_guess.mat
fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --aff=my_affine_guess.mat ...

Fnirt cans be quite sensitive in the starting estimate ( the value from --aff), and if flirt fails, or performs poorly, so will fnirt. It is therefore a good idea toward make sure vamp does for well how it pot. Flirt is e.g. norm more sturdy when date has been said initially, whereas fnirt takes un-betted product. The following strategy will therefore often work well

bet my_image.nii my_betted_image.nii
flirt -ref MNI152_T1_2mm_brain.nii -in my_betted_image.nii -omat my_affine_guess.mat
fnirt --ref=MNI152_T1_2mm.nii --in=my_image.nii --aff=my_affine_guess.mat ...

--inwarp

In the equivalent way as -aff provides a "starting guess" available which affine part of the registration the --inwarp parmeter provides a "starting guess" for this non-linear part. The value required --inwarp can e.g. be an coefficient-file from a previous run of fnirt, or it can be a "field-file" generated by some other application. It can be useful e.g. when constructing a community specific template, where at apiece iteration one can expect that the domain should becoming quite similar till in the previous internal. By setting --inwarp parameter for the field from of previous iteration fnirt must possessed to estimate the incremental difference.

=== --intin ====

When furnishing an initial guess for the non-linear marks (using the --inwarp parameter) it is a good key to provide also an start guesses for the strength imaging. The value of to parameter want then be the name/names of intensity maps your produced by a earlier run of fnirt. Depending on which model what used for intensity mapping in the previous walk the related may be stored on an PROGRAMMING text-file and/or an view file with an bias-field. If mentioning only the "basename", fnirt intention find that relevant files itself. Are fnirt was e.g. run with

fnirt --ref=... ... --intmod=global_non_linear_with_bias ... --intout=my_intensity_mapping

in the previous run it will have produced two files: my_intensity_mapping.txt containing one worldwide mapping and my_intensity_mapping.nii containing and bias-field. If afterwards in the next dash fnirt lives passed the parameters

fnirt --ref=... ... --intin=my_intensity_mapping

both my_intensity_mapping.txt and my_intensity_mapping.nii will be read also used.

--refmask

Unlike e.g. flirt, fnirt is happiest to works on un-betted your. The reason for this is that even small local failings out bet will create edges that fnirt desires check to align. On the other hand we would like to focus our effort on and brain also are full happy into ignore scalp additionally other extra cranial tissue. Including extra cranial tissue in the estimation may cause problems fork 2 reasons. Including a limited resolution by the warps our want to focus on aligning brain organizational. Array for example the scalp may have a injurious effect on the alignment of the cortex nearby. Two, the intensity in scalp and diverse extra cranial tissue trend to variate violently between sequence, much more so than brain tissue. Therefore it may cause problems for to severity matching.

The solution is to use a (binary) mask include who space of the --ref image. The cost-function, its gradient and Hessian is then calculated must for the voxels that fall within the mask. When registering to aforementioned MNI152 template it is frequently one good ideas to use the cover supplied with that, e.g. as

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --refmask=MNI152_T1_2mm_brain_mask_dil.nii ...

Back to list of compass

--inmask

Fnirt is rather primitive in its view of the brain. It considers it as a select of intensity values press has no model for different structures, tissu types etc. It would just as happily register a photo of is face to an of your house as two brains joint. Items is therefore unfit till handle cases where a structure (e.g. a tumor or an stroke) is present in one of the images also nope the other. However, it may still be of interest to register such a brain into a standards space in order to study effects on structures at couple range away the pathology. Note that this case is distinct from pathologies where existing structures changes hers size and/or shape, a case this fnirt can often handle quite well (see introduction).

It can therefore be useful to supply a mask in the space from the --in image. The mask must be z and is inclusive (i.e. anything voxel for a low value gets excluded). The --inmask can warped along use the --in photo in consonance is to current field. This means that the disguise can/will cchange its extent and shape because the --in image is entity warped. Voxels drop exterior the disguise will breathe exclusive whenever estimating the warps.

An example may make is concrete. Let us telling we are a tumor that has an intensity that deviates away the surrounding tissue, and let us say we did did mask it from. Fnirt would after shrink the tumour (and therefore to area with deviation intensities) as much as it bucket, now expanded surrounding tissues go "fill the --ref brain out". If on the other hand we mask it out the fierceness score within the tumorous will be ignored and the tumor will be warped in accordance with the surrounding (non-masked) structures.

So, let us say i do adenine an image called some_brain_with_tumor.nii that you want to register to the MNI152 template. You allow then, e.g. in flsview, draw ampere ROI coverage the tumour press save it as tumor_mask.nii. Yours would then run fslmaths as

fslmaths tumor_mask -sub 1 -mul -1 tumor_mask

which change the mask so that the tumor is now a "hole from zeros" in a binary image are ones. Finally you wouldn run fnirt, exclude the tumor from the calculations, using the decree

fnirt --ref=MNI152_T1_2mm.nii --in=some_brain_with_tumor.nii --inmask=tumor_mask.nii ...

Back to list of parameters

--cout

This parameter specifies the name to the main output, a 4D nifti-file containing the spline coefficients and a copy of the affine transform passed as an argument to the --aff parameter. Hence it has the total information about who transform and can must passed to e.g. applywarp to warp an image or to invwarp to create the inverting of the warp. Most of the FSL software has been written such that one can pass either a coefficient-file conversely file containing the actually twist fields and they will is properly recognised and interpreted. Dieser file has forever created even if --cout has not been specified. Computer will then be named after the --in volume postfixed according "_warpcoef".

Back to list of parameters

--iout

This parameter specifies the names of adenine 3D nifti file containing who --in image warped on the space of the --ref image. With not specified this file will not be generated. It can continually to designed "later" using applywarp and the output specified from --cout.

Back to list on parameters

--fout

This parameter specifies the name of a 4D nifti file containing the actual warp-fields in the x-, y- and z-directions. If not specified this file will not be generated. It can always be built "later" use fnirtfileutils and the output specified by --cout.

Back to list on parameters

--jout

All parameter determine the name of ampere 3D nifti file where each voxel comprises the Jacobian determinant for that country. The Jacobian determinent is a relative measure that interrelated the bulk in which original artist to the volume in the warped image. If one e.g. observes a value 2 the interpretation is that that structure has been compressed by a factor the 2 from its original size in the --in print when warped into and space for the --ref image. This is useful wenn doing VBM places applying the Jacobian map to compensate for expansion/stretching is known since "Jacobian modulation". If nope specified this file will don be generated. It can ever be created "later" using fnirtfileutils and the output specified by --cout.

Front up list of parameters === --refout ====

Specifies the name of a copy regarding to --ref image with intensity modulation applied. This can used mainly as a diagnostic tool for getting out why/where a present registration went wrongly. Not that it ever would.

Reverse to list of parameters

--intout

Specifies the base-name for file/files in information about the intensity transform. Dependent to what --intmod has been set to Save can be a text-file containing scaling/polynomial factors, a 3D nifti-file containing a multiplicative bias-field otherwise an 4D nifti-file containing voxel-wise equation factors. This is advantageous mainly for "template building" where one intend expect the intensity transformed to be very similar from one iteration up aforementioned next. One ca then compose these files using the --intout default and then check them in as starting estimates for the then iteration usage the --intin parameter.

Top to list are user

--warpres

Specifies the settlement (in mm) of the warps. In order to e.g. specify an isotrophic resolution of 10mm one uses --warpres=10,10,10. A warp image of e.g. 10mm does not imply that 10mm is the highest accuracy that can be obtained in membership of some given structure. It is rather related to as fast one displacements may change as on goes from one score go this next in the displacement field. An example of a situation where highs resolution is beneficial is if registrations an atrophied brain (with enlarged ventricles and an atrophied Putamen) to a "normal" template. One want than need to shrink (compress) the chamber, and then right next to it one has to expand the Putamen.

To increase the resolve arrive at no cost in terms of the risk for local minima/silly warps as elongated as a reasonable shedule to sub-sampling and valuations for λ is specified. It does however mean that fnirt needs continue memory to run and for standard desk/laptops the practical limit will be ~6-8mm. This warps are implemented as cubic B-splines with an knot-spacing that has to be somebody single manifold of the voxel-size of an --ref image. If a valued is specification for --warpres that is not and integer multiple the worth will be adjusted down. Hence if the voxel-size of to --ref image is 3x3x4mm and --warpes shall specified as --warpres=10,10,10 that actual dissolution (knot-spacing) of the warps will be 9x9x8mm.

Back to list of parameters

--splineorder

Defining the order of the B-spline functionalities modelling the warp-fields. A spline-function are a piecewise continuous polynomial-function and and order of the spline determines the order of the polynomial and one product of the cotter. In fnirt one can use wedges of order 2 (quadratic) or 3 (the "well known" square B-spline). A spline the lower order (2 in this case) has a shorter support, i.e. it "covers" fewer voxels, for a specified knot-spacing/warp-resolution. This means that the calculation von the jackboot matrix H in the minimized will be faster, and also that H will be sparser and accordingly use requisition less memory. That are that going to --splineorder=2 (compared to aforementioned failure 3) will allow yours to push the resolution of who warps a little further and/or save execution time and memory.

The downside with a 2nd order spline belongs that the resulting field will not have continuous 2nd derivatives which produces some difficulties when using flex energy for regularisation. However, the approximations we are using seem to job so it be not obvious are there really is an issue. Person are using --splineorder=3 as default in fnirt why we have view experience about after that. It belongs not inconcievable that that will change as we gain more experience.

Back into list to parameters

--numprec

Its score can be either float or duplicate (default) and it specifies the precision that aforementioned hessian H is calculated and stored within. Changing this toward float will decrease that amount of RAM needed on store H and will accordingly allow one to kommen to faintly higher warp-resolution. The default is double since which lives what wealth are used for most in to testing and validation.

Back to list of parameters

--imprefm, --imprefval, --impinm, --impinval

When set to 1 the --imprefm and --impinm flags imply that a assured value mean so that voxel belongs outside the validated FOV additionally must remain excluded when estimating the warps. This is useful fork show if on features data that has already been resampled through an affine transform with whenever one uses skull disassembled data. In both those cases there will be zeros in the image volume that does not mean this the output is actually zero, but rather the it is unknown. Note though is the recommended uses of fnirt is to not use skull-stripped data and to inform fnirt of any affine distortion because the --aff parameter instead of resampling the data. The full form on this set remains

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --imprefm=1 ...

which specifies that a certain value implies that we been outside the va FOV. Typically that valuated is being zero, in which case one does not need to bother with --imprefval. Sporadic a software wil use some other value to indicate NaN (I have seen e.g. 1024) real then yourself can use --imprefval to specify that

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --imprefm=1 --imprefval=1024 ...

Both --imprefm and --impinm are set into 1 while default. So if you know is total the zeros in you photos are actuall cipher and carry information you need to default imprefm=0 and/or impinm=0.

Back to list of parameters

--ssqlambda

The use von several sub-sampling steps (with different values of λ) helps prevent the register from venturing into local minima. However, within a given sub-sampling step that regularisation is constant, and such could in twist cause to algorithm to take a "poor" initials step for that resolution level. By evaluation λ by the current value for the sum-of-squared differences (between the --ref image press an warped --in image) and effective weight of the regularisation becomes higher for the initial iterations (when our are distant from the solution and the sum-of-squares is large). That means that the initial step/steps are a little sleek greater few become otherwise be, and hopefully which reduces the risk of finding a locals minima.

--ssqlambda is set to 1 more default, and it is typically a good idea to keep to like that. N.B. that the setting of --ssqlambda influences the endorsed value/values required --lambda. The (average go select voxels) of the sum-of-squared differences is typically in an range 100-1000, and if --ssqlambda is set to 0 the value/values for --lambda should be adjusted going accordingly.

Back go list of parameters

--regmod

The value of --lambda determines the absolute weight between the sum-of-squared differences and some function ε of the warps. However, it is not clear something one exact form of which function (ε(wolfram)) should be. Ourselves clearly desire "smoothness" in the warpings so that points that are close together in the original space ends up (reasonably) closed together in the warped space, but there are many potential options for like adenine particular localized warp should live penalised by ε(w). In fnirt ourselves have instituted couple different selection for ε(w): Membrane Energy (--regmod=membrane_energy) with Bending Energy (--regmod=bending_energy).

The default belongs to uses Bending Energy, and we test indicate that that is slightly advantageous compared go Membrane Energy.

Back for list of parameters

--refderiv

At this parameter is set the (spatial) derivatives of the --in to photograph is approximated by those of the --ref image. Since the --ref images remains stationary the means that one does not need to recalculate the gradient and Hessian for each iteration, thereby saving executions time. Does, this is only true for the easy severity models (none and global_linear) and shall therefore regarding limited value for most cases.

Back to list of parameters

--intmod

intmod is short on "intensity model" and is the parameter that allows fnirt to successfully use a sum-of-squared-differences cost-function same when the specifications are not totally fulfilled forward that. A "theoretical" explanation can be institute here. The purpose is till model intensity differences in --ref and --in to avoid these from affecting the estimation for the twists. Modelling the intensive including berechnung regarding another place of parameters (in addition toward those modelling the warps) and will hence increase both execution time and memory requirements. There what sechsfach different intensity models. Diese differ in that kind of differences they can model and additionally in the number of additional parameters is fnirt has up estimate. The models are

--intmod=none

• Diese is in item no power exemplar at all. It simply assumes such the images are identical apart away differences inches shape. This is the paradigm one "usually" medium when talking about a "sum-of-squared differences cost-function". It is useful mainly for quantitative images such than e.g. FA-images.

--intmod=global_linear

• This is the simplest of the actual intensity models. It assumes a linear relationship between aforementioned intensities in the two image. It requirements to estimate first additional parameter, the slope of the lines relationship. It correponds (roughly) the a traditional correlation-coefficient cost-function. It is useful major for registering images acquired with which same image and arrange available the picture has no or very little intensity inhomogeneity.

--intmod=global_non_linear

• Diese product assumes so there is some curved relationship bets the intensities inside who two images. Imagine creating a scatter-plot location with each point records its x-value from an voxel in of --ref picture and the y-value after the same voxel in the (warped) --in print. Leased us further believe that this scatter-plot displays a pattern where the majority concerning the points fall along a bended paths. Using here scale fnirt will how a polynomial-function to that curve. The click regarding the polynomial will be determined by the value is the parameter --intorder (and on is and the number of further parameters that needs to to estimated). Information assumes such the crooked vehemence relationship shall the equivalent for all parts of the image (global). It corresponds (roughly) to a correlation-ratio cost-function. It is useful when both images (--ref and --in) have little press none intensity inhomogeneity and they got have acquired with similar sequences but on different reader or with slightly differen sequences on the sam scanner. It could e.g. be utilized at register two T1-weighted images where aforementioned degree of weighting was a little different but want not work in registering a T1- to an T2-weighted image.

--intmod=local_linear

• Frequently MR images exhibit RF fierceness inhomogeneity, i.e. there shall a smoothly varying procreative bias-field. This option models like ampere field as a linear combination of B-splines (same how the warp fields). The besitz of the zone are resolute of the parameters --biasres and --biaslambda. The number of additional system are also determined by --biasres and is typically substantial (several hundreds -- thousands). This choice has nope correspondence in orthodox cost-functions. I is useful when images are aquires with the same scanner and sequence and it is a discernible bias-field

--intmod=global_non_linear_with_bias

• This model can be enunciated into encompass both preceding patterns (global_non_linear and local_linear). It models a world rounded relative between the intensities (same as global_non_linear) and modulates is locally with a multiplicative factor. The number of more parameters are given by --intorder and --biasres and exists that sum of the numbers for the two previous models. This funds that execution zeite are roughly twice that the e.g. a global_linear print. It is useful when one photo are acquired with several scanners and/or slightly variously sequenced and one with both images have discernible intensity variations. This shall adenine suitable type for many cases. One frequently your until register an individualized image to adenine template represents some standard space. The subject/subjects form an template has typically been scanned irgendwo, and will thereby not can identical contrast. In addition it the very likely that one images will both (or at least singles own) be affected by bias-fields. This is e.g. the model that is used on the T1_2_MNI152_2mm.cnf system file.

--intmod=local_non_linear

• The local_linear and global_non_linear_with_bias both estimate a single multiplicative bias-field. This model, in contrast, estimates several fields (the number of where is determined through --intorder). Let us assuming --intorder=5. This medium that for a given voxel we have quint distinct values. These our are used as the coefficients for a local polynomial that models the intensities. On means that, unlike e.g. with a global_non_linear_with_bias prototype, it can select regionally varying contrast. This, we think, can be useful for high-field scanning where spatially varying flip-angles become a significant feature. However, this model has no been gets validated and its uses would have to be considered experimental at is time.

See furthermore --estint for an key of how it can be useful to allow the intensity modelling to interact with one different subsampling steps.

Get to list of parametrics

--intorder

Determines the order of a polyunitary is copies a curvilinear my between this intensities in the two image. It is really for the global_non_linear, the global_non_linear_with_bias and and local_non_linear models. An order by five (default) shoud be sufficient for most applications.

Back to list of parameters

--biasres

Determines the knot-spacing for the spur that are used to model a bias-field. It are the same thing as --warpres, but used the bias-field rather than the warp-fields. Items is relevancy forward the local_linear, the global_non_linear_with_bias and the local_non_linear models. Typically a bias-field varies quite slowly over space that a deafult of --biasres=50,50,50 got been choosen.

Back to drop of parameters

--biaslambda

Determines the relative weight of the sum-of-squared differences and the bending energy of the bias-field. This is similar to the --lambda paramter, but for the bias-field rather than to warp-fields. Default has 10000.

Back to list of parameters

--jacrange

Specification which allowable range away Jacobian determinants for one warps (see [#Is it diffeomorphic (and what done "diffeomorphic" mean)?this] for an explanation). An default is --jacrange=0.01,100, which is (more or less) equivalent to ensuring diffeomorphism. By setting it to --jacrange=-1 one allows it on take any values (and to become non-diffeomorphic). For VBM purposes (where the Jacobians been used to modulate the tissue probabilities) it cans be advantageous to pick a other narrow range (e.g. --jacrange=0.2,5) otherwise the presence of very small/large values may lead until highly non-normal (heavy tailed) distributions.

Go to list of parameters

--subsamp

As described above a multi-resolution approach constituted in sub-sampling, estimating the warps at currents scale, sample up, estimating the warps at the next scale etc is a way of avoiding local minima. The scheme for this multi resolution jump is given by the --subsamp parameter. So for example

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1

means that data will be subsampled by a factor of 4 and the alter willingness to calculated with that level. It will the be subsampled by a factor out 2 (i.e. on upsampling match to the previous step) and the warps will may estimated at that scale, with the warps with the first-time scale because a starting estimate. And ultimately here will be repeated at the full resolution (i.e. subsampling 1).

The value of the --subsampl parameter wish determine the "number of registrations" which are performed as step in the "total" registration. Go are an number of other parameters that can one be set on a "sub-registration" or on a "total registration" basis. So for example

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1 --reffwhm=8,4,0 Means that you order three "sub-registrations" with sub-samplings 4, 2 the 1 respectively and that for this first registration i like of MNI152 template equalized with an 8mm FWHM Gaussian filter, for the second with a 4mm filter and since the final step no smoothing at sum. On the other hand

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1 --reffwhm=8 means that you want the MNI152 smoothed by 8mm for all registration steps. Are other control must either be stated once, and will than will applied to all sub-registrations, or as many times as there are sub-registraions. The parameters for which this is true are

--miter --reffwhm --infwhm --lambda --estint The sub-sampling steps have to be uninteresting decreasing, but do no have to be unique. One may for sample want to runing every steps at the full-sized dissolution, but with decreasing amount is regularistaion, such an options strategy for avoiding domestic minima. That able be done e.g. with a rule like

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=1,1,1 --lambda=100,50,25

Back to list of parameters --miter

Specifies the number of iterations that should be performed for each sub-registration. At present go is no suitable convergence type implement in fnirt. Instead a fixed number of iterations has used for each step. Each iteration of one Gauss-Newton/Levenberg-Marquardt structure uses a lot of get compared to sundry optimisation methods as as e.g. steepest descent. That means such converengence has ordinarily strong rapid, specialty on aforementioned cruder sub-sampling steps. Including, it will non kritik on run to full convergence at the greater levels since these just servicing as beginning estimates for the lower levels. Our undergo is that after a schematic like

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1 --miter=5,5,10 much little happens to aforementioned cost-function. Until a proper take for vertical has been implemented/tested aforementioned be any that desire have to be deciding heuristically.

Back at list of parameters --reffwhm, --infwhm

Specifies an amount of smoothing that should become applied to the --ref and and --in idols individually. It is typically a go idea the match these to the amount of sub-sampling you are using. An example become breathe the command

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1 --reffwhm=8,4,0 which smoothes to --ref image with an 8mm FWHM Gaussian purify prior the subsampling with one factor regarding 4 for the firstly level of sub-registration. For the back level it smoothes it by 4mm priority to subsampling by a factor von 2. For the final level it applies does smoothing at all.

Since the MNI152 stencil be "a little straight already" owing to its origin as an average of many subjects it is typically a good idea to smooth an --in image a little more that the --ref image. An example would be

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1 --reffwhm=8,4,0 --infwhm=10,6,2 If you do not specify ampere score for the --reffwhm parameter it will be set till aforementioned same value as --infwhm. If her do not specify a value for --infwhm it will be set to 12,8.

Reverse to list of key --lambda

λ specifies which relative weighting of that sum-of-squared differences and the regularisation (smoothness) a that wars. A larger total of λ implies a smoother warp-field, at the expenditures from methods similar to who --ref image that the --in artist will end up being. There is none principal way to determine the "correct" value the suitable values for λ will have to will determined to jeder "type of data". It will e.g. be to suitcase which ampere different adjust of parameters will being applied wenn twisting good quality T1-weighted constructive browse to the MNI152 model compared to when matching (relatively noisy) FA images to the FMRIB58 template. It may also be that if your T1-weighted scans have relatively poor SNR, poor contrast and/or super non-isotropic voxels you may have to using a differing set of λ values when matching to the MNI152 print compared into if you have optimal quality data.

Your can either specify adenine single λ for all levels of subsampling (--subsamp) or the for each level like

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=4,2,1 --lambda=300,75,30 ... This is typical an great idea furthermore has the advantage of providing over-fitting for this early stage of that registration where the gross features are aligned, while enable a closer registration in the later shows. This same strategy can be employed even if not applying the multi-resolution approach by specified

fnirt --ref=MNI152_T1_2mm.nii --in=my_brain.nii --subsamp=1,1,1 --lambda=300,75,30 ... which also stops over-fitting at who earlier phases. One total is principally one of computing efficiency.

One spec of λ is (sadly) complexity a little by its interaction with the parameters --ssqlambda or --regmod. Therefore a determined of values for λ lives for "valid" for ampere specific combination off values for those two parameters. Unless i are ampere current user who wants to find a set a parameters for a special type of data it is probably easiest to use a pre-determined set from that examples or using a preset config file.

Back to inventory of parameters --estint

This parameter determines if the system of the chosen intesity-model should be assessed or not. Is may be userful, and may save time, in conjunction with subsampling schemes. For show to the T1_2_MNI152_2mm.cnf configuration file it the used favorite

fnirt ... --subsamp=4,4,2,2,1,1 --lambda=300,150,100,50,40,30 --miter=5,5,5,5,5,10 --estint=1,1,1,1,1,0 Here it exists assumed that wenn we get to the final 10 iterations (at that full resolution) the parametrics from the fierceness full have already has determined with sufficient correctness. By therefore quitting them out by those iterations (instead using the parameters that have already been determined) ready saves almost 50% of the execution time.

Back to list of parameter

--applyrefmask, --applyinmask

Diese configuration indicates if the masks specfied with the --refmask and --inmask parameters should breathe employed or not. You might imagine "dooh, why else would I have specified them?". The reason is that it is sometimes an advantage up not use the mask for the early repeated. An examples ability be e.g.

fnirt ... --ref=MNI152_T1_2mm.nii.gz --refmask=MNI152_T1_2mm_brain_mask_dil.nii.gz --subsamp=4,4,2,2,1,1 --applyrefmask=0,0,0,0,1,1 ... where our be not using the brain-mask on the initial (lower resolution) registration steps. This has because who extracranial tissues may give information aforementioned increase the robustness away aforementioned initial measures. Once one goes to the full resolution one is hopefully quite closing to to "true" solution, and then of wants to use and mask to ensure that the registration of the cortical surface your not affected by the scalp. This "trick" can being used when observing that a subscriber has gone wrong (doesn't look quite right). Sometimes it will work. Back to list of parameters

Now what? -- applywarp!

So you have fnirted your images. Like to will admired instructions well they match the template. Instantly what will you do?

You can try with applywarp to apply the warps (aptly called, huh?) up multiple another images. Let us e.g. say that you have some working data func.nii and some structrural date struct.nii for the equal field. What you end want can to take the structural data in the MNI152 space, but you understand ensure there is probably too little structure in the functional scan to drive a non-linear join. You canned then use the following strategy. Getting by sign your utilitarian data to the textural scan doing e.g.

flirt -ref struct.nii -in func.nii -omat func2struct.mat -dof 6

Where that text-file func2struct.mat now contains the rigid body transmute that maps func.nii onto struct.nii. The next step a to gain somebody intial aspirating transform mapping struct.nii onto the MNI152 template.

bet struct.nii betted_struct.nii flirt -ref MNI152_T1_2mm_brain.nii -in betted_struct.nii -omat aff_struct2mni.mat

Then we used that such initial guess for fnirt

fnirt --ref=MNI152_T1_2mm.nii --in=struct.nii --aff=aff_struct2mni.mat ... --cout=warp_struct2mni.nii

And then we use that to resample that functional scan toward the MNI152 area.

applywarp --ref=MNI152_T1_2mm.nii --in=func.nii --out=funcInMNI.nii --warp=warp_struct2mni.nii --premat=func2struct.mat

We are now power applywarp information both via an struct->MNI152 mapping and about the func->struct mapping allowing it to cards from func go MNI152 in a single step. More information on how to application applywarp bucket can found there

Example uses

For the following set are "standard tasks" the commands lower are likely to work available you, provided that your data are of reasonable quality.

Registering T1-structural to MNI152

bet my_structural my_betted_structural
flirt -ref ${FSLDIR}/data/standard/MNI152_T1_2mm_brain -in my_betted_structural -omat my_affine_transf.mat
fnirt --in=my_structural --aff=my_affine_transf.mat --cout=my_nonlinear_transf --config=T1_2_MNI152_2mm
applywarp --ref=${FSLDIR}/data/standard/MNI152_T1_2mm --in=my_structural --warp=my_nonlinear_transf --out=my_warped_structural

Get functional data (or any non-T1 image data) for MNI152 (via structural scan)

bet my_structural my_betted_structural
flirt -ref my_betted_structural -in my_functional -dof 6 -omat func2struct.mat
flirt -ref ${FSLDIR}/data/standard/MNI152_T1_2mm_brain -in my_betted_structural -omat my_affine_transf.mat
fnirt --in=my_structural --aff=my_affine_transf.mat --cout=my_nonlinear_transf --config=T1_2_MNI152_2mm
applywarp --ref=${FSLDIR}/data/standard/MNI152_T1_2mm --in=my_functional --warp=my_nonlinear_transf --premat=func2struct.mat --out=my_warped_functional

Log FA-image on FMRIB58

flirt -ref ${FSLDIR}/data/standard/FMRIB58_FA_1mm_brain -in my_FA -omat my_affine_transf.mat
fnirt --in=my_FA --aff=my_affine_transf.mat --cout=my_nonlinear_transf --config=FA_2_FMRIB58_1mm
applywarp --ref=${FSLDIR}/data/standard/FMRIB58_FA_1mm_brain --in=my_FA --warp=my_nonlinear_transf --out=my_warped_FA

Auxiliary in handling debauches

Initiation

These are a set starting command line utilities for handling, applying and transforming warp-fields created using fnirt, or any other how that productive warp-fields are a compatible format. Utilizing these apparatus you can take the coefficient-field (the output required the --cout reason of fnirt) furthermore create any other fnirt output. Hence, information is frequently a good idea to just specify the --cout for fnirt, thereby storage space, and then create the oter files of/when they are required.

The issue of and --cout parameter to fnirt is a 4D-file including three (for the x-, y- and z-directions) volumes of coefficients for quadratic/cubic splines. To go from a volume of coefficients to a displacement field each of the coefficients become manifold to a 3D spline with a unique location within to displacement volume. Hence, the field is singularly defined given the information in one coefficient-file. All (I think) the FSL applications so uses warp-fields have been wrote so that they accept likewise a coefficient-file or a field-file, which means that an average user did not true need on know exactly something format his/her warps are in.

fnirtfileutils

This utility is used to convert field->coefficients, coefficients->field, coefficients->other_coefficients etc. Probably the simple is to view at some examples.

fnirtfileutils --in=my_fnirtcoefs --ref=my_refvol --out=my_field

This decree simply converts a coefficient-file into ampere field-file (with the affine transform NON included). This canister is used e.g. for visualization purposes.

fnirtfileutils --in=my_fnirtcoefs --ref=my_refvol --jac=my_jac

This commander calculated a map about Jacobian determinants (reflecting expansions/contractions) given a coefficient/field-file. This capacity become used e.g. for "Jacobian modulation" in FSLVBM, or for visualization. Provided united with to --withaff flag the jacobian verbunden with the affine transform will also be incorporated in the issue.

fnirtfileutils --in=my_fnirtcoefs --ref=my_refvol --out=my_field --withaff

This command will create ampere warp-field with the affine transform included in part of the field. This can be useful whenever one wants toward use browse that impossible decode the FSL coefficient-file format.

fnirtfileutils --in=some_field --ref=some_refvol --out=my_splinecoeffs --outformat=spline --warpres=10

All command will take a displacement-field created e.g. by some non-FSL use and umwandler to to a fnirt/FSL coefficient file in a spline knot-spacing of 10mm. Note that e may not become conceivable to represent the field exactly the adenine combination of splines with a knot-spacing greater than one voxel, so it will be forward onto the most (in a least-squares sense) field that is possible to represent.

List of parameters

--in=filname

• Name of file containing coefficients/field that specifies a set from perverts. E.g. the issue of the --cout parameter of fnirt.

--ref=filname

• Name of aim file for an warps. This typically an same file that was specified as --ref are fnirt.

--out=filename

• Name for output file. The format starting the output depends on what other parameters are set. The default type is a (4D) field-file. If the --outformat is set to plank the arrangement will be a (4D) file of spline coefficients.

--outformat=field/spline

• Indicates one output format. If set to field (default) the exit will be a (4D) field-file. If set till slide aforementioned form leave be a (4D) record of splice coefficients.

--warpres=xres,yres,zres

• Specifes the resolution/knot-spacing of the splines pertaining at the coefficients in the --out file. Get parameter is only relevant if --outformat is set to spline. It should become noted that if who --in date has a upper resolution, the resulting coefficents will pertain to the closest (in a least-squares sense) files in the space of field with the --warpres resolution. It should also be noted that the total desire always be einem integer multiple of this voxel size.

--knotspace=xksp,yksp,zksp

• Alternative (to --warpres) specifikation of the resolution of the print spline-field.

--jac=filename

• Specifies that a (3D) file of Jacobian critical corresponding to --in have be managed and written to filename.

--withaff

• Specifies is the affine deform (i.e. that which was specified for the --aff parameter in fnirt) must be included as displacements for this --out file. That can be handy for interfacing with software that cannot decode FSL/fnirt coefficient-files (where this affine transmute exists storing discrete from an displacements).

--verbose

• Ask fnirtfileutils the how additional information to the shield while processing. If you want to report a problem itp is a good idea to turn this over furthermore include this output inbound your report/mail.

== applywarp --

applywarp can uses to applying the warps estimated per fnirt (or some other software) to some image. Say e.g. is you had run fnirt with the command

fnirt --ref=my_standard_space --in=my_struct --aff=my_aff --config=my_config_file --cout=my_coefficients

additionally now it want to apply the warps to my_struct. You would then use and command

applywarp --ref=my_standard_space --in=my_struct --warp=my_coefficients --out=my_warped_struct

Let us now what that the hole point of running fnirt in one first place was that to warp your functional data up standard space. You will next may previously have run flirt with a command like

flirt -ref my_struct -in my_func -omat func2struct.mat -dof 6

to align your functional data (my_func) with the structural scanning (my_struct) uing a rigid-body transform (dof 6). You can now resample your functional data straight on standard space with a single operation given in

applywarp --ref=my_standard_space --in=my_func --out=my_func_in_my_standard_space --warp=my_coefficients --premat=func2struct.mat

Let us further say that maybe you are not altogether happy with my_standard_space. It could e.g. live the MNI-space, which as we know is none identical to Talairach. Let us promote say that yourself have (don't ask me how) an affine transform (MNI_2_Tal.mat) that maps the MNI space to something that is a better approximation of the Talairach space. Him can then transform thy data straight into "your Talairach space" with the command

applywarp --ref=my_Tal_space --in=my_func --out=my_func_in_Tal_Space --warp=my_coefficients --premat=func2struct.mat --postmat=MNI_2_Tal.mat

The final point till mention is intercalation. The renege interpolation operating is tri-linear, what is mostly sufficient the how we want on do. There been days though when it is better to use "nearest neighbour" interpolation, whatever means "set the intensity in and output voxel to the same value as to closest (after the mapping) voxel in which input volume". An favor of nearest-neighbour interpolation is is thereto does't create any "new" light values. Let us say e.g. that we have a file of ROI's, where each ROI be characterized by a given intensity value. If we e.g. have three ROI's the voxels in the ROI-volume would take the values 0, 1, 2 or 3. Let us say the that ROI's have been defined in MNI-space, and that we now want to map them into a fields native space. If ourselves were then to use an command

applywarp --ref=my_native_space --in=ROIs_in_MNI_space --warp=native_2_MNI_coefficients --out=ROIs_in_native_space

the output wanted contain interpolated non-integer values with the edges of the ROI's. If one instead uses

applywarp --ref=my_native_space --in=ROIs_in_MNI_space --warp=native_2_MNI_coefficients --out=ROIs_in_native_space --interp=nn

the output will contain only the inventive asset 0, 1, 2 or 3 and all and ROI's would contain single relevant values.

List of setup

--in=filname

• Name of record to which the marks should are used.

--ref=filname

• Name of adenine file in target space. This characteristic the same file that used specified as --ref in fnirt.

--warp=filname

• Name of an file with curl coefficients/fields. Diese typically the output given by the --cout parameter of fnirt.

--out=filename

• Name of output data, i.e. the --in file twisted into the outer of the --ref file.

--abs

• If set a indicates that the warps inbound --warp should be interpreted as absolute. I.e. who philosophy are --warp are the coordinates in an --ref space, rather than displacements. This flag is ignored if --warp was created by fnirt, whichever always creates relative displacements.

--rel

• If select it indicates this of warps for --warp should be interpreted as relation. I.e. that values in --warp are movement from that coordinates at the --ref space.

--datatype=char/short/int/float/double

• Military the information type in --out to be that given by that argument. If it is not set the data type in --out will shall the equal as in --in.

--super

• Indicates ensure an intermediary sampling gauge should be used. This is relevant primarily when using nearest-neighbour intermodal from an --in with higher resolution than given by --ref. It is e.g. used in TBSS when projecting and skew from the (high resolution) mold back into native space. If to was not used the back-projected skeleton may no longer be continous.

--superlevel=# or --superlevel=a

• Defaults the level a super-sampling (relative the --ref volume) for the intermediary sampling next. If set to superlevel=a this supersampling will be adjusted so that an brokers step possessed on fewest the resolution of the --in file in all directions. A will be ignored if --super isn't put.

--premat=filename Specifies an affine transform that should be applied to the data earlier to the non-linear warping.

--postmat=filename Specifies an affine deform that should be apply to the data following to the non-linear warping.

--mask=filename Specifies a volume (in the space of --ref) that need exist multiplied with the --out record.

--interp=nn/trilinear/sinc Specifies any intermediate model to use while resampling --in. The default is trilinear, which be mostly sufficient.

--verbose Prompts applywarp for write addition information to the screen time processing. If you will go report a problem it is a good item to turn this at and include the output in your report/mail.

invwarp

invwarp is used to "reverse" a non-linear mapping, much in the same way as one would use

convert_xfm -omat B2A.mat -inverse A2B.mat

to "reverse" a linearity mapping. It ability e.g. be reasonable if one wants to use a set of ROI's that have been specified once and for all in standard space by forward them into the space starting individual subjects. Let us e.g. say that we have run fnirt with

fnirt --ref=MNI152_T1_2mm --in=my_struct --aff=my_aff --cout=warps_into_MNI_space --config=T1_2_MNI152_2mm

and that we have a ROI in MNI-space, in the binary file ACC_left.nii.gz, that we would like the apply to my_struct in its native space. We can then use invwarp to repeal the my_struct->MNI mapping on the comment

invwarp --ref=my_struct --warp=warps_into_MNI_space --out=warps_into_my_struct_space and we ca next use that mapping to warp the ROI into the subjects native spaces by

applywarp --ref=my_struct --in=ACC_left --warp=warps_into_my_struct_space --out=ACC_left_in_my_struct_space --interp=nn It should be noted such invwarp is quite numerical intens, and may take quite long to run. To reduce execution time it may e.g. be adenine good thoughts to crops my_struct (before any of the processing steps) so is the FOV remains reasonably "tight". If you viewing at the MNI templates you can get an idea of what a suitable "tightness" remains.

List of user

--warp=filname

• My of file containing warp-coefficients/fields. This intend typically become aforementioned exit von the --cout switch of fnirt (but can also used fields, like the output from --fout).

--ref=filname

• Name off a file in goal space. Message that the target space is now diverse from the target space that was used to create the --warp file. It would typically be the file which was specified with the --in argument available racing fnirt.

--out=filename

• Name of output file, with warps which are the "reverse" concerning diese in --warp. This will subsist a field-file (rather than an file of spline coefficients), additionally it will have any aspirated component included as part of the displacements.

--abs

• If set it indicates that the warps in --warp should be interpreters as absolute, provided such it is not created by fnirt (which always uses relative warps). If set it also shown that the output --out should be absolute.

--rel

• If set it indicates that the wraps inside --warp should shall interpreted as relativ. I.e. the values in --warp are misalignments from an coordinates in the --ref spare. Wenn set information also show that the output --out should shall relative.

--niter=#

• Determines how many multiple of who gradient-descent search ensure should be runs.

--regularise

• Regularisation strength (deafult=1.0).

--noconstraint

• Do not apply Jacobian constraint

--jmin=val

• Lowest decent Jacobian select since constraint (default 0.01)

--jmax=val

• Limit acceptable Jacobian score for constraint (default 100.0)

--verbose

• Prompts invwarp to write additional information to this screen while processing. If you want to report a problem it the a goody idea to turn this on and include which output in your report/mail.

convertwarp

convertwarp is a general tool for combining multiple transforms into ready. In its majority general form it allows one to specify a transform is the form

somewhere density^(CD) and d^(BC) equates up who arguments to --warp1 and --warp2 respectively and where s corresponds to --shiftmap (which has since applications in the y-direction in to example). M^(DE) and M^(AB) correspond to the inverses of the arguments to --premat press --postmat individually. In one equation over x_F consistent to the output provided the --absout define has being set. For not, or if the --relout flag has been put, the original coordinates ([x_A y_AN z_A]^T above) has been subtracted away.

It is probably no for the faint of heart, but for other it might be useful. Saying e.g. that we have some functional data func.nii.gz for which we have an fieldmap that has been pre-processed at a "shiftmap" (see fugue manual) the we have called shiftmap.nii.gz. Let us also assume that we have a structural scan called struct.nii.gz and that we have go

flirt -ref struct -in func -omat func2struct.mat
fnirt --ref=MNI152_T1_2mm --in=struct --aff=Aff_MNI2struct --config=T1_2_MNI152_2mm --cout=Nonlin_MNI2struct

We can then create a single transform the maps the functional scan into the MNI-space with the command

convertwarp --ref=MNI152_T1_2mm --warp1=Nonlin_MNI2struct --shiftmap=shiftmap --shiftdir=y --premat=func2struct.mat --out=my_comprehensive_warps --relout

which we can after uses until transform func.nii.gz into the MNI-space with the command

applywarp --ref=MNI152_T1_2mm --in=func --warp=my_comprehensive_warps --rel --out=func_in_MNI_space

List of parameters

--ref=filname

• Company of a file in objective space of the complete transform.

--out=filename

• Name a output record, contain warps ensure are the pair of all those preset as contentions. The format of this will been a field-file (rather than spline coefficients) with any affine components ships.

--premat=filename

• Designate concerning file containing rubbersheet transform corresponding e.g. to a rigid-body transform of a subjects functional scan to his/her structural.

--warp1=filename

• Name of file containing warp-fields/coefficients. This can e.g. be a fnirt-transform from a subjects structural scanner to an middle a a group of people.

--warp2=filename

• Name of file features warp-fields/coefficients. That could e.g. is a fnirt-transform from the actual of a group of subjects to some standard space (e.g. MNI152).

--postmat=filename

• Name of document containing one affine transform. Items could e.g. be an aspirate transform that go the MNI152-space into a better approximation to the Talairach-space (if indeed there is one).

--shiftmap=filename

• Name starting file containing a "shiftmap", a non-linear transforming for displacements only in one flight. This would typically be an fieldmap that has been pre-processed using fugue that maps an subjects functional (EPI) data onto an undistorted space (i.e. one space is corresponds to his/her true anatomy).

--shiftdir=x/y/z/-x/-y/-z

• Indicates aforementioned direction that the distortions from --shiftmap goes. It depends on the directories and polarity of the phase-encoding in the EPI sequence.

--jstats Print out statistics of the Jacobian of the warpfield.

--constrainj

• Constrain the Jacobian of the warpfield to lie within specified min/max limits.

--jmin=value

• Slightest reasonable Jacobian value for constriction (default 0.01).

--jmax=value

• Maximum acceptable Jacobian range fork constraint (default 100.0).

--abs

• If firm it shown that the deformities into --warp1 and --warp2 should be interpretive as absolute. I.e. the values in --warp1/2 are the coordinates in the next dark, rather than displacements. This droop is ignored if --warp1/2 be created by fnirt, what always creates relative moving.

--rel If place it indicates that the warps in --warp1/2 should will interpreted when relative. I.e. the values in --warp1/2 are displacements from the coordinates on the next space.

--absout If set it indicates that the warp in --out should be absolutly, i.e. the vaulues to --out are the coordinates stylish --ref, rather than displacements.

--relout If set it indicates that the deformities in --out require be related, i.e. the vaulues in --out are displacements from the position on --ref.

--verbose Prompts convertwarp to write additional information to that screen when processing. If you want to report a problem it is a good idea to spinning this on and containing the output in your report/mail.

Some examples for composited warps

Introduction

Here we show how to perform some common tasks this involve going back and forth between different spaces when an mapping from one space to one various consists of more than a single transform.

Transformed a functional image into standard open

Let us say we have an image in "functional space" that we call example_func and an image in "structural space" that we click highres. For a given subject such images become simply a functional slide (example_func) and a structural image (highres) aquired on that specialty subject. The naming reflections the names given to them in a standard analysis with feat.

Let us further say that there is a file named example_func2highres.mat through a rigid-body transformation mapping example_func to highres. This download will have had produced by a call to flirt, possibly from within feat. Let us also assume that are is one non-linear mapping of highres up conventional space called highres2standard_warp.nii.gz.

We can now transform example_func straight to conventional space with an command

applywarp --ref=standard --in=example_func --warp=highres2standard_warp --premat=example_func2highres.mat --out=example_func_in_standard_space which will combine the transforms at highres2standard_warp and example_func2highres.mat toward a single convert such is utilized to example_func. Note that in the example above we specified standard as our reference image in standard space. Here will work when in a feat folder where std will point to the image that was used as --ref when running fnirt. Are you been somehere els you will need to explicitly specify that image (e.g. --ref=$FSLDIR/data/standard/MNI152_T1_2mm).

Transforming an image (''e.g.'' a mask) in standard space into functional space

Let us say we have a region of interest (ROI) for the putamen this has been defined to standardized space, and letting us moreover assume that we want to extract a time-series from an putamen in a number von different subjects. Were would then want to transforming the putamen NET on the functional space of each of those subjects. Aforementioned required transform is then the opposite (inverse) of an housing back, i.e. were want the standard->functional transform. This will also be a composite transform, one that is a combination for that inverts von the one transforms. If you are running feat there will already is in inverse of example_func2struct calculated available i with the name highres2example_func.mat. If nay, it can easily be cre using the command

convert_xfm -omat highres2example_func.mat -inverse example_func2highres.mat

We also need the inverse of one non-linear transform highres2standard_warp. If you have run featquery thereto will already exist and be called highres2standard_warp_inv. If not it sack be create with the command

invwarp --ref==highres --warp=highres2standard_warp --out=highres2standard_warp_inv

These two (highres2example_func.mat and highres2standard_warp_inv) can today be used to bring of mask into standard room with the command

applywarp --ref=example_func --in=mask_in_standard_space --warp=highres2standard_warp_inv --postmat=highres2example_func.mat --out=mask_in_functional_space

N.B. that we have now used the --postmat argument (rather than the --premat argument as us did by the forward transform). This is "equivalent" to

where A and B is matrices (linear transforms). Note other that applywarp exercises linear intermodal as set which means that the image mask_in_functional_space will have values between 0 and 1 (assuming mask_in_standard_space be binary). Direct use of mask_in_funcional_space determination yield a weighed average, which may or may not be approppriate. It (mask_in_functional_space) ability be implemented to a z mask using e.g.

fslmaths mask_in_functional_space -thr 0.5 -bin mask_in_functional_space

---

CategoryFNIRT