Home · Quickstart · Documentation · About · Nipy

# interfaces.camino.connectivity

## Conmat

Link to code

Wraps command conmat

Creates a connectivity matrix using a 3D label image (the target image) and a set of streamlines. The connectivity matrix records how many stream- lines connect each pair of targets, and optionally the mean tractwise statistic (eg tract-averaged FA, or length).

The output is a comma separated variable file or files. The first row of the output matrix is label names. Label names may be defined by the user, otherwise they are assigned based on label intensity.

Starting from the seed point, we move along the streamline until we find a point in a labeled region. This is done in both directions from the seed point. Streamlines are counted if they connect two target regions, one on either side of the seed point. Only the labeled region closest to the seed is counted, for example if the input contains two streamlines:

    1: A-----B------SEED---C
    2: A--------SEED-----------

then the output would be

    A,B,C
    0,0,0
    0,0,1
    0,1,0

There are zero connections to A because in streamline 1, the connection to B is closer to the seed than the connection to A, and in streamline 2 there is no region reached in the other direction.

The connected target regions can have the same label, as long as the seed point is outside of the labeled region and both ends connect to the same label (which may be in different locations). Therefore this is allowed:

    A------SEED-------A

Such fibers will add to the diagonal elements of the matrix. To remove these entries, run procstreamlines with -endpointfile before running conmat.

If the seed point is inside a labled region, it counts as one end of the connection. So

    ----[SEED inside A]---------B

counts as a connection between A and B, while

    C----[SEED inside A]---------B

counts as a connection between A and C, because C is closer to the seed point.

In all cases, distance to the seed point is defined along the streamline path.

### Example 1

To create a standard connectivity matrix based on streamline counts.

    >>> import nipype.interfaces.camino as cam
    >>> conmat = cam.Conmat()
    >>> conmat.inputs.in_file = 'tracts.Bdouble'
    >>> conmat.inputs.target_file = 'atlas.nii.gz'
    >>> conmat.run()

### Example 1

To create a standard connectivity matrix and mean tractwise FA statistics.

    >>> import nipype.interfaces.camino as cam
    >>> conmat = cam.Conmat()
    >>> conmat.inputs.in_file = 'tracts.Bdouble'
    >>> conmat.inputs.target_file = 'atlas.nii.gz'
    >>> conmat.inputs.scalar_file = 'fa.nii.gz'
    >>> conmat.tract_stat         = 'mean'
    >>> conmat.run()

Inputs:

    [Mandatory]
    in_file: (an existing file name)
            Streamlines as generated by the Track interface
            flag: -inputfile %s
    target_file: (an existing file name)
            An image containing targets, as used in ProcStreamlines interface.
            flag: -targetfile %s

    [Optional]
    args: (a unicode string)
            Additional parameters to the command
            flag: %s
    environ: (a dictionary with keys which are a newbytes or None or a
             newstr or None and with values which are a newbytes or None or a
             newstr or None, 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
    output_root: (a file name)
            filename root prepended onto the names of the output files. The
            extension will be determined from the input.
            flag: -outputroot %s
    scalar_file: (an existing file name)
            Optional scalar file for computing tract-based statistics. Must be
            in the same space as the target file.
            flag: -scalarfile %s
            requires: tract_stat
    targetname_file: (an existing file name)
            Optional names of targets. This file should contain one entry per
            line, with the target intensity followed by the name, separated by
            white space. For example: 1 some_brain_region 2 some_other_region
            These names will be used in the output. The names themselves should
            not contain spaces or commas. The labels may be in any order but the
            output matrices will be ordered by label intensity.
            flag: -targetnamefile %s
    terminal_output: (u'stream' or u'allatonce' or u'file' or u'none')
            Control terminal output: `stream` - displays to terminal immediately
            (default), `allatonce` - waits till command is finished to display
            output, `file` - writes output to file, `none` - output is ignored
    tract_prop: (u'length' or u'endpointsep')
            Tract property average to compute in the connectivity matrix. See
            TractStats for details.
            flag: -tractstat %s
            mutually_exclusive: tract_stat
    tract_stat: (u'mean' or u'min' or u'max' or u'sum' or u'median' or
             u'var')
            Tract statistic to use. See TractStats for other options.
            flag: -tractstat %s
            mutually_exclusive: tract_prop
            requires: scalar_file

Outputs:

    conmat_sc: (an existing file name)
            Connectivity matrix in CSV file.
    conmat_ts: (a file name)
            Tract statistics in CSV file.