# labs.spatial_models.structural_bfls

## Module: `labs.spatial_models.structural_bfls`

Inheritance diagram for `nipy.labs.spatial_models.structural_bfls`:

The main routine of this module implement the LandmarkRegions class, that is used to represent Regions of interest at the population level (in a template space).

This has been used in Thirion et al. Structural Analysis of fMRI Data Revisited: Improving the Sensitivity and Reliability of fMRI Group Studies. IEEE TMI 2007

Author : Bertrand Thirion, 2006-2013

## `LandmarkRegions`

class nipy.labs.spatial_models.structural_bfls.LandmarkRegions(domain, k, indiv_coord, subjects, confidence)

  Bases: `object`

  This class is intended to represent a set of inter-subject regions It should inherit from some abstract multiple ROI class, not implemented yet.

  __init__(domain, k, indiv_coord, subjects, confidence)

    Building the landmark_region

    Parameters:
      domain: ROI instance

        defines the spatial context of the SubDomains

      k: int,

        the number of landmark regions considered

      indiv_coord: k-length list of arrays,

        coordinates of the nodes in some embedding space.

      subjects: k-length list of integers

        these correspond to an ROI feature: the subject index of individual regions

      confidence: k-length list of arrays,

        confidence values for the regions (0 is low, 1 is high)

  centers()

    returns the average of the coordinates for each region

  kernel_density(k=None, coord=None, sigma=1.0)

    Compute the density of a component as a kde

    Parameters:
      k: int (<= self.k) or None

        component upon which the density is computed if None, the sum is taken over k

      coord: array of shape(n, self.dom.em_dim), optional

        a set of input coordinates

      sigma: float, optional

        kernel size

    Returns:
      kde: array of shape(n)

        the density sampled at the coords

  map_label(coord=None, pval=1.0, sigma=1.0)

    Sample the set of landmark regions on the proposed coordinate set cs, assuming a Gaussian shape

    Parameters:
      coord: array of shape(n,dim), optional,

        a set of input coordinates

      pval: float in [0,1]), optional

        cutoff for the CR, i.e. highest posterior density threshold

      sigma: float, positive, optional

        spatial scale of the spatial model

    Returns:
      label: array of shape (n): the posterior labelling
  roi_prevalence()

    Return a confidence index over the different rois

    Returns:
      confid: array of shape self.k

        the population_prevalence

  show()

    function to print basic information on self

nipy.labs.spatial_models.structural_bfls.build_landmarks(domain, coords, subjects, labels, confidence=None, prevalence_pval=0.95, prevalence_threshold=0, sigma=1.0)

  Given a list of hierarchical ROIs, and an associated labelling, this creates an Amer structure wuch groups ROIs with the same label.

  Parameters:
    domain: discrete_domain.DiscreteDomain instance,

      description of the spatial context of the landmarks

    coords: array of shape(n, 3)

      Sets of coordinates for the different objects

    subjects: array of shape (n), dtype = np.int_

      indicators of the dataset the objects come from

    labels: array of shape (n), dtype = np.int_

      index of the landmark the object is associated with

    confidence: array of shape (n),

      measure of the significance of the regions

    prevalence_pval: float, optional
    prevalence_threshold: float, optional,

      (c) A label should be present in prevalence_threshold subjects with a probability>prevalence_pval in order to be valid

    sigma: float optional,

      regularizing constant that defines a prior on the region extent

  Returns:
    LR None or structural_bfls.LR instance

      describing a cross-subject set of ROIs. If inference yields a null result, LR is set to None

    newlabel: array of shape (n)

      a relabelling of the individual ROIs, similar to u, that discards labels that do not fulfill the condition (c)