.. AUTO-GENERATED FILE -- DO NOT EDIT!

interfaces.camino.calib
=======================


.. _nipype.interfaces.camino.calib.SFLUTGen:


.. index:: SFLUTGen

SFLUTGen
--------

`Link to code <http://github.com/nipy/nipype/tree/49d76df8df526ae0790ff6079642565548bc4434/nipype/interfaces/camino/calib.py#L174>`__

Wraps command **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()        # doctest: +SKIP

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                Voxel-order data of the spherical functions peaks.
        info_file: (a file name)
                The Info file that corresponds to the calibration datafile used in
                the reconstruction.
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        binincsize: (an 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.
        directmap: (a boolean)
                Use direct mapping between the eigenvalues and the distribution
                parameters instead of the log of the eigenvalues.
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        in_file: (an existing file name)
                Voxel-order data of the spherical functions peaks.
        info_file: (a file name)
                The Info file that corresponds to the calibration datafile used in
                the reconstruction.
        minvectsperbin: (an 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.
        order: (an integer)
                The order of the polynomial fitting the surface. Order 1 is linear.
                Order 2 (default) is quadratic.
        out_file: (a file name)
        outputstem: (a string, nipype default value: LUT)
                Define the name of the generated luts. The form of the filenames
                will be [outputstem]_oneFibreSurfaceCoeffs.Bdouble and
                [outputstem]_twoFibreSurfaceCoeffs.Bdouble
        pdf: ('bingham' or 'watson', nipype default value: bingham)
                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.
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

Outputs::

        lut_one_fibre: (an existing file name)
                PICo lut for one-fibre model
        lut_two_fibres: (an existing file name)
                PICo lut for two-fibre model

.. _nipype.interfaces.camino.calib.SFPICOCalibData:


.. index:: SFPICOCalibData

SFPICOCalibData
---------------

`Link to code <http://github.com/nipy/nipype/tree/49d76df8df526ae0790ff6079642565548bc4434/nipype/interfaces/camino/calib.py#L64>`__

Wraps command **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.

Example 1
~~~~~~~~~
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()           # doctest: +SKIP

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.

Example 2
~~~~~~~~~
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()              # doctest: +SKIP

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

Inputs::

        [Mandatory]
        info_file: (a file name)
                The name to be given to the information output filename.
        scheme_file: (an existing file name)
                Specifies the scheme file for the diffusion MRI data
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored

        [Optional]
        args: (a string)
                Additional parameters to the command
        environ: (a dictionary with keys which are a value of type 'str' and
                 with values which are a value of type 'str', nipype default value:
                 {})
                Environment variables
        ignore_exception: (a boolean, nipype default value: False)
                Print an error message instead of throwing an exception in case the
                interface fails to run
        info_file: (a file name)
                The name to be given to the information output filename.
        onedtfarange: (a list of from 2 to 2 items which are a float)
                Minimum and maximum FA for the single tensor synthetic data.
        onedtfastep: (a float)
                FA step size controlling how many steps there are between the
                minimum and maximum FA settings.
        out_file: (a file name)
        scheme_file: (an existing file name)
                Specifies the scheme file for the diffusion MRI data
        seed: (a float)
                Specifies the random seed to use for noise generation in simulation
                trials.
        snr: (a float)
                Specifies the signal-to-noise ratio of the non-diffusion-weighted
                measurements to use in simulations.
        terminal_output: ('stream' or 'allatonce' or 'file' or 'none')
                Control terminal output: `stream` - displays to terminal
                immediately, `allatonce` - waits till command is finished to display
                output, `file` - writes output to file, `none` - output is ignored
        trace: (a float)
                Trace of the diffusion tensor(s) used in the test function.
        twodtanglerange: (a list of from 2 to 2 items which are a float)
                Minimum and maximum crossing angles between the two fibres.
        twodtanglestep: (a float)
                Angle step size controlling how many steps there are between the
                minimum and maximum crossing angles for the two tensor cases.
        twodtfarange: (a 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.
        twodtfastep: (a float)
                FA step size controlling how many steps there are between the
                minimum and maximum FA settings for the two tensor cases.
        twodtmixmax: (a float)
                Mixing parameter controlling the proportion of one fibre population
                to the other. The minimum mixing parameter is (1 - twodtmixmax).
        twodtmixstep: (a float)
                Mixing parameter step size for the two tensor cases. Specify how
                many mixing parameter increments to use.

Outputs::

        PICOCalib: (an existing file name)
                Calibration dataset
        calib_info: (an existing file name)
                Calibration dataset
