pyhrf package – PyHRF is a set of tools for within-subject fMRI data analysis, which focuses on the characterization of the hemodynamics.
Within the chain of fMRI data processing, these tools provide alternatives to the classical within-subject GLM estimation step. The inputs are preprocessed within-subject data and the outputs are statistical maps and/or fitted HRFs.
The package is mainly written in Python and provides the implementation of the two following methods:
The joint-detection estimation (JDE) approach, which divides the brain into functionnaly homogeneous regions and provides one HRF estimate per region as well as response levels specific to each voxel and each experimental condition. This method embeds a temporal regularization on the estimated HRFs and an adaptive spatial regularization on the response levels.
The Regularized Finite Impulse Response (RFIR) approach, which provides HRF estimates for each voxel and experimental conditions. This method embeds a temporal regularization on the HRF shapes, but proceeds independently across voxels (no spatial model).
pyhrf.ndarray module – This module provides classes and functions to handle multi-dimensionnal numpy array (ndarray) objects and extend them with some semantics (axes labels and axes domains). See xndarray class. (TODO: make xndarray inherit numpy.ndarray?)exception pyhrf.ndarray.ArrayMappingError
Map the flat_axis of flat_data onto the region within mask. flat_data is then reshaped so that flat_axis is replaced with mask.shape
m is the result of np.where(mask) -> can be passed to speed up if already done before
Example 1 >>> a = np.array([1,2,3]) >>> m = np.array([[0,1,0], [0,1,1]] ) >>> expand_array_in_mask(a,m) array([[0, 1, 0],[0, 2, 3]])
Example 2 >>> a = np.array([[1,2,3],[4,5,6]]) >>> m = np.array([[0,1,0], [0,1,1]] ) >>> expand_array_in_mask(a,m,flat_axis=1) array([[[0, 1, 0],[0, 2, 3]],<BLANKLINE>[[0, 4, 0],[0, 5, 6]]])pyhrf.ndarray.merge(arrays, mask, axis, fill_value=0)
Merge the given arrays into a single array according to the given mask, with the given axis being mapped to those of mask. Assume that arrays[id] corresponds to mask==id and that all arrays are in the same orientation.Arg:
arrays (dict of xndarrays):
mask (xndarray): defines the mapping between the flat axis in thearrays to merge and the target expanded axes.
Stack xndarray instances in list ‘c_list’ along a new axis label ‘axis’. If ‘domain’ (numpy array or list) is provided, it is associated to the new axis. All cuboids in ‘c_list’ must have the same orientation and domains. ‘axis_pos’ defines the position of the new axis: either ‘first’ or ‘last’.
Stack all arrays within input tree into a single array.
tree (–) – nested dictionnaries of xndarray objects. Each level of the tree correspond to a target axis, each key of the tree correspond to an element of the domain associated to that axis.level_labels (–) – axis labels corresponding to each level of the tree
Return true if other cuboid contains the same data. TODO: should it be irrespective of the orientation ?add(c, dest=None)astype(t)cexpand(cmask, axis, dest=None)
Same as expand but mask is a cuboid
TODO: + unit testcflatten(cmask, new_axis)copy(copy_meta_data=False)
Return copy of the current cuboid. Domains are copied with a shallow dictionnary copy.descrip()
Return a printable string describing the cuboid.descrip_shape()divide(c, dest=None)expand(mask, axis, target_axes=None, target_domains=None, dest=None, do_checks=True, m=None)
Create a new xndarray instance (or store into an existing ‘dest’ cuboid) where ‘axis’ is expanded and values are mapped according to ‘mask’. ‘target_axes’ is a list of the names of the new axes replacing ‘axis’. ‘target_domains’ is a dict of domains for the new axes.
Return a cuboid with new orientation. If cuboid is already in the right orientation, then return the current cuboid. Else, create a new one.repeat(n, new_axis, domain=None)
Return a new cuboid with self’s data repeated ‘n’ times along a new axis labelled ‘new_axis’. Associated ‘domain’ can be provided.rescale_values(v_min=0.0, v_max=1.0, axis=None)roll(axis, pos=-1)
Roll xndarray by making ‘axis’ the last axis. ‘pos’ is either 0 or -1 (first or last, respectively) TODO: handle all pos.save(file_name, meta_data=None, set_MRI_orientation=False)
Save cuboid to a file. Supported format: Nifti1. ‘meta_data’ shoud be a 2-elements tuple: (affine matrix, Nifti1Header instance). If provided, the meta_data attribute of the cuboid is ignored. All extra axis information is stored as an extension.set_MRI_orientation()
Set orientation to sagittal,coronal,axial,[time|iteration|condition] Priority for the 4th axis: time > condition > iteration. The remaining axes are sorted in alphatical orderset_axis_domain(axis_id, domain)
Set the value domain mapped to axis_id as domain
axis_id (–) – label of the axisdomain (–) – value domain
Set the cuboid orientation (inplace) according to input axes labelssplit(axis)
Split a cuboid along given axis. Return an OrderedDict of cuboids.squeeze(axis=None)
Remove all dims which have length=1. ‘axis’ selects a subset of the single-dimensional axes.squeeze_all_but(axes)std(axis=None)sub_cuboid(orientation=None, **kwargs)
Return a sub cuboid. ‘kwargs’ allows argument in the form: axis=slice_value.sub_cuboid_from_slices(orientation=None, **kwargs)
Return a sub cuboid. ‘kwargs’ allows argument in the form: axis=slice_index.substract(c, dest=None)sum(axis=None)swapaxes(a1, a2)
Swap axes a1 and a2
a1 (–) – identifier of the 1st axisa2 (–) – identifier of the 2nd axis
A new cuboid wrapping a swapped view of the numpy array
Render the array as an html table whose column headers correspond to domain values and axis names defined by col_axes, row headers defined by row_axes and inner cell axes defined by inner_axes Data within a cell can be render as text or as a plot figure (image files are produced)