nisl/tutorial — pull request #47 by pgervais (2013-04-22 12:13:03+00:00)
Title: Regions/parcellation handling functions (request for comment)

This pull request is unfinished, this is just a request for comments right now.

A few functions for doing processing on brain regions have been added:

- Conversion between different storage formats (4D array, 3D array containing labels, list of 3D arrays)
- Extraction of timeseries for each region from fMRI data, using a generative model, and conversely.
- Masking/unmasking of regions.
- Test for intersection of regions.

**For a clear view of the new API, compile the documentation (cd doc; make) and browse the "Reference" page.** For example usage, see in tests/test_region.py

Comments are welcome, especially for masking/unmasking of regions. So far, two new functions have been added: apply_mask_to_regions() and unapply_mask_to_regions(), that most of the time act as wrappers for apply_mask() and unapply_mask(). The only case where things are different is when regions are described as a 3D array containing labels: an additional step is then required.

An alternative API would be to slightly change apply_mask() and unapply_mask(), to make them process regions as well. I think we could do with just a keyword argument like:

apply_mask(regions_img, mask_img, regions=True)

instead of

apply_mask_to_regions(regions_img, mask_img)

Tell me what you think.