New Page 1

But, if you are one of the lucky ones to have Matlab 7 and you are using the GUI, the interface looks like this:

Using Ortho

Ortho works on Analyze format files only (.img). Please note that ORTHO disregards the .mat files that are generated by SPM. It does use the header information like origins, voxel sizes and Scaling Factor.

Now that ORTHO is running, its main functions are to

- display the images in orthogonal views,
- overlay statistical maps on top of them and
- extract time series from selected voxels. You can easily select the type or ROI you want.
- show you pixel values of the anatomical and the statistical images.

ORTHO can also (if you check the options)

- average events from a time series,
- show you a movie of the image in orthogonal sections.
- filter the data,
- display the temporal frequency content. The user is allowed to navigate the images interactively, and ORTHO updates the time series display accordingly.
- save the time series data into ASCII files.
- ortho is VERY easy to run as a batch script. Type " help ortho2005 " at the matlab command prompt for details.

Ortho's interface is designed so that when you press the GO button, it displays as much as it can with whatever fields are filled in by the user, (... but some combinations are not implemented yet). ORTHO shows you the images and it updates the display interactively as you select voxels by clicking on them. Information about the pixel (or pixels) gets displayed in the matlab command window. When you RIGHT CLICK, all that information gets put into ASCII files.

The details of the guts of the program and how it works are below, in the description for the ortho2005 function, but here is a brief description:

1. Extracting and Looking at a time series:

If you fill in the "time series" only, you will get a plot of the time series at whatever voxel you click on. To fill in the "Time Series" field, select one of the images in the time series. ORTHO will assume that they all are named the same except for the numbers at the end of the name. eg-

vol_e2343_10_12_03_0001.img
vol_e2343_10_12_03_0002.img
...etc

If you have a single 4D file, ORTHO will recognize it and read it in as well. If you fill in the "anatomical" image only, you will get a display of the image you select along with a nice histogram of the pixels values.

2. Stuff you can do to the time series:

You can also add detrending (3rd order polynomial) and gaussian filtering to the time series by checking the appropriate box. The filter parameters are hard-coded. They should be user defined, but that's not implemented yet... sorry... it's easy to hack if you have the inclination, though...

If you click with the RIGHT mouse button, the extracted waveforms get stored as ASCII files for easy access outside of matlab.

You can display the FFT's magnitude and phase in a separate window by checking the "FFT" box (near the bottom)

If you provide a set of onset times, and a time window, you will get trial averages over the desired widow of time. Note - ortho looks at time in units of scans - does not know your sampling rate or TR. It also displays a nice image of a matrix made up of the individual events that you are averaging. This is really handy because you can notice changes in the events from trial to trial, things like habituation or drifts in HRF parameters, errors in the timing of the experiment...

You can also look at a movie of the time series through the selected location be checking the "Movie" checkbox

3. Ovelaying a Statistical Map:

If you fill in the "anatomical" and "stats map 1", you will get a display of the anatomical image with the statistical map overlayed on it. You can select the threshold by filliing in the threshold value field. These images must be coregistered previously. They can have different resolutions, but they need to be in the same orientation with the same origin. Remember that ORTHO does not use the .mat files generated by SPM's coregistration so it doesn't apply the transformations on the fly the way SPM does.

You can also display two statistical maps to find overlapping voxels by filling in "stats map 2" as well. Overlapping pixels in the statistical maps are shown in green.

You can change the threshold interactively by filling in a new value in the interface and clicking on a pixel to update the display.

4. Selecting ROI types:

If you fill in the "Anatomical", "Stats Maps" and "Time Series", you can also select a specfic set of voxels to extract the information from. The values in those voxels get averaged together. You can choose what kind of ROI to use in the upper right side of the interface:

Cube: means that you get the voxel you click on plus the number of neighbors in each direction specified in the field labeled "ROI size". The default is cube with zero neighbors.
Thresholded Sphere: means a sphere with the radius in mm specified in the field labeled ROI size.
Mask File: means an Analyze format image in which the voxels of interest have value 1. All others have value of zero.
Voxel File means that the ROI consists of a list of voxels specified in an ASCII file, which you have to select by clicking the "Mask File / Vox. File" Button, or just typing in the file name in the field below that button. About the aforementioned voxel file, it needs to be an ascii (text) file that looks like this example:

