# labs.mask

## Module: `labs.mask`

Utilities for extracting masks from EPI images and applying them to time series.

## Functions

nipy.labs.mask.compute_mask(mean_volume, reference_volume=None, m=0.2, M=0.9, cc=True, opening=2, exclude_zeros=False)

  Compute a mask file from fMRI data in 3D or 4D ndarrays.

  Compute and write the mask of an image based on the grey level This is based on an heuristic proposed by T.Nichols: find the least dense point of the histogram, between fractions m and M of the total image histogram.

  In case of failure, it is usually advisable to increase m.

  Parameters:
    mean_volume 3D ndarray

      mean EPI image, used to compute the threshold for the mask.

    reference_volume: 3D ndarray, optional

      reference volume used to compute the mask. If none is give, the mean volume is used.

    m float, optional

      lower fraction of the histogram to be discarded.

    M: float, optional

      upper fraction of the histogram to be discarded.

    cc: boolean, optional

      if cc is True, only the largest connect component is kept.

    opening: int, optional

      if opening is larger than 0, an morphological opening is performed, to keep only large structures. This step is useful to remove parts of the skull that might have been included.

    exclude_zeros: boolean, optional

      Consider zeros as missing values for the computation of the threshold. This option is useful if the images have been resliced with a large padding of zeros.

  Returns:
    mask 3D boolean ndarray

      The brain mask

nipy.labs.mask.compute_mask_files(input_filename, output_filename=None, return_mean=False, m=0.2, M=0.9, cc=1, exclude_zeros=False, opening=2)

  Compute a mask file from fMRI nifti file(s)

  Compute and write the mask of an image based on the grey level This is based on an heuristic proposed by T.Nichols: find the least dense point of the histogram, between fractions m and M of the total image histogram.

  In case of failure, it is usually advisable to increase m.

  Parameters:
    input_filename string

      nifti filename (4D) or list of filenames (3D).

    output_filename string or None, optional

      path to save the output nifti image (if not None).

    return_mean boolean, optional

      if True, and output_filename is None, return the mean image also, as a 3D array (2nd return argument).

    m float, optional

      lower fraction of the histogram to be discarded.

    M: float, optional

      upper fraction of the histogram to be discarded.

    cc: boolean, optional

      if cc is True, only the largest connect component is kept.

    exclude_zeros: boolean, optional

      Consider zeros as missing values for the computation of the threshold. This option is useful if the images have been resliced with a large padding of zeros.

    opening: int, optional

      Size of the morphological opening performed as post-processing

  Returns:
    mask 3D boolean array

      The brain mask

    mean_image 3d ndarray, optional

      The main of all the images used to estimate the mask. Only provided if return_mean is True.

nipy.labs.mask.compute_mask_sessions(session_images, m=0.2, M=0.9, cc=1, threshold=0.5, exclude_zeros=False, return_mean=False, opening=2)

  Compute a common mask for several sessions of fMRI data.

  > Uses the mask-finding algorithms to extract masks for each session, and then keep only the main connected component of the a given fraction of the intersection of all the masks.

  Parameters:
    session_images list of (list of strings) or nipy image objects

      A list of images/list of nifti filenames. Each inner list/image represents a session.

    m float, optional

      lower fraction of the histogram to be discarded.

    M: float, optional

      upper fraction of the histogram to be discarded.

    cc: boolean, optional

      if cc is True, only the largest connect component is kept.

    threshold float, optional

      the inter-session threshold: the fraction of the total number of session in for which a voxel must be in the mask to be kept in the common mask. threshold=1 corresponds to keeping the intersection of all masks, whereas threshold=0 is the union of all masks.

    exclude_zeros: boolean, optional

      Consider zeros as missing values for the computation of the threshold. This option is useful if the images have been resliced with a large padding of zeros.

    return_mean: boolean, optional

      if return_mean is True, the mean image across subjects is returned.

    opening: int, optional,

      size of the morphological opening

  Returns:
    mask 3D boolean ndarray

      The brain mask

    mean 3D float array

      The mean image

nipy.labs.mask.intersect_masks(input_masks, output_filename=None, threshold=0.5, cc=True)

  Given a list of input mask images, generate the output image which is the the threshold-level intersection of the inputs

  Parameters:
    input_masks: list of strings or ndarrays

      paths of the input images nsubj set as len(input_mask_files), or individual masks.

    output_filename, string:

      Path of the output image, if None no file is saved.

    threshold: float within [0, 1[, optional

      gives the level of the intersection. threshold=1 corresponds to keeping the intersection of all masks, whereas threshold=0 is the union of all masks.

    cc: bool, optional

      If true, extract the main connected component

  Returns:
    grp_mask, boolean array of shape the image shape

nipy.labs.mask.largest_cc(mask)

  Return the largest connected component of a 3D mask array.

  Parameters:
    mask: 3D boolean array

      3D array indicating a mask.

  Returns:
    mask: 3D boolean array

      3D array indicating a mask, with only one connected component.

nipy.labs.mask.series_from_mask(filenames, mask, dtype=<class 'numpy.float32'>, smooth=False, ensure_finite=True)

  Read the time series from the given sessions filenames, using the mask.

  Parameters:
    filenames: list of 3D nifti file names, or 4D nifti filename.

      Files are grouped by session.

    mask: 3d ndarray

      3D mask array: true where a voxel should be used.

    smooth: False or float, optional

      If smooth is not False, it gives the size, in voxel of the spatial smoothing to apply to the signal.

    ensure_finite: boolean, optional

      If ensure_finite is True, the non-finite values (NaNs and infs) found in the images will be replaced by zeros

  Returns:
    session_series: ndarray

      3D array of time course: (session, voxel, time)

    header: header object

      The header of the first file.

  Notes

  When using smoothing, ensure_finite should be True: as elsewhere non finite values will spread across the image.

nipy.labs.mask.threshold_connect_components(map, threshold, copy=True)
  Given a map with some coefficients set to zero, segment the

    connect components with number of voxels smaller than the threshold and set them to 0.

  Parameters:
    map: ndarray,

      The spatial map to segment

    threshold: scalar,

      The minimum number of voxels to keep a cluster.

    copy: bool, optional

      If copy is false, the input array is modified inplace

  Returns:
    map: ndarray,

      the map with connected components removed