Home · Quickstart · User Guide and Examples · Interfaces Index · Developers · About · Nipy

# nipype.interfaces.camino.calib module

## SFLUTGen

Link to code

> Bases: StdOutCommandLine

> Wrapped executable: `sflutgen`.

> Generates PICo lookup tables (LUT) for multi-fibre methods such as PASMRI and Q-Ball.

> SFLUTGen creates the lookup tables for the generalized multi-fibre implementation of the PICo tractography algorithm. The outputs of this utility are either surface or line coefficients up to a given order. The calibration can be performed for different distributions, such as the Bingham and Watson distributions.

> This utility uses calibration data generated from SFPICOCalibData and peak information created by SFPeaks.

> The utility outputs two lut’s, `*_oneFibreSurfaceCoeffs.Bdouble` and `*_twoFibreSurfaceCoeffs.Bdouble`. Each of these files contains big-endian doubles as standard. The format of the output is:

>     dimensions    (1 for Watson, 2 for Bingham)
>     order         (the order of the polynomial)
>     coefficient_1
>     coefficient_2
>     ...
>     coefficient_N

> In the case of the Watson, there is a single set of coefficients, which are ordered:

>     constant, x, x^2, ..., x^order.

> In the case of the Bingham, there are two sets of coefficients (one for each surface), ordered so that:

>     for j = 1 to order
>       for k = 1 to order
>         coeff_i = x^j * y^k
>     where j+k < order

> Example

> To create a calibration dataset using the default settings

>     >>> import nipype.interfaces.camino as cam
>     >>> lutgen = cam.SFLUTGen()
>     >>> lutgen.inputs.in_file = 'QSH_peaks.Bdouble'
>     >>> lutgen.inputs.info_file = 'PICO_calib.info'
>     >>> lutgen.run()

> in_filea pathlike object or string representing an existing file

>   Voxel-order data of the spherical functions peaks. Maps to a command-line argument: `-inputfile %s`.

> info_filea pathlike object or string representing a file

>   The Info file that corresponds to the calibration datafile used in the reconstruction. Maps to a command-line argument: `-infofile %s`.

> argsa string

>   Additional parameters to the command. Maps to a command-line argument: `%s`.

> binincsizean integer

>   Sets the size of the bins. In the case of 2D histograms such as the Bingham, the bins are always square. Default is 1. Maps to a command-line argument: `-binincsize %d`.

> directmapa boolean

>   Use direct mapping between the eigenvalues and the distribution parameters instead of the log of the eigenvalues. Maps to a command-line argument: `-directmap`.

> environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

>   Environment variables. (Nipype default value: `{}`)

> minvectsperbinan integer

>   Specifies the minimum number of fibre-orientation estimates a bin must contain before it is used in the lut line/surface generation. Default is 50. If you get the error “no fibre-orientation estimates in histogram!”, the calibration data set is too small to get enough samples in any of the histogram bins. You can decrease the minimum number per bin to get things running in quick tests, but the sta- tistics will not be reliable and for serious applications, you need to increase the size of the calibration data set until the error goes. Maps to a command-line argument: `-minvectsperbin %d`.

> orderan integer

>   The order of the polynomial fitting the surface. Order 1 is linear. Order 2 (default) is quadratic. Maps to a command-line argument: `-order %d`.

> out_filea pathlike object or string representing a file

>   Maps to a command-line argument: `> %s` (position: -1).

> outputstema string

>   Define the name of the generated luts. The form of the filenames will be [outputstem]_oneFibreSurfaceCoeffs.Bdouble and [outputstem]_twoFibreSurfaceCoeffs.Bdouble. Maps to a command-line argument: `-outputstem %s`. (Nipype default value: `LUT`)

> pdf‘bingham’ or ‘watson’

>   Sets the distribution to use for the calibration. The default is the Bingham distribution, which allows elliptical probability density contours. Currently supported options are:

>   > - bingham – The Bingham distribution, which allows elliptical probability density contours.

>   > - watson – The Watson distribution. This distribution is rotationally symmetric.

>   Maps to a command-line argument: `-pdf %s`. (Nipype default value: `bingham`)

> lut_one_fibrea pathlike object or string representing an existing file

>   PICo lut for one-fibre model.

> lut_two_fibresa pathlike object or string representing an existing file

>   PICo lut for two-fibre model.

## SFPICOCalibData

Link to code

> Bases: StdOutCommandLine

> Wrapped executable: `sfpicocalibdata`.

> Generates Spherical Function PICo Calibration Data.

