SPM/Programming intro

From Wikibooks, the open-content textbooks collection

Contents 1 Aim 2 Useful functions, by category 2.1 Reading image headers and data 2.2 Writing data 2.3 Reading and writing data with the alternative NIfTI class library 2.4 Geometry, voxel-world mappings 2.5 Linear (rigid/affine) registration and reslicing 2.6 Preprocessing, including segmentation and non-linear normalisation 2.7 Statistics 2.8 Viewing data 2.9 Miscellaneous 3 Illustrative examples 3.1 Reading and writing a volume (to replace NaNs with zeros) 4 Comments, complaints, constructive criticism

[edit] Aim

This page is intended to provide a quick-start guide to writing your own MATLAB scripts and functions using SPM as a library. It's based on one of John's Gems, but will hopefully grow into a more complete introduction. SPM programming can mean simply writing batch scripts to automate common pipelines, writing short helper scripts or functions to accomplish useful tasks (e.g. see the other Gems, including those for SPM2 and SPM99), writing your own SPM extensions, or even modifying your local installation of SPM.

This page unashamedly fails to provide for older versions of SPM or peculiar versions of MATLAB --- it is simply too much work for the developers and keen mailing list contributors to support multiple releases. Having said that, if a function listed below exists in SPM2 or even SPM99, then there is a reasonably good chance that it will behave similarly, but you have been warned that it might not...

[edit] Useful functions, by category

Text in parentheses indicates useful (term)s for running help term, other than or as well as the function name itself.

[edit] Reading image headers and data

• spm_vol, header information
• spm_read_vols (spm_vol), for reading entire volumes
• spm_slice_vol, for arbitrary planes
• spm_sample_vol, any voxels
• spm_get_data (spm_sample_vol), any voxels from multiple volumes
• spm_bsplins (spm_bsplinc) --- NB spm_slice_vol and spm_sample_vol offer polynomial or sinc interpolation; these functions provide b-spline interp as used in spm_reslice

[edit] Writing data

• spm_write_vol (spm_vol)
• spm_create_vol
• spm_write_plane

[edit] Reading and writing data with the alternative NIfTI class library

• nifti (@nifti/Contents, @nifti/create)
• file_array (@file_array/Contents)

[edit] Geometry, voxel-world mappings

• spm_get_space, get the voxel-world mapping matrix (a rigid or affine transform, in homogeneous coordinates)
• spm_imatrix, convert above matrix to parametrised form
• spm_matrix, convert parameter vector to affine matrix
• spm_check_orientations
• get_orig_coord5

[edit] Linear (rigid/affine) registration and reslicing

• spm_realign
• spm_coreg (spm_reslice)
• spm_affreg
• spm_reslice, needs reference image; see following for reslicing to specified geometry
• reorient (resize_img) --- available from John's Gems 2 and 3

[edit] Preprocessing, including segmentation and non-linear normalisation

• spm_preproc (spm_config_preproc, spm_prep2sn, spm_preproc_write), SPM5's unified segmentation and normalisation
• spm_normalise, the old pre-SPM5 non-unified spatial normalisation
• spm_segment, the old pre-SPM5 non-unified tissue segmentation
• spm_smooth

[edit] Statistics

• spm_ancova (spm_reml_ancova), unused by SPM itself, but often useful for scripting or educational purposes

[edit] Viewing data

• spm_check_registration (spm_image, spm_orthviews), the ubiquitous three orthogonal views
• slover, slices through images, overlays of thresholded or raw statistics; see also slice_overlay
• spm_mip_ui (spm_mip), maximum intensity projections or glass brain images

[edit] Miscellaneous

• spm_imcalc_ui (spm_imcalc)
• spm_defaults
• spm_jobman

[edit] Illustrative examples

Keep these brief! (but not as brief as current pittance!!)

[edit] Reading and writing a volume (to replace NaNs with zeros)

A simpler (but more memory-hungry) version of an old Gem. See the gem for an example of plane-wise reading and writing.

fnm = spm_select(1, 'image');
[pth bnm ext] = spm_fileparts(fnm);
VI = spm_vol(fnm);
VO = VI; % copy input info for output image
VO.fname = fullfile(pth, [bnm '_zn' ext]);
img = spm_read_vols(VI);
img(isnan(img)) = 0; % use ~isfinite instead of isnan to replace +/-inf with zero
spm_write_vol(VO,img);

[edit] Comments, complaints, constructive criticism

There may be bugs in the above code examples, and/or nonsense in the descriptions!

In time I hope this page will become a collaborative effort, but as of January 2008 much of any blame lies with me, Ged Ridgway, and therefore if you have any corrections or other suggestions, then please email me, but if I don't get back to you, then try the mailing list.