12 43 45
12 44 46
23 45 89

...etc.

Those coordinates are in voxel units and they are relative to the first voxel in the file - the one in the lower left corner, NOT the orgin!

function result = ortho2005(args,varargin)

(c) Luis Hernandez-Garcia at University of Michigan
report bugs to: hernan@umich.edu

last edits: July 23,2005

This is a program to visualize overlays of FMRI data, extract time
series and do some quick analyses on those time series like FFT, gaussian
filters, event averaging, detrending.
Images should be in Analyze (AVW) format

USAGE:

This program will do as much as it can with the information provided.
ie - If you give onset times, it will assume you want event averages,
You can run this program in a couple of ways:
The arguments to this function can go in either as a structure like this:
(fell free to copy and paste the following in order to run the program. it's what I do)

args.ROIsize = 0;
args.ROItype = 'cube';
args.threshold = 0;
args.onsets = [];
args.window = 10;
args.spm_file = [];
args.anat_file = [];
args.tseries_path = [];
args.tseries_file = [];
args.tseries_file2 = [];
args.doDetrend = 0;
args.doGfilter = 0;
args.doFFT = 0;
args.ignore_origin = 0;
args.wscale = [];
args.interact = 1;
args.xyz=[];
args.mask_file = [];
args.output_name = 'Ortho';
args.voxFile = [];
args.doMovie = 0;

then you call

ortho2005(args)

OR as variable arguments when you just want to change a couple of the
defaults. The general syntax is

ortho2005([],'argument1', value1, 'argument2', value2, ....)

for example:

ortho2005( [], 'anat_file', '/usr/data/vol_0001.img', 'ROIsize', 1);

INPUTS (arguments).
(their default values are in the above struct)

ROIsize : this is the 'radius' of the ROI if it's a sphere
or the number of neighbors to consider if it's a cubw.
it's in mm for the sphere case, and voxels for the cube case

ROItype : what type of ROI you'll useyou can choose
'cube' : average the neighbors in each direction
'voxfile': average the values in the voxels specified in an ASCII file
'thr_sphere': average the voxels in a sphere, but only those whose
statistics are above threshold
'mask' : average the voxels that are non-zero in a mask img file

threshold : statistic theshold for display of the overlay and for ROI
averaging.

voxFile : an ASCI file containing three columns specifying which voxels
to extract time series from. Note- uses scan units and ignores the
origin by default.

mask_file = binary mask image to use if you want to choose your ROIs that
way

onsets : a vector of onset times, specified in scan units for window averaging;

window : The window of time to average after ach onset (peristimulus interval)
also in units of scans;

spm_file : The statistical map to overlay on the orthogonal views;

anat_file : The anatomical image file to overlay;

tseries_path : this doesn't do aquat right now

tseries_file : one of the files in the time series.
If the data are 4D, ortho2005 should recognize it and read it in= [];

tseries_file2 : this doesn't do squat yet, either = [];

doDetrend : Detrend the data by fitting and removing a 4th order polynomial.
usually works like a charm!;

doGfilter: Filter the data with a simple Gaussian filter in time.
kernel width (SD) is hard wired to 4 scans ;

doFFT : show the FFT magnitude and phase of the time series in a separate window;

doMovie : show a movie loop of the time series. only the time series
image is required

ignore_origin : ignore the origin information from SPM. This can be tricky;

wscale : window level scaling for display of the anatomical images
if you want to do it manually;

interact : allow the user to interactively pick points from the image, or just
do one set of coordinates and exit the program. When interactive,
you exit the program by clicking to the left of the images, or by
hitting the Z key.

xyz : voxel coordinates to analyse when not running interactively.

output_name : a prefix to put on all the files generated by the program ('Ortho');

Outputs from ortho2005

you get some very nice displays of whatever you chose. if you click the
right mouse button instead of the left one, you get these ASCII files:

*voxels.dat : the voxels that data was extracted from
*data.dat: the raw time series data from theose voxels
*avg.dat : the means and standard deviation of the events

function Tmapper(rootname)

Luis Hernandez-Garcia at U Michigan
12-17-2003

Tmap calculator for SPM images avoiding the mask issues in SPM99

this function takes a set of images with a common rootname
and calculates:

df.img:
the number of available measurements at each pixel
(not NaN's or Infs): this is the degrees of freedom
at that pixel
mean.img:
the mean of the pixels excluding NaNs and Infs
var.img:
the variance of the pixels exluding NaNs and Infs
tscore.img:
the t score wherever possible, taking into account the
available number of measurements.
If there is only one measurement, we call it a NaN.
(not much of a t-test if there is only one measurement.
pval.img
the corresponding p values to the tscores using the
degrees of freedom calculated earlier

10lnP:
this one is just -10*ln(p) for bettern display purposes.

USAGE example: Tmapper('rfx_')

(when doing RFX, it's useful to put links to the individual
contrast images in the same directroty)

warning: it's slow!

function [m,s]=event_avg(data,onsets, duration, sampRatio)

data: is a single ROW vector with the time series
onsets: is a vector of the onset times (in scan units)
window: is the number of scans to average in each event
sampRatio: is the interpolation factor if the window, or the
onset times are non-integer.
result : is a matrix containing the average single event, and their
standard deviation. The units are % change realtive to the
mean signal before detrending

the first scan is scan #1, not #0

function [func_hat, var_hat] = hrf_deconv(data, onsets, length)

deconvolves the hrf from a time series, given:

data - (of course)this needs to be a column
onsets - the onsets of the events
length - of the HRF to estimate desired

the function uses a linear regression approach to
deconvolve the function.

note - it also adds another regressor to the matrix in order to
estimate the DC offset. This is not reported in the final estimate

it returns:
fun - the resulting HRF function
v - the variance estimate for the function

data = data + 100;

function hrf = make_hrf(delta,tau, npoints)

Generates a gamma variate function for the hemodynamic response function.
points is the number of points to be included in the function.
(ie - the length of the response to be calculated)
Normalized so that it peaks at 1

delta - delay in the function
tau - decay/uptake constant
npoints - number of points to generate

NOTE: must be consistent in units!

function result = mydetrend( data [,saveCoeffs])

this function fits and subtracts a third order polynomial
from the data.

function [fig1, fig2, fig3] = ov(h,d,x,y,z,roi)

function ovm(threshold,spm_file, spm_file2, anat_file )

this function overlays two activation maps on top of an anatomical
image and shows the overlaps in green at the specified threshold

the display is in orthogonal sections and it's interactive

The program writes a file called "overlaps.dat" with the xyz
voxel coordinates of the overlapping voxels

function power_img = spm_power(alpha, df, error)

computes the power of a t-test accross
several images of every voxel.

Luis Hernandez
University of Michigan
Last Edit 1-27-2000

The null hypothesis is that each images has a value equal
to the mean value of all the images in the group.
The alternative hypothesis is that they are not (double sided test)
a p-value less than alpha means that they are different.

Arguments and defaults:
alpha: significance level (0.05)
df : degrees of freedom (number of images * average number of Ressels)
error: Numbber of standard deviations of error to assume, when
calculating the power (1)
files.txt: a text file containing the filenames (with path) of
of the images to test

Output:
power.img
p-value.img

function [Spower N_min]= Spower_finder(x, alpha, bf, effect, Spower_threshold)

computes the Number of measurements
to achieve a given Spower for a t-test accross
several images of every voxel.

Luis Hernandez
University of Michigan
Last Edit 2 - 18 -2000

The null hypothesis is that each images has a value equal
to the mean value of all the images in the group.
The alternative hypothesis is that they are not (double sided test)
a p-value less than alpha means that they are different.

This function computes the probability of being right if we reject the
null hypothesis of being equal, based on a given effect size.

Arguments and defaults:
x: 2D data array. rows = pixels, cols = subjects
alpha: significance level (0.05)
bf : Bonferroni correction factor.
effect: Effect size (%) to be assumed, when calculating the Spower (5%)
Spower_threshold: Desired Spower level

function N = power_ranger(alpha, bf, effect_size, power_threshold)

computes the power of a t-test accross
several images of every voxel.

Luis Hernandez
University of Michigan
Last Edit 1 - 25 -2005

The null hypothesis is that each images has a value equal
to the mean value of all the images in the group.
The alternative hypothesis is that they are not (double sided test)
a p-value less than alpha means that they are different.

USAGE: the program will put up a file selection box.
select the images of the activation maps you have and
hit the CANCEL button once you have selected all of them
The program will compute the power of your test with your
current number of samples and the number of samples needed
to achive the desired power. This is done pixel by pixel,
so what you get is two images.

Arguments and defaults:
alpha: significance level (default ... 0.05)
bf : Bonferroni correction factor (default ... 1).
effect_size: what we guess that the Effect's value is.
power_threshold: the desired power level (from 0 to 1) for which the program
will calculate the minimum number of subjects (default ...0.8)
Output:
power.img
N.img

function N = power_ranger_jr(x, alpha, bf, error, power_threshold)

computes the Number of measurements
to achieve a given power for a t-test accross
several images of every voxel.

Luis Hernandez
University of Michigan
Last Edit 2 - 15 -2000

The null hypothesis is that each images has a value equal
to the mean value of all the images in the group.
The alternative hypothesis is that they are not (double sided test)
a p-value less than alpha means that they are different.

This function computes the probability of being right if we reject the
null hypothesis of being equal, based on a given effect size.

Arguments and defaults:
x: data array
alpha: significance level (0.05)
bf : Bonferroni correction factor.
error: Effect size to be assumed, when calculating the power (5%)
power_threshold: Desired power level

function hdr = read_hdr(name)
Luis hernandez
last edit 12-16-2004

Loads the analyze format header file from a file 'name'

data = read_img(hdr, name)
or
data = read_img(name)

Luis hernandez
last edit 12-16-2004

Loads the data from an analyze format file 'name' containing mutislice image data
if the file contains multiple TIME points,
this function returns a two dimensional array of data
(each row is an image , each column is a time series).

image_data = read_img2(hdr, name)

Luis hernandez
last edit 6-29-2000

Loads the data from an analyze format file 'name' containing mutislice image data
hdr: is a header structure (use read_hdr())
name: file name (.img)
The function returns a three dimensional array

data = read_img_data(hdr, name)

Luis hernandez
last edit 4-5-98

Loads the data from an analyze format file 'name' containing mutislice image data
this function returns a one dimensional array of data (row vector).

series_data = read_img_series(root)

Luis hernandez
last edit 6/26/2004

hdr header information
root root name of the image files

ouput: a matrix with pixels in each column and
rows means position in time

similar to read_img, but used when there are multiple files
for the time series

No help comments found in set_func_colors.m.

spmJr (path, file_root, reference_vector)

function result = timeplot4(path,file, [ x,y,z] )

Returns the intensity of the voxels in the points determined
x y z are the coordinates of a set of voxels to be averaged
the data comes back as a row vector. eg -
[ x1 y1 z1 ;
x2 y2 z2 ;
x3 y3 z3 ]

function write_hdr(name,hdr)
Luis hernandez
last edit 1-7-98

Writes the analyze format header file from a file 'name'

function write_img_data(name, data, hdr)

Luis hernandez
last edit 4-24-2004

Writes the data to an analyze format file 'name' containing mutislice image data
this also handles a timeseries in one file (ie -each image is a row )

function write_img_data(name, data, hdr)

Writes the data to an analyze format file 'name' containing mutislice image data

function tcourse = xtract(hdr, data, x, y, z)

here the data is a 2D matrix with all the time points in rows
x,y,z are vectors defining a cubic ROI

matlab scripts	shell scripts	C/Linux binaries	C/Linux source code
ORTHO 2005 An interactive Matlab GUI tool for time series extraction , visualization and analysis. (latest version 12/2005 - works a lot better) User's Manual: Installation 1. Download the .tar file below (LuisTools.tar) and expand it in a directory of choice. tar xvf LuisTools.tar 2. Add that directory to your Matlab path Starting ORTHO Run Matlab 7 and execute the command: ortho (The GUI portion does not work with prior versions of Matlab, but you can still run ortho as a command line tool, though!) If you want to run ortho without the GUI, take a look at the file ortho_nogui.m . You can edit that file by filling in the fields that you need, and use it as a "fake GUI". Once you have filled it in, all you have to do is execute it. Similarly, If you want to use the programs in batch mode to run through all your subjects, edit the file ortho_batch.m and execute it. But, if you are one of the lucky ones to have Matlab 7 and you are using the GUI, the interface looks like this: Using Ortho Ortho works on Analyze format files only (.img). Please note that ORTHO disregards the .mat files that are generated by SPM. It does use the header information like origins, voxel sizes and Scaling Factor. Now that ORTHO is running, its main functions are to - display the images in orthogonal views, - overlay statistical maps on top of them and - extract time series from selected voxels. You can easily select the type or ROI you want. - show you pixel values of the anatomical and the statistical images. ORTHO can also (if you check the options) - average events from a time series, - show you a movie of the image in orthogonal sections. - filter the data, - display the temporal frequency content. The user is allowed to navigate the images interactively, and ORTHO updates the time series display accordingly. - save the time series data into ASCII files. - ortho is VERY easy to run as a batch script. Type " help ortho2005 " at the matlab command prompt for details. Ortho's interface is designed so that when you press the GO button, it displays as much as it can with whatever fields are filled in by the user, (... but some combinations are not implemented yet). ORTHO shows you the images and it updates the display interactively as you select voxels by clicking on them. Information about the pixel (or pixels) gets displayed in the matlab command window. When you RIGHT CLICK, all that information gets put into ASCII files. The details of the guts of the program and how it works are below, in the description for the ortho2005 function, but here is a brief description: 1. Extracting and Looking at a time series: If you fill in the "time series" only, you will get a plot of the time series at whatever voxel you click on. To fill in the "Time Series" field, select one of the images in the time series. ORTHO will assume that they all are named the same except for the numbers at the end of the name. eg- vol_e2343_10_12_03_0001.img vol_e2343_10_12_03_0002.img ...etc If you have a single 4D file, ORTHO will recognize it and read it in as well. If you fill in the "anatomical" image only, you will get a display of the image you select along with a nice histogram of the pixels values. 2. Stuff you can do to the time series: You can also add detrending (3rd order polynomial) and gaussian filtering to the time series by checking the appropriate box. The filter parameters are hard-coded. They should be user defined, but that's not implemented yet... sorry... it's easy to hack if you have the inclination, though... If you click with the RIGHT mouse button, the extracted waveforms get stored as ASCII files for easy access outside of matlab. You can display the FFT's magnitude and phase in a separate window by checking the "FFT" box (near the bottom) If you provide a set of onset times, and a time window, you will get trial averages over the desired widow of time. Note - ortho looks at time in units of scans - does not know your sampling rate or TR. It also displays a nice image of a matrix made up of the individual events that you are averaging. This is really handy because you can notice changes in the events from trial to trial, things like habituation or drifts in HRF parameters, errors in the timing of the experiment... You can also look at a movie of the time series through the selected location be checking the "Movie" checkbox 3. Ovelaying a Statistical Map: If you fill in the "anatomical" and "stats map 1", you will get a display of the anatomical image with the statistical map overlayed on it. You can select the threshold by filliing in the threshold value field. These images must be coregistered previously. They can have different resolutions, but they need to be in the same orientation with the same origin. Remember that ORTHO does not use the .mat files generated by SPM's coregistration so it doesn't apply the transformations on the fly the way SPM does. You can also display two statistical maps to find overlapping voxels by filling in "stats map 2" as well. Overlapping pixels in the statistical maps are shown in green. You can change the threshold interactively by filling in a new value in the interface and clicking on a pixel to update the display. 4. Selecting ROI types: If you fill in the "Anatomical", "Stats Maps" and "Time Series", you can also select a specfic set of voxels to extract the information from. The values in those voxels get averaged together. You can choose what kind of ROI to use in the upper right side of the interface: Cube: means that you get the voxel you click on plus the number of neighbors in each direction specified in the field labeled "ROI size". The default is cube with zero neighbors. Thresholded Sphere: means a sphere with the radius in mm specified in the field labeled ROI size. Mask File: means an Analyze format image in which the voxels of interest have value 1. All others have value of zero. Voxel File means that the ROI consists of a list of voxels specified in an ASCII file, which you have to select by clicking the "Mask File / Vox. File" Button, or just typing in the file name in the field below that button. About the aforementioned voxel file, it needs to be an ascii (text) file that looks like this example: 12 43 45 12 44 46 23 45 89 ...etc. Those coordinates are in voxel units and they are relative to the first voxel in the file - the one in the lower left corner, NOT the orgin! Example: Here is a screen shot of what the output typically looks like: ORTHO is still evolving, and so is this page. Please stay tuned .....