# labs.spatial_models.parcel_io

## Module: `labs.spatial_models.parcel_io`

Utility functions for mutli-subjectParcellation: this basically uses nipy io lib to perform IO opermation in parcel definition processes

## Functions

nipy.labs.spatial_models.parcel_io.fixed_parcellation(mask_image, betas, nbparcel, nn=6, method='ward', write_dir=None, mu=10.0, verbose=0, fullpath=None)

  Fixed parcellation of a given dataset

  Parameters:
    domain/mask_image
    betas: list of paths to activation images from the subject
    nbparcel, int number of desired parcels
    nn=6: number of nearest neighbors to define the image topology

      (6, 18 or 26)

    method=’ward’: clustering method used, to be chosen among

      ‘ward’, ‘gkm’, ‘ward_and-gkm’ ‘ward’: Ward’s clustering algorithm ‘gkm’: Geodesic k-means algorithm, random initialization ‘gkm_and_ward’: idem, initialized by Ward’s clustering

    write_di: string, topional, write directory.

      If fullpath is None too, then no file output.

    mu = 10., float: the relative weight of anatomical information
    verbose=0: verbosity mode
    fullpath=None, string,

      path of the output image If write_dir and fullpath are None then no file output. If only fullpath is None then it is the write dir + a name depending on the method.

  Notes

  Ward’s method takes time (about 6 minutes for a 60K voxels dataset)

  Geodesic k-means is ‘quick and dirty’

  Ward’s + GKM is expensive but quite good

  To reduce CPU time, rather use nn=6 (especially with Ward)

nipy.labs.spatial_models.parcel_io.mask_parcellation(mask_images, nb_parcel, threshold=0, output_image=None)

  Performs the parcellation of a certain mask

  Parameters:
    mask_images: string or Nifti1Image or list of strings/Nifti1Images,

      paths of mask image(s) that define(s) the common space.

    nb_parcel: int,

      number of desired parcels

    threshold: float, optional,

      level of intersection of the masks

    output_image: string, optional

      path of the output image

  Returns:
    wim: Nifti1Imagine instance, representing the resulting parcellation

nipy.labs.spatial_models.parcel_io.parcel_input(mask_images, learning_images, ths=0.5, fdim=None)

  Instantiating a Parcel structure from a give set of input

  Parameters:
    mask_images: string or Nifti1Image or list of strings/Nifti1Images,

      paths of mask image(s) that define(s) the common space.

    learning_images: (nb_subject-) list of (nb_feature-) list of strings,

      paths of feature images used as input to the parcellation procedure

    ths=.5: threshold to select the regions that are common across subjects.

      if ths = .5, thethreshold is half the number of subjects

    fdim: int, optional

      if nb_feature (the dimension of the data) used in subsequent analyses if greater than fdim, a PCA is performed to reduce the information in the data Byd efault, no reduction is performed

  Returns:
    domain discrete_domain.DiscreteDomain instance

      that stores the spatial information on the parcelled domain

    feature: (nb_subect-) list of arrays of shape (domain.size, fdim)

      feature information available to parcellate the data

nipy.labs.spatial_models.parcel_io.parcellation_based_analysis(Pa, test_images, test_id='one_sample', rfx_path=None, condition_id='', swd=None)

  This function computes parcel averages and RFX at the parcel-level

  Parameters:
    Pa: MultiSubjectParcellation instance

      the description of the parcellation

    test_images: (Pa.nb_subj-) list of paths

      paths of images used in the inference procedure

    test_id: string, optional,

      if test_id==’one_sample’, the one_sample statstic is computed otherwise, the parcel-based signal averages are returned

    rfx_path: string optional,

      path of the resulting one-sample test image, if applicable

    swd: string, optional

      output directory used to compute output path if rfx_path is not given

    condition_id: string, optional,

      contrast/condition id used to compute output path

  Returns:
    test_data: array of shape(Pa.nb_parcel, Pa.nb_subj)

      the parcel-level signal average if test is not ‘one_sample’

    prfx: array of shape(Pa.nb_parcel),

      the one-sample t-value if test_id is ‘one_sample’

nipy.labs.spatial_models.parcel_io.write_parcellation_images(Pa, template_path=None, indiv_path=None, subject_id=None, swd=None)

  Write images that describe the spatial structure of the parcellation

  Parameters:
    Pa MultiSubjectParcellation instance,

      the description of the parcellation

    template_path: string, optional,

      path of the group-level parcellation image

    indiv_path: list of strings, optional

      paths of the individual parcellation images

    subject_id: list of strings of length Pa.nb_subj

      subject identifiers, used to infer the paths when not available

    swd: string, optional

      output directory used to infer the paths when these are not available