> SFPICOCalibData creates synthetic data for use with SFLUTGen. The synthetic data is generated using a mixture of gaussians, in the same way datasynth generates data. Each voxel of data models a slightly different fibre configuration (varying FA and fibre- crossings) and undergoes a random rotation to help account for any directional bias in the chosen acquisition scheme. A second file, which stores information about the datafile, is generated along with the datafile.

> Examples

> To create a calibration dataset using the default settings

>     >>> import nipype.interfaces.camino as cam
>     >>> calib = cam.SFPICOCalibData()
>     >>> calib.inputs.scheme_file = 'A.scheme'
>     >>> calib.inputs.snr = 20
>     >>> calib.inputs.info_file = 'PICO_calib.info'
>     >>> calib.run()

> The default settings create a large dataset (249,231 voxels), of which 3401 voxels contain a single fibre population per voxel and the rest of the voxels contain two fibre-populations. The amount of data produced can be varied by specifying the ranges and steps of the parameters for both the one and two fibre datasets used.

> To create a custom calibration dataset

>     >>> import nipype.interfaces.camino as cam
>     >>> calib = cam.SFPICOCalibData()
>     >>> calib.inputs.scheme_file = 'A.scheme'
>     >>> calib.inputs.snr = 20
>     >>> calib.inputs.info_file = 'PICO_calib.info'
>     >>> calib.inputs.twodtfarange = [0.3, 0.9]
>     >>> calib.inputs.twodtfastep = 0.02
>     >>> calib.inputs.twodtanglerange = [0, 0.785]
>     >>> calib.inputs.twodtanglestep = 0.03925
>     >>> calib.inputs.twodtmixmax = 0.8
>     >>> calib.inputs.twodtmixstep = 0.1
>     >>> calib.run()

> This would provide 76,313 voxels of synthetic data, where 3401 voxels simulate the one fibre cases and 72,912 voxels simulate the various two fibre cases. However, care should be taken to ensure that enough data is generated for calculating the LUT. # doctest: +SKIP

> info_filea pathlike object or string representing a file

>   The name to be given to the information output filename. Maps to a command-line argument: `-infooutputfile %s`.

> scheme_filea pathlike object or string representing an existing file

>   Specifies the scheme file for the diffusion MRI data. Maps to a command-line argument: `-schemefile %s`.

> argsa string

>   Additional parameters to the command. Maps to a command-line argument: `%s`.

> environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’

>   Environment variables. (Nipype default value: `{}`)

> onedtfarangea list of from 2 to 2 items which are a float

>   Minimum and maximum FA for the single tensor synthetic data. Maps to a command-line argument: `-onedtfarange %s`.

> onedtfastepa float

>   FA step size controlling how many steps there are between the minimum and maximum FA settings. Maps to a command-line argument: `-onedtfastep %f`.

> out_filea pathlike object or string representing a file

>   Maps to a command-line argument: `> %s` (position: -1).

> seeda float

>   Specifies the random seed to use for noise generation in simulation trials. Maps to a command-line argument: `-seed %f`.

> snra float

>   Specifies the signal-to-noise ratio of the non-diffusion-weighted measurements to use in simulations. Maps to a command-line argument: `-snr %f`.

> tracea float

>   Trace of the diffusion tensor(s) used in the test function. Maps to a command-line argument: `-trace %f`.

> twodtanglerangea list of from 2 to 2 items which are a float

>   Minimum and maximum crossing angles between the two fibres. Maps to a command-line argument: `-twodtanglerange %s`.

> twodtanglestepa float

>   Angle step size controlling how many steps there are between the minimum and maximum crossing angles for the two tensor cases. Maps to a command-line argument: `-twodtanglestep %f`.

> twodtfarangea list of from 2 to 2 items which are a float

>   Minimum and maximum FA for the two tensor synthetic data. FA is varied for both tensors to give all the different permutations. Maps to a command-line argument: `-twodtfarange %s`.

> twodtfastepa float

>   FA step size controlling how many steps there are between the minimum and maximum FA settings for the two tensor cases. Maps to a command-line argument: `-twodtfastep %f`.

> twodtmixmaxa float

>   Mixing parameter controlling the proportion of one fibre population to the other. The minimum mixing parameter is (1 - twodtmixmax). Maps to a command-line argument: `-twodtmixmax %f`.

> twodtmixstepa float

>   Mixing parameter step size for the two tensor cases. Specify how many mixing parameter increments to use. Maps to a command-line argument: `-twodtmixstep %f`.

> PICOCaliba pathlike object or string representing an existing file

>   Calibration dataset.

> calib_infoa pathlike object or string representing an existing file

>   Calibration dataset.