to_nii improvements

[lucywowen]

• the to_nii function needs to be better explained-- e.g. what’s the “template” argument do and how is it used?

• be able to change the samplerate for .nii files that are saved out (e.g. to downsample enormous files) and/or to select out specific time ranges to save out

• add shortcuts for templates i.e. to_nii('10mm')

[lucywowen]

If template is None:

• calculate voxel size (ex. 20)
• check if appropriate nifti exists (ex 20_20_20.nii)
• if doesn't exist, downsample standard brain and save

If template is '20mm' (or '8mm' or '6mm'):

• shortcut to existing nifti

if template is 20:

• check if appropriate nifti exists (ex 20_20_20.nii)
• if not, downsample and save

if template is /path/to/nifti:

• load that nifti and use it as template

[jeremymanning]

here is the full (proposed) logic:

add a get_brain_object function that supports the following argument types (call the argument x):

• If x is a string: check if the string refers to an existing file name (with or without an extension). if so, load the .nii, .nii.gz, or .bo file that it corresponds to and return the brain object. (If .nii or .nii.gz, need to create a brain object first.)
  • if the file name doesn't exist, check to see if it is in the format x_y_z (with or without an extension), where x, y, and z are numbers (either ints or floats). If so:
    • resample the standard brain to have voxel sizes of dimensions x, y, and z
    • save the nifti file locally as x_y_z.nii.gz (so that it doesn't have to be recomputed next time)
    • return get_brain_object(x) (this should load the just-computed nifti file and return a brain object)
  • if the file name doesn't exist and isn't in the x_y_z format, throw an error (invalid format)
• if x is a brain object: just return the brain object
• if x is a nibabel.Nifti1Image: create a brain object from the nifti image and return it
• if x is a 3-element tuple, list, or numpy array: resample the standard brain to the given resolution (if the appropriate file doesn't already exist) and return get_brain_object(x[0] + '_' + x[1] + '_' + x[2])
• if x is a single positive number, return get_brain_object(x*np.ones_like([0, 0, 0])
• else: throw an error (invalid format)

for the to_nii function, support the following cases:
if template is None:

• compute voxel size, v
• use get_brain_object(v) as the template
  otherwise use get_brain_object(template) as the template

[jeremymanning]

updated logic (following some changes to code):

1. compute voxel size, v
2. ensure the minimum voxel dimension (along x, y, and z) is no less than 1mm (anything smaller is not supported; it'd result in an enormous file size). in other words, set v[v < 1] = 1.
3. take the user-specified template and resample it to have voxels of size v. the template can be one of three (general) options: 'gray' (default; gray matter mask of standard MNI152 brain), 'std' (standard MNI 152 brain), or the user can specify any other nifti image (either as a filename or a nibabel.Nifti1Image object)
4. use the resampled template to create the final nifti file

[lucywowen]

I've implemented these changes, but I think we should discuss defaults.

I don't think that we should have it use the brain object voxel size (electrodes tend to be very close together... less than 1mm, so if you're using a patient's electrode locations it takes forever).

However, it would be nice to have a reasonable 'smart' default for the reconstructions that looks at the voxel size that was used to make the model and uses that as the template.

Possibly if x, y, and z are all equal use that?? Seems like there's a clever way to check to see if the locations are derived from a specific template or if they are electrode locations (and irregularly spaced) and change the default according to that.