Class constructor for marsy: the MarsBaR data object
FORMAT [o,others] = marsy(params, region_stuff, summary_stuff)
Synopsis:
% Some example data
Y = rand(100, 10);
% Use data as time courese from 10 regions
m_Y = marsy(Y);
% Use data as 10 samples (voxels from one region)
m_Y = marsy({Y}, 'region_1', 'mean');
% Extract data for ROI 'my_roi', from list (string array) of images P
m_Y = get_marsy(my_roi, P, 'mean'); % method for maroi (region) object
Inputs
params - can be: structure, either:
containing MarsBaR data structure or
containing fields for marsy object, which should include
'y_struct', containing data structure
OR: filename, which loads to give structure as above
OR: 2D matrix, containing summary data (Y) only (see below)
OR: cell array of 2D matrices, one per region
region_stuff - (optional) cell array of names for regions
or array of structures containing information for
regions
or cell array of structures with information
Structure can have fields;
name - string identifying region
descrip - longer description of region
Y - matrix of samples (voxel data) for this
region, size N by S1 for region 1, N by S2 for
region 2 etc.
weights - weighting vector, one value for each sample
1..S1 (for region 1) etc.
Can be empty, so each sample has weight 1.
info - structure containing any other fields of
interest
vXYZ - any voxel coordinates in X Y Z dimension
(3 by S1 for region 1 etc).
mat - a 4x4 transformation matrix giving coordinates
in mm from voxel coordinates in vXYZ
summary_stuff - (optional) summary function to summarize data (string)
or structure containing information for summary data
Structure can have fields;
sumfunc - the summary function used to summarize the
samples (voxels) per time point; a string,
which is usually one of 'mean', 'median',
'wtmean', 'eigen1', or 'unknown'
descrip - text field describing the origin of the data
info - a structure with fields defining any other
interesting information about the region
block_rows - optional cell array, specifying the rows in
the data that correspond to a particular
session or subject (see below). If absent, the
data is assumed to come from a single session
or subject.
Any data in region_stuff, summary info will overwrite region or summary
information passed in the first argument
Outputs
o - marsy object
others - any unrecognized fields from params, for processing by
(as yet non-existent) children
marsy is an object to contain MarsBaR data structures.
The marsy object contains data for one or more ROIs. It offers two
possible views of the data; the SUMMARY view, which gives one summary time
course for each ROI, and the REGION view, which gives all the timecourses
available from the ROI. For example, most ROIs contain more than one
voxel, and, in the REGION view, there will be one time course for each
voxel. In the SUMMARY view, all the data for a single region, for each
timepoint, are combined with a summary function, to give one
representative value per time point, and therefore a single time course
for the whole ROI. The most common summary function would be the mean of
all the samples (voxels) at each time point, but there are others (see
below).
At its simplest, the marsy object can just contain a single time-course
for a single ROI. In this case the summary and region view will be
the same.
It can also contain data for more than one ROI, and more than one
time course per region. In this case the object needs to know how to
summarize the timecourses for the ROIs to give the summary view.
Let's call the number of regions R
All regions in the structure have data with the same number of time points
Let's call the number of time points N
For each region there may be many samples at each time point.
For example, there is usually one sample from each voxel in the ROI.
Let's call the number of samples (voxels) per time point S1..SR for
regions 1..R.
Thus, the summary view will give an N by R matrix, with one row for
each ROI. The region view, for (say) region 2, will return all the
samples for ROI 2, an N by S2 matrix.
The regions may also be associated with names, for interpreting output and
to help remember where the data has come from. They may also (optionally)
be associated with a longer text description ('descrip'), and any fields
you the user think may be useful (contained in 'info').
You can also (optionally) set text description and info data for the
whole object, for examnple specifying where (all) the data was
extraxcted from.
The data can come from several sessions or subjects. Optionally, this
can be specified with the summary data field 'block_rows', specifying
which rows in the data correspond to which session or subject
The object contains a data structure of a particular format, listed in
the programmer's help for this function. Please avoid using this
structure directly, as this format may change at any time. Instead,
please use the public methods listed below
Methods
verbose - get/set whether reporting is verbose or not (1 or 0)
summary_data - gets (N by R) summary matrix Y
summary_descrip - gets/sets description of object
summary_stuff - gets/sets information field of object
resummarize - recalculates summary data if possible
is_summarized - returns 1 if data has been summarized already
can_summarize - returns 1 if data can be suumarized without error
sumfunc - gets/sets summary function to summarize data
block_rows - gets/sets information on rows corresponding to
sessions/subjects
n_regions - gets number of regions (R above)
n_time_points - gets number of time points (N above)
ui_plot - a variety of plots of the data to SPM interface
save_struct - saves y_struct to disk as structure
region - returns region structure, filled with defaults as necessary
region_data - gets region sample (voxel) data as cell array; returns
all regions if no region number specificed, or one cell
per region if region numbers are specified
region_weights - as above, but for region weighting vector (see above)
region_name - gets cell array of region names as 1 by R cell array
(if no region number is specified) or single cell string
if a single region is specified
region_descrip - gets cell array of descriptions of specified region
region_stuff - gets cell array of info field of specified region
xyz - gets voxel or mm XYZ coordinates of given region
join - accepts several marsy objects, and merges into one (if
possible)
split - splits object into array of objects, with one element
for each region
Other methods (to avoid)
y_struct - sets or gets data structure
$Id$
0001 function [o,others] = marsy(params, region_stuff, summary_stuff) 0002 % Class constructor for marsy: the MarsBaR data object 0003 % FORMAT [o,others] = marsy(params, region_stuff, summary_stuff) 0004 % 0005 % Synopsis: 0006 % % Some example data 0007 % Y = rand(100, 10); 0008 % 0009 % % Use data as time courese from 10 regions 0010 % m_Y = marsy(Y); 0011 % 0012 % % Use data as 10 samples (voxels from one region) 0013 % m_Y = marsy({Y}, 'region_1', 'mean'); 0014 % 0015 % % Extract data for ROI 'my_roi', from list (string array) of images P 0016 % m_Y = get_marsy(my_roi, P, 'mean'); % method for maroi (region) object 0017 % 0018 % Inputs 0019 % params - can be: structure, either: 0020 % containing MarsBaR data structure or 0021 % containing fields for marsy object, which should include 0022 % 'y_struct', containing data structure 0023 % OR: filename, which loads to give structure as above 0024 % OR: 2D matrix, containing summary data (Y) only (see below) 0025 % OR: cell array of 2D matrices, one per region 0026 % 0027 % region_stuff - (optional) cell array of names for regions 0028 % or array of structures containing information for 0029 % regions 0030 % or cell array of structures with information 0031 % Structure can have fields; 0032 % name - string identifying region 0033 % descrip - longer description of region 0034 % Y - matrix of samples (voxel data) for this 0035 % region, size N by S1 for region 1, N by S2 for 0036 % region 2 etc. 0037 % weights - weighting vector, one value for each sample 0038 % 1..S1 (for region 1) etc. 0039 % Can be empty, so each sample has weight 1. 0040 % info - structure containing any other fields of 0041 % interest 0042 % vXYZ - any voxel coordinates in X Y Z dimension 0043 % (3 by S1 for region 1 etc). 0044 % mat - a 4x4 transformation matrix giving coordinates 0045 % in mm from voxel coordinates in vXYZ 0046 % 0047 % summary_stuff - (optional) summary function to summarize data (string) 0048 % or structure containing information for summary data 0049 % Structure can have fields; 0050 % sumfunc - the summary function used to summarize the 0051 % samples (voxels) per time point; a string, 0052 % which is usually one of 'mean', 'median', 0053 % 'wtmean', 'eigen1', or 'unknown' 0054 % descrip - text field describing the origin of the data 0055 % info - a structure with fields defining any other 0056 % interesting information about the region 0057 % block_rows - optional cell array, specifying the rows in 0058 % the data that correspond to a particular 0059 % session or subject (see below). If absent, the 0060 % data is assumed to come from a single session 0061 % or subject. 0062 % 0063 % Any data in region_stuff, summary info will overwrite region or summary 0064 % information passed in the first argument 0065 % 0066 % Outputs 0067 % o - marsy object 0068 % others - any unrecognized fields from params, for processing by 0069 % (as yet non-existent) children 0070 % 0071 % marsy is an object to contain MarsBaR data structures. 0072 % 0073 % The marsy object contains data for one or more ROIs. It offers two 0074 % possible views of the data; the SUMMARY view, which gives one summary time 0075 % course for each ROI, and the REGION view, which gives all the timecourses 0076 % available from the ROI. For example, most ROIs contain more than one 0077 % voxel, and, in the REGION view, there will be one time course for each 0078 % voxel. In the SUMMARY view, all the data for a single region, for each 0079 % timepoint, are combined with a summary function, to give one 0080 % representative value per time point, and therefore a single time course 0081 % for the whole ROI. The most common summary function would be the mean of 0082 % all the samples (voxels) at each time point, but there are others (see 0083 % below). 0084 % 0085 % At its simplest, the marsy object can just contain a single time-course 0086 % for a single ROI. In this case the summary and region view will be 0087 % the same. 0088 % 0089 % It can also contain data for more than one ROI, and more than one 0090 % time course per region. In this case the object needs to know how to 0091 % summarize the timecourses for the ROIs to give the summary view. 0092 % 0093 % Let's call the number of regions R 0094 % All regions in the structure have data with the same number of time points 0095 % Let's call the number of time points N 0096 % For each region there may be many samples at each time point. 0097 % For example, there is usually one sample from each voxel in the ROI. 0098 % Let's call the number of samples (voxels) per time point S1..SR for 0099 % regions 1..R. 0100 % 0101 % Thus, the summary view will give an N by R matrix, with one row for 0102 % each ROI. The region view, for (say) region 2, will return all the 0103 % samples for ROI 2, an N by S2 matrix. 0104 % 0105 % The regions may also be associated with names, for interpreting output and 0106 % to help remember where the data has come from. They may also (optionally) 0107 % be associated with a longer text description ('descrip'), and any fields 0108 % you the user think may be useful (contained in 'info'). 0109 % 0110 % You can also (optionally) set text description and info data for the 0111 % whole object, for examnple specifying where (all) the data was 0112 % extraxcted from. 0113 % 0114 % The data can come from several sessions or subjects. Optionally, this 0115 % can be specified with the summary data field 'block_rows', specifying 0116 % which rows in the data correspond to which session or subject 0117 % 0118 % The object contains a data structure of a particular format, listed in 0119 % the programmer's help for this function. Please avoid using this 0120 % structure directly, as this format may change at any time. Instead, 0121 % please use the public methods listed below 0122 % 0123 % Methods 0124 % verbose - get/set whether reporting is verbose or not (1 or 0) 0125 % summary_data - gets (N by R) summary matrix Y 0126 % summary_descrip - gets/sets description of object 0127 % summary_stuff - gets/sets information field of object 0128 % resummarize - recalculates summary data if possible 0129 % is_summarized - returns 1 if data has been summarized already 0130 % can_summarize - returns 1 if data can be suumarized without error 0131 % sumfunc - gets/sets summary function to summarize data 0132 % block_rows - gets/sets information on rows corresponding to 0133 % sessions/subjects 0134 % n_regions - gets number of regions (R above) 0135 % n_time_points - gets number of time points (N above) 0136 % ui_plot - a variety of plots of the data to SPM interface 0137 % save_struct - saves y_struct to disk as structure 0138 % 0139 % region - returns region structure, filled with defaults as necessary 0140 % region_data - gets region sample (voxel) data as cell array; returns 0141 % all regions if no region number specificed, or one cell 0142 % per region if region numbers are specified 0143 % region_weights - as above, but for region weighting vector (see above) 0144 % region_name - gets cell array of region names as 1 by R cell array 0145 % (if no region number is specified) or single cell string 0146 % if a single region is specified 0147 % region_descrip - gets cell array of descriptions of specified region 0148 % region_stuff - gets cell array of info field of specified region 0149 % xyz - gets voxel or mm XYZ coordinates of given region 0150 % join - accepts several marsy objects, and merges into one (if 0151 % possible) 0152 % split - splits object into array of objects, with one element 0153 % for each region 0154 % 0155 % Other methods (to avoid) 0156 % y_struct - sets or gets data structure 0157 % 0158 % $Id$ 0159 0160 % Programmer's help 0161 % 0162 % Please see the caveats in the main help about using the object 0163 % structure to access the object data. 0164 % 0165 % Fields 0166 % ------ 0167 % 0168 % y_struct - structure containing MarsBaR data structure 0169 % verbose - flag for verbose messages while working 0170 % 0171 % The MarsBaR data structure 0172 % -------------------------- 0173 % 0174 % The data structure contains fields: 0175 % Y - matrix of summary time courses, N by R 0176 % Yvar - matrix of summary time course variance, over samples for 0177 % each time point (usually voxels) - N by R 0178 % (the marsbar code does not currently use Yvar) 0179 % sumfunc - the summary function used to summarize the samples (voxels) 0180 % per time point; a string, which is usually one of 0181 % 'mean', 'median', 'wtmean', 'eigen1', or 'unknown' 0182 % descrip - text field describing the origin of the data (optional) 0183 % info - a structure defining any other interesting information 0184 % about where the data came from 0185 % 0186 % regions - cell array of structures, with one element per region (and 0187 % therefore one element per column in the Y field). 0188 % Regions is a cell array to allow different fields to be 0189 % filled for each region 0190 % Each structure in the cell array has fields 0191 % name - string identifying region 0192 % descrip - longer description of region 0193 % Y - matrix of samples (voxel data) for this region, size 0194 % N by S1 for region 1, N by S2 for region 2 etc. 0195 % weights - weighting vector, one value for each sample 1..S1 0196 % can be empty, so each sample has weight 1. 0197 % info - structure containing any other fields of interest 0198 % vXYZ - any voxel coordinates in X Y Z dimension 0199 % (3 by S1 for region 1 etc). 0200 % mat - a 4x4 transformation matrix giving coordinates in 0201 % mm from voxel coordinates in vXYZ 0202 0203 myclass = 'marsy'; 0204 defstruct = struct('y_struct', [],... 0205 'verbose', 1); 0206 0207 if nargin < 1 0208 params = []; 0209 end 0210 if isa(params, myclass) 0211 o = params; 0212 return 0213 end 0214 if nargin < 2 0215 region_stuff = []; 0216 end 0217 if nargin < 3 0218 summary_stuff = []; 0219 end 0220 0221 % check first input 0222 if ischar(params) % maybe filename 0223 params = load(params); 0224 end 0225 switch class(params) 0226 case 'marsy' 0227 % pass quietly through 0228 o = params; 0229 return 0230 case 'struct' 0231 if ~isfield(params, 'y_struct') 0232 % Appears to be an MarsBaR data structure 0233 params = struct('y_struct',params); 0234 end 0235 0236 % need to process old data structure format here 0237 if isfield(params.y_struct, 'cols') 0238 params.y_struct = sf_convert_0p23(params.y_struct); 0239 end 0240 case {'double','float'} 0241 % direct set of summary data call 0242 params = struct('y_struct', ... 0243 struct('Y', ... 0244 params, 'Yvar', ... 0245 params * Inf, ... 0246 'sumfunc', 'unknown')); 0247 case 'cell' 0248 % specifying region data 0249 n = size(params{1}, 1); 0250 for i = 1:length(params) 0251 n2 = size(params{i}, 1); 0252 if any(n - n2) 0253 error('All regions must have the same number of time points'); 0254 end 0255 if isstruct(params{i}) 0256 regions{i} = params{i}; 0257 else 0258 regions{i} = struct('Y', params{i}); 0259 end 0260 end 0261 params = struct('y_struct', struct('regions', {regions})); 0262 otherwise 0263 error('Unexpected data type for first input'); 0264 end 0265 0266 % get number of regions 0267 R = NaN; 0268 st = params.y_struct; 0269 if isfield(st, 'Y') 0270 R = size(st.Y); 0271 elseif isfield(st, 'regions') 0272 R = length(st.regions); 0273 end 0274 0275 % process further inputs 0276 if ~isempty(region_stuff) 0277 % region_stuff has been specified 0278 if ischar(region_stuff) 0279 region_stuff = {region_stuff}; 0280 end 0281 if ~isnan(R) 0282 if length(region_stuff) ~= R 0283 error('region_stuff should have one entry per region'); 0284 end 0285 end 0286 if iscell(region_stuff) & ischar(region_stuff{1}) % names only 0287 tmp = region_stuff; region_stuff = cell(size(region_stuff)); 0288 for i = 1:length(tmp) 0289 region_stuff{i}.name = tmp{i}; 0290 end 0291 end 0292 if isstruct(region_stuff) % need a cell array 0293 tmp = region_stuff; region_stuff = cell(size(region_stuff)); 0294 for i = 1:length(tmp) 0295 region_stuff{i} = tmp(i); 0296 end 0297 end 0298 0299 % set 0300 if ~isfield(params.y_struct, 'regions') 0301 params.y_struct.regions = cell(1, length(region_stuff)); 0302 end 0303 for i = 1:length(region_stuff) 0304 params.y_struct.regions{i} = mars_struct('ffillmerge', ... 0305 params.y_struct.regions{i},... 0306 region_stuff{i}); 0307 end 0308 end 0309 0310 if ~isempty(summary_stuff) 0311 % summary_stuff has been specified 0312 if ischar(summary_stuff) % sumfunc only 0313 summary_stuff = struct('sumfunc', summary_stuff); 0314 end 0315 params.y_struct = mars_struct('ffillmerge', ... 0316 params.y_struct, ... 0317 summary_stuff); 0318 end 0319 0320 % fill with defaults, parse into fields for this object, children 0321 [pparams, others] = mars_struct('ffillsplit', defstruct, params); 0322 0323 % add version tag (was CVS; now marsbar version) 0324 pparams.cvs_version = marsbar('ver'); 0325 0326 % set the marsy object 0327 o = class(pparams, myclass); 0328 0329 % calculate summary data if possible 0330 o = resummarize(o); 0331 0332 return 0333 0334 % Subfunctions 0335 0336 % convert structure from MarsBaR <= 0.23 0337 function o_st = sf_convert_0p23(i_st) 0338 if ~isfield(i_st, 'cols') 0339 o_st = i_st; 0340 return 0341 end 0342 for r = 1:length(i_st.cols) 0343 col = i_st.cols{r}; 0344 regions{r} = struct('name', col.name,... 0345 'descrip', col.descrip,... 0346 'Y', col.y,... 0347 'weights', [],... 0348 'info', struct('file', col.file),... 0349 'vXYZ', [], ... 0350 'mat', []); 0351 end 0352 o_st = struct('Y', i_st.Y,... 0353 'Yvar', i_st.Yvar,... 0354 'regions', {regions},... 0355 'sumfunc', i_st.sumfunc,... 0356 'descrip', 'Data from MarsBaR <= 0.23',... 0357 'info', []); 0358 return 0359