Home > marsbar > @marsy > marsy.m

marsy

PURPOSE ^

Class constructor for marsy: the MarsBaR data object

SYNOPSIS ^

function [o,others] = marsy(params, region_stuff, summary_stuff)

DESCRIPTION ^

 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$

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

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

Generated on Thu 17-Mar-2016 01:14:46 by m2html © 2005