John's Gems 2
Please note that since 2010 I no longer update John's Gems, and have instead integrated them into my blog Neuroimaging Tips & Tools. Please use the JohnGems tag in the blog to find all the Gems.
SPM2Specific code snippets by John Ashburner
John Ashburner is an author of SPM and frequent contributor to the SPM email list. Many of his answers consist of short snippets of code that are incredibly useful for SPM2 analyses. Below are the most some of the best (the 'gems') in an accessible form. (The inspiration for this page is "Graphics Gems", a series of books containing short bits of useful code for computer graphics.)
We don't yet know about any undiscovered bugs, so we aren't sure if they exist or not.
JA, Mar 21, 2003.
I haven't tested them all but I'll make bug fixes as I find them. I hope you find this useful.
See also the SPM99 gems page and New! the SPM5 gems page.
Gem 1: Transformation Matricies in SPM2 vs SPM99Subject: Re: spm2b: spm_header_edit.m From: John Ashburner <john@FIL.ION.UCL.AC.UK> Date: Fri, 7 Feb 2003 19:09:38 +0000 (14:09 EST) To: SPM@JISCMAIL.AC.UK > Following your previous answer it looks like the origin is indeed set to > the new value in the header, but also the .mat file is written. In this > file, I find two matrices: M and mat. I noticed that they are identical if > defaults.analyze.flip = 0 but if defaults.analyze.flip = 1 one of them is > flipped (M(1,4)=mat(1,4)). Why are there two transformation matrices? Backwards compatibility. The M variable is for compatibility with SPM99, whereas the mat variable is the one used for SPM2. Images produced by SPM2b that have a .mat file should be compatible between analyses with different defaults.analyze.flip settings. In other words, reading the orientation of images with .mat files containing the mat field does not require identifying the value of defaults.analyze.flip. However, if the orientation etc is read from an SPM99 .mat file, or from the .hdr, then the defaults.analyze.flip variable is consulted. If a .mat file exists, then it is read, otherwise the relevant information is taken from the .hdr and defaults.analyze.flip. If a mat variable exists in the mat file then it is used, otherwise the orientation is derived from the M variable and defaults.analyze.flip. Best regards, John Gem 2: Making your own MINC SPM2 templatesSubject: Re: FDP template  SPM99 version From: John Ashburner <john@FIL.ION.UCL.AC.UK> Date: Thu, 27 Mar 2003 16:53:03 +0000 (11:53 EST) To: SPM@JISCMAIL.AC.UK > Those who use the FDG template should know that is was created for SPM99, > and is thus in the standard orientation for that program, which is the > opposite from that used in SPM2b. > > I believe that John Ashburner has agreed to convert to MINC format for use > in SPM2b. Converting from SPM99 to SPM2b templates can be pretty easy. In this case, the command was (all one line): rawtominc transverse short signed range 0 32767 real_range 0 32767 orange 0 32767 xstep 2 ystep 2 zstep 2 xstart 90 ystart 126 zstart 72 xdircos 1 0 0 ydircos 0 1 0 zdircos 0 0 1 pet FDG.mnc 91 109 91 < template_FDG_PET_OSEM_seg.img The converted template can be downloaded from: ftp://ftp.fil.ion.ucl.ac.uk/spm/spm2b_updates/templates/ rawtominc can be obtained from: ftp://ftp.bic.mni.mcgill.ca/pub/minc/ Note that the simple conversion only applies to SPM99 templates in Analyze format. If you do the same with SPM2b generated templates, then you will need to do a leftright flip to them first. Best regards, John Gem 3: Finding pvalue and statistics for all voxels(Note: The program in this email was corrected; I have added the corrections to this message. Also, an additional typo was discovered in Sep 2003 and was fixed.) Subject: Re: tabulate all voxels of a volume or cluster From: John Ashburner <john@FIL.ION.UCL.AC.UK> Date: Thu, 27 Mar 2003 14:26:56 +0000 (09:26 EST) To: SPM@JISCMAIL.AC.UK > Is there a possibility to tabulate the pvalues and statistics for all > voxels for the entire volume. (not only the peaks) ? > Or which data file should I readout to get the desired > values? Copy and paste the following into Matlab, and select the appropriate spmT or spmF images. The first 3 columns are MNI coordinates. The fourth is the statistic. I haven't included any pvalues, but this would be a relatively simple operation, provifing you can figure out degres of freedom etc. Use spm_Tcdf.m or spm_Fcdf.m to do this. P=spm_get(1,'*.img','Select statistic image'); V=spm_vol(P); [x,y,z] = ndgrid(1:V.dim(1),1:V.dim(2),0); for i=1:V.dim(3), z = z + 1; tmp = spm_sample_vol(V,x,y,z,0); msk = find(tmp~=0 & finite(tmp)); if ~isempty(msk), tmp = tmp(msk); xyz1=[x(msk)'; y(msk)'; z(msk)'; ones(1,length(msk))]; xyzt=V.mat(1:3,:)*xyz1; for j=1:length(tmp), fprintf('%.4g %.4g %.4g\t%g\n',xyzt(1,j),xyzt(2,j),xyzt(3,j),tmp(j)); end; end; end; Best regards, John Gem 4: log10 Pvalues from T imagesPvalue images are difficult to visualize since "important" values are small and clumped near zero. A log10 transformation makes for much better visualization while still having interpretability (e.g. a value of 3 cooresponds to P=0.001). This function, T2nltP, will create log10 Pvalue image based on either a contrast number (which must be a T contrast) or a T statistic image and the degrees of freedom. This version for SPM2 was created Michael Moffitt, based on the SPM99 function of the same name for SPM99. Note that Michael's version can easily be changed to create Pvalues instead of log10 Pvalues.
function T2nltP(a1,a2) % Write image of Pvalues (spm_nltP_?) for a T image % % FORMAT T2nltP % SPM will ask you which spmT_? file you want to convert to spm_nltP_? % % FORMAT T2nltP(Timg,df) % Timg Filename of T image % df Degrees of freedom % % % As per SPM convention, T images are zero masked, and so zeros will have % Pvalue NaN. % % @(#)T2nltP.m 1.2 T. Nichols 03/07/15 % Modified 04/01/20 by MAM  for SPM2 compatibility if nargin==0 % Ask user for SPM.mat file and specific contrast [SPM,xSPM]=spm_getSPM; % If a 'T' contrast, get degrees of freedom (df) and fname of spmT_? if xSPM.STAT ~= 'T', error('Not a T contrast'); end df=xSPM.df(2); Tnm=xSPM.Vspm.fname; elseif nargin==2 Tnm = a1; df = a2; end Tvol = spm_vol(Tnm); Pvol = Tvol; Pvol.dim(4) = spm_type('float'); Pvol.fname = strrep(Tvol.fname,'spmT','spm_nltP'); if strcmp(Pvol.fname,Tvol.fname) Pvol.fname = fullfile(spm_str_manip(Tvol.fname,'H'), ... ['nltP' spm_str_manip(Tvol.fname,'t')]); end Pvol = spm_create_vol(Pvol); for i=1:Pvol.dim(3), img = spm_slice_vol(Tvol,spm_matrix([0 0 i]),Tvol.dim(1:2),0); img(img==0) = NaN; tmp = find(isfinite(img)); if ~isempty(tmp) % Create map of P values %img(tmp) = (max(eps,1spm_Tcdf(img(tmp),df))); % Create map of log10(P values) img(tmp) = log10(max(eps,1spm_Tcdf(img(tmp),df))); end Pvol = spm_write_plane(Pvol,img,i); end; spm_close_vol(Pvol); Gem 5: Normalizing [x y z]An offlist email reports how to find the point in an normalized image that corresponds to a given unnormalized location. See also Unnormalizing a point. From: John Ashburner <john@fil.ion.ucl.ac.uk> To: Christophe Phillips <c.phillips@ulg.ac.be> Subject: Re: Coordinates transform Date: Wed, 4 Feb 2004 17:26:21 +0000 Hi Christophe, > I've the coordinates [x y z] of a point (actually the location of a > fitted current dipole) in an image 'img1'. This image was normalised > into 'w_img1'. I'd like to have the dipoles coordinates [x y z]_w in > the normalised image... > > Do you have a routine that can do that easily from the 'img1_sn.mat' > file ? The deformations in the sn.mat files map from points in normalised space, to points in unnormalised space. You therefore need to invert them, which is a bit messy. You would use the Deformations toolbox for this (from the Toolbox pulldown). First write out the deformation field from the sn.mat. Then call the Deformations toolbox again, and choose the deformations inversion option. This will be an iy*.img file with three volumes. This little script can then be used. c = [x y z]'; % coordinates in mm (as shown by Display) P = spm_get(1,'iy*.img','Select inverted warp'); P = [repmat(P,3,1) [',1';',2';',3']]; V = spm_vol(P); vx = inv(V(1).mat)*[c ; 1]; % The voxel in the deformation to sample w_coord = [... spm_sample_vol(V(1),vx(1),vx(2),vx(3),1) spm_sample_vol(V(2),vx(1),vx(2),vx(3),1) spm_sample_vol(V(3),vx(1),vx(2),vx(3),1)] I haven't tested it, so there may be things to fix. All the best, John Gem 6: Contrast SE ComputationAn email from Will Penny on how a contrast's standard error is computed. Subject: Re: Beta SE in SPM2? From: Will Penny <wpenny@FIL.ION.UCL.AC.UK> Date: Fri, 27 Feb 2004 11:26:35 +0000 To: SPM@JISCMAIL.AC.UK Tobias, > How do I extract beta SE in SPM2? As far as I can see I can only get > y, Y, beta, and Bcov...have I missed something? If you're referring to the Standard Error or the Standard deviation of the parameter estimates then this isn't stored explicitly. Its computed on the fly when one makes an inference about a contrast. See the following lines (153158) in spm_contrasts: case 'T' %Compute SPM{t} image % cB = spm_get_data(xCon(ic).Vcon,XYZ); l = spm_get_data(VHp,XYZ); VcB = xCon(ic).c'*SPM.xX.Bcov*xCon(ic).c; Z = cB./sqrt(l*VcB); So, if you did a contrast xCon(ic).c'=[1 0 0 0] to test the null hypothesis that the first parameter is zero then cB will be equal to beta1 and sqrt(l*VcB) will be equal to std(beta1)  the standard deviation of the first parameter estimate. Note that l is the residual sum of squares at that voxel which is stored in the image ResMS.img and accessed via the file handle VHp. In this way SPM does'nt have to store Standard Deviations/covariances for every voxel and beta  so saving disk space. But its not that handy for what you want ! Hope this helps, Will. Gem 7: Extracting realignment parametersThe referenced script is here save_parameters.m
Subject: Re: [SPM] realignment parameter From: John Ashburner <john@FIL.ION.UCL.AC.UK> Date: Fri, 23 Apr 2004 11:25:27 +0000 (07:25 EDT) To: SPM@JISCMAIL.AC.UK > I have switched from spm99 to spm2 and am learning new things. > When I realign images interactively with GUI interface, > the rp*.txt file is created. However, the parameter file > is not created  or, I cannot find it , when I realign > with a batch script. > I am sure I left out something, but I don't know it. > Any suggestion will be very appreciated. If you call spm_realign with output (lefthand) arguments, then no rp_*.txt file is saved. You could create a save_parameters.m file, containing: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% function save_parameters(V) fname = [spm_str_manip(prepend(V(1).fname,'rp_'),'s') '.txt']; n = length(V); Q = zeros(n,6); for j=1:n, qq = spm_imatrix(V(j).mat/V(1).mat); Q(j,:) = qq(1:6); end; save(fname,'Q','ascii'); return; %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% and derive the values from your realigned images: P = spm_get(Inf,'*.IMAGE','Select realigned images'); save_parameters(spm_vol(P)) Best regards, John Gem 8: ImCalc ScriptSPM99 Gem 21 is the same (with minor changes). Subject: Re: a script to use ImaCal From: John Ashburner <john@FIL.ION.UCL.AC.UK> Date: Thu, 16 Oct 2003 11:24:17 +0000 (07:24 EDT) To: SPM@JISCMAIL.AC.UK > Brain image for each subject to mask out CSF signal was generated by > using MPR_seg1.img (i1) and MPR_seg2.img (i2) with (i1+i2)>0.5 in > ImaCal.(called brainmpr.img for each subject) > > Then I have more than twohundred maps, which need to mask out > CSF. I think I can use ImaCal again with selecting brainmpr.img (i1) > and FAmap.img (i1), and then calculating (i1.*i2) to generate a new > image named as bFAmap.img. Unfortunately, if I use the ImaCal, it > take so long time to finish all subjects. Could anyone have a script > to generate a multiplication imaging with choosing a brain > image(brainmpr.img, i1) and a map image (FAmap.img, i2) and writing > an output image (bFAmap.img) from i1.*i2? You can do this with a script in Matlab. Something along the lines of the following should do it: P1=spm_get(Inf,'*.IMAGE','Select i1'); P2=spm_get(size(P1,1),'*.IMAGE','Select i2'); for i=1:size(P1,1), P = strvcat(P1(i,:),P2(i,:))); Q = ['brainmpr_' num2str(i) '.img']; f = '(i1+i2)>0.5'; flags = {[],[],[],[]}; Q = spm_imcalc_ui(P,Q,f,flags); end; Note that I have not tested the above script. I'm sure you can fix it if it doesn't work. Best regards, John Gem 9: Masking w/ ImCalcThis is an email from Rik Henson which references John. It addresses the fact that ImCalc defaults to writing out images in 2byte signed integer format, which is can be problematic if you're masking statistic images (which should written with floating point precision).
Subject: Masking with ImCalc From: Rik Henson <r.henson@UCL.AC.UK> Date: Fri, 14 May 2004 08:24:25 +0100 (03:24 EDT) To: SPM@JISCMAIL.AC.UK Several people have asked how to mask SPMs across different analyses. This used to be possible using ImCalc in SPM99 (see Mailbase archive). In SPM2 however, when ImCalc is called from the GUI, it adopts various defaults, which include writing images as "uint16" (rather than "float", which is the normal datatype for T/F imgs). Thanks to John for pointing this out. It is for this reason that the procedure of overwriting spmT/F*imgs using ImCalc does not work from SPM2's GUI. To override this default however, you can simply call ImCalc from the command line instead, setting the datatype to spm_type 'float': spm_imcalc_ui([],[],'i1.*(i2>3.09)',{[],[],'float',0}) The empty 1st and 2nd arguments mean that SPM will prompt you to select the input images and the output filename, as usual. You will of course need to change the third argument to your particular ImCalc equation for evaluation. The 4th argument is a cell array of defaults, which includes the 'float' enforcement. For more info, type "help spm_imcalc_ui". RikSee also SPM2 Gem 8, and SPM99 Gems 3, 16, and 21. Gem 10: Creaging a mask from a XYZ listThis is a "Jan's Gem" from Jan Gläscher...
Subject: Re: [SPM] creating a mask from voxel coordinates From: Jan Gläscher <glaescher@UKE.UNIHAMBURG.DE> Date: Tue, 15 Mar 2005 12:24:27 +0100 To: SPM@JISCMAIL.AC.UK Dear Susana, you can try the following recipe. It might not be the easiest way, but it should work. Suppose your n MNI coordinates are saved in a 3xn matrix called mni. (This is essential (not the name, but the format of 3xn), otherwise the steps below won't work). 1. Create an spm_vol handle to the image, that you determined the coordinates from Vin = spm_vol(spm_get(1,'*.img','Select image')); 2. Read the information in the image. (The data are not needed, this is done purely for the purpose of setting up a matrix of voxel coordinates. [Y,XYZ] = spm_read_vols(Vin); 3. Setup a matrix of zeros in the dimensions of the input image mask = zeros(Vin.dim(1:3)); 4. Now loop over all voxels in your mni variable and set the corresponding location in the mask matrix to 1: for v = 1:size(mni,2) mask(find(XYZ(1,:)==mni(1,v)&XYZ(2,:)==mni(2,v)&XYZ(3,:)==mni(3,v))) = 1; end 5. Setup an spm_vol output file handle and change the filename Vout = Vin; Vout.fname = '/path/to/the/directory/mask.img'; 6. Finally, write the new mask to the output file. spm_write_vol(Vout,mask); Cheers, Jan Gem 11: UnnormalizationThis script of John's will find the corresponding coordinate in unnormalised image: get_orig_coord2.m
Gem 12: fMRI Analysis thresholdThis is an update of Gem12 for SPM99, originally by Stefan Kiebel.
> Is it possible to instruct spm99 to search all voxels within a given > mask image rather than all above a fixed or a %mean threshold? Yes, with SPM2 it's possible to use several masking options. To recap, there are 3 sorts of masks used in SPM2: 1. an analysis threshold 2. implicit masking 3. explicit masking 1: One can set this threshold for each image to Inf to switch off this threshold. 2: If the image allows this, NaN at a voxel position masks this voxel from the statistics, otherwise the mask value is zero (and the user can choose, whether implicit masking should be used at all). 3: Use mask image file(s), where NaN (when image format allows this) or a nonpositive value masks a voxel. On top of this, SPM automatically removes any voxels with constant values over time. So what you want is an analysis, where one only applies an explicit mask. In SPM2 for PET, you can do this by going for the Full Monty and choosing Inf for the implicit mask and no 0thresholding. Specify one or more mask images. (You could also define a new model structure, controlling the way SPM for PET asks questions). With fMRI data/models, SPM2 is fully capable of doing explicit masking, but the user interface for fMRI doesn't ask for it. One way to do this type of masking anyway is to change the SPM.mat file *after* you specify your model, but *before* clicking 'Estimate'. Specifically: 1. Load the SPM.mat file, load SPM set the SPM.xM.TH values all to Inf, SPM.xM.TH = Inf*SPM.xM.TH; and, in case that you have an image format not allowing NaNs, set SPM.xM.I to 0 SPM.xM.I = 0; 2. If using a mask image, set SPM.xM.VM to a vector of structures, where each structure element is the output of spm_vol. For instance: SPM.xM.VM = spm_vol('Maskimage'); 3. Finally, save by save SPM SPM Gem 13: Corrected cluster size thresholdThis is a script that will tell you the corrected cluster size threshold for given clusterdefining threshold: CorrClusTh.m The usage is pretty self explanatory: Find the corrected cluster size threshold for a given alpha function [k,Pc] =CorrClusTh(SPM,u,alpha,guess) SPM  SPM data structure u  Cluster defining threshold If less than zero, u is taken to be uncorrected Pvalue alpha  FWEcorrected level (defaults to 0.05) guess  Set to NaN to use a NewtonRhapson search (default) Or provide a explicit list (e.g. 1:1000) of cluster sizes to search over. If guess is a (nonNaN) scalar nothing happens, except the the corrected Pvalue of guess is printed. Finds the corrected cluster size (spatial extent) threshold for a given cluster defining threshold u and FWEcorrected level alpha. To find the 0.05 (default alpha) corrected cluster size threshold for a 0.01 clusterdefining threshold: >> load SPM >> CorrClusTh(SPM,0.01) For a clusterdefining threshold of 2.4671 the level 0.05 corrected cluster size threshold is 7860 and has size (corrected Pvalue) 0.0499926Notice that, due to the discreteness of cluster sizes you cannot get an exact 0.05 threshold. The function uses an automated search which may sometimes fail. If you specify a 4th argument you can manually specify the cluster sizes to search over: >> CorrClusTh(SPM,0.01,0.05,6000:7000) WARNING: Within the range of cluster sizes searched (6000...7000) a corrected Pvalue <= alpha was not found (smallest P: 0.0819589) Try increasing the range or an automatic search.Ooops... bad range. Lastly, you can use it as a look up for a specific cluster size threshold. For example, how much over the 0.05 level would a cluster size of 7859 be? >> CorrClusTh(SPM,0.01,0.05,7859) For a clusterdefining threshold of 2.4671 a cluster size threshold of 7859 has corrected Pvalue 0.050021Just a pinch!
