maroi

 maroi - class constructor for umbrella ROI object
 Can be called as a simple contructor:
 inputs [defaults]
 params  - a structure, containing fields to construct the object
  
 or to load objects of this (or child) type)
 o = maroi('load', fname);
 or
 o = maroi(fname);
 (where fname is a string)
 or
 o_cell_arr = maroi(name_cell_arr);
 (where 
 o_cell_arr is a cell array of ROI objects and
 name_cell_arr is a cell array of filenames)
 or 
 o_cell_arr = maroi('load_cell', fnames)
 to load strings/cell array of strings into cell array of objects

 or to access class data
 res = maroi('classdata', p1, p2); (see classdata method)

 or to process a filename to be suitable for saving an ROI
 new_fn = maroi('filename', old_fn);

 An ROI is a definition of a region in space. As currently implemented,
 an ROI can be of three types:

 a shape - a geometric shape defined independent of any image
           e.g. sphere, box
 a point list - a list of points which are within the region, maybe with
                associated values (see below)
 a volume - a 3D volume, containing values for the ROI at each point
           e.g. matrix, image 

 Usually, the ROI will be binary; i.e. any point that is within the
 region will have a value of 1, and all points outside have a value of
 0.  Because regions may be resampled into new image spaces, this
 binaryness needs to be enforced in the resampling; this is done if the
 'binarize' flag is set for the object; the 'roithresh' field determines
 the value above which a point is considered within the region, after
 resampling.

 In addition to defining the region in space, the ROI may also define
 values for the points within the region.  If an ROI defines values then it
 is a 'weighting' ROI (such as 0->1 probability weighting); those ROIs can
 contain different values across the region.  Because of the problem of
 missing values when resampling an ROI (e.g sampling at the edge of a
 volume when using anything other than nearest neighbour resampling),
 weighting ROIs should be zero based, so that a value outside the
 region will be considered to have the value 0 in resampling.  Values of
 NaN and 0 will always be assumed to be outside the region after
 resampling
 
 At the moment, each ROI is saved as a separate mat file, with filename
 <name>_roi.mat

 $Id$

0001 function [o, others] = maroi(params, varargin)
0002 % maroi - class constructor for umbrella ROI object
0003 % Can be called as a simple contructor:
0004 % inputs [defaults]
0005 % params  - a structure, containing fields to construct the object
0006 %
0007 % or to load objects of this (or child) type)
0008 % o = maroi('load', fname);
0009 % or
0010 % o = maroi(fname);
0011 % (where fname is a string)
0012 % or
0013 % o_cell_arr = maroi(name_cell_arr);
0014 % (where
0015 % o_cell_arr is a cell array of ROI objects and
0016 % name_cell_arr is a cell array of filenames)
0017 % or
0018 % o_cell_arr = maroi('load_cell', fnames)
0019 % to load strings/cell array of strings into cell array of objects
0020 %
0021 % or to access class data
0022 % res = maroi('classdata', p1, p2); (see classdata method)
0023 %
0024 % or to process a filename to be suitable for saving an ROI
0025 % new_fn = maroi('filename', old_fn);
0026 %
0027 % An ROI is a definition of a region in space. As currently implemented,
0028 % an ROI can be of three types:
0029 %
0030 % a shape - a geometric shape defined independent of any image
0031 %           e.g. sphere, box
0032 % a point list - a list of points which are within the region, maybe with
0033 %                associated values (see below)
0034 % a volume - a 3D volume, containing values for the ROI at each point
0035 %           e.g. matrix, image
0036 %
0037 % Usually, the ROI will be binary; i.e. any point that is within the
0038 % region will have a value of 1, and all points outside have a value of
0039 % 0.  Because regions may be resampled into new image spaces, this
0040 % binaryness needs to be enforced in the resampling; this is done if the
0041 % 'binarize' flag is set for the object; the 'roithresh' field determines
0042 % the value above which a point is considered within the region, after
0043 % resampling.
0044 %
0045 % In addition to defining the region in space, the ROI may also define
0046 % values for the points within the region.  If an ROI defines values then it
0047 % is a 'weighting' ROI (such as 0->1 probability weighting); those ROIs can
0048 % contain different values across the region.  Because of the problem of
0049 % missing values when resampling an ROI (e.g sampling at the edge of a
0050 % volume when using anything other than nearest neighbour resampling),
0051 % weighting ROIs should be zero based, so that a value outside the
0052 % region will be considered to have the value 0 in resampling.  Values of
0053 % NaN and 0 will always be assumed to be outside the region after
0054 % resampling
0055 %
0056 % At the moment, each ROI is saved as a separate mat file, with filename
0057 % <name>_roi.mat
0058 %
0059 % $Id$
0060   
0061 % Programmers' notes
0062 %
0063 % maroi is the parent for all ROI objects. It can contain no useful ROI
0064 % itself, but implements functions for all objects of maroi type.  Children
0065 % will generally call this parent constructor with passed arguments.  This
0066 % constructor routine then sets fields contained in the parent maroi object,
0067 % and removes the relevant fields from the passed structure, then returns
0068 % the stripped structure to the caller, so that it can use any extra
0069 % arguments to set child properties, etc
0070 %
0071 % Fields are [defaults - which may well be overidden by children]:
0072 % source   - filename for roi object ['']
0073 % label    - 16 character label for outputting
0074 % descrip  - (maybe) prolix description of ROI ['']
0075 % history  - string specifying processing done to ROI ['']
0076 % spm_hold - defines resampling method when reslicing ROI into different
0077 %            space (see spm_sample_vol.m) [1]
0078 % binarize - flag to indicate this is a binary ROI.
0079 %            if == 1, The object will always return binary values; this is
0080 %            enforced at object initialization, and during during
0081 %            resampling [1]
0082 %
0083 % roithresh - absolute threshold above which a point is considered within
0084 %            the ROI. With binarize flad set, this value
0085 %            will usually be 0.5 (see defaults set in classdata).  With
0086 %            binarize flag unset, iw will usually be eps. These defaults
0087 %            are set using the classdata variable
0088 %
0089 % Methods that must be defined for a maroi object are
0090 % [pts vals] = voxpts(obj, space)
0091 % [pts vals] = realpts(obj, space)
0092 % timeseries = getdata(obj, images, [flags]);
0093 % mobj = maroi_matrix(obj, [space])
0094 %
0095 % In constructor calls:
0096 % params passed are fields for current object, and for any parents
0097 % (thus there must be no overlap in field names between child and parent
0098 % objects, which in can in any case be confusing).
0099 %
0100 % Matthew Brett 21/9/01 (AR)
0101 
0102 myclass = 'maroi';
0103 defstruct = struct(...
0104     'source','',...
0105     'label','',...
0106     'descrip', '',...
0107     'history','',...
0108     'spm_hold',  my_classdata('def_hold'),...
0109     'binarize',1,...
0110     'roithresh', my_classdata('def_binthresh'));
0111 
0112 if nargin < 1
0113   params = [];
0114 end
0115 if isa(params, myclass)
0116   o = params;
0117   return
0118 end
0119 
0120 % parse out string action calls (class data, helper functions)
0121 if ischar(params)
0122   switch params
0123    case 'classdata'
0124     o = my_classdata(varargin{:});
0125    case 'load'
0126     o = my_loadroi(varargin{1});
0127    case 'load_cell'
0128     params = varargin{1};
0129     if ischar(params), params = cellstr(params); 
0130     elseif ~iscell(params), params = {params}; end
0131     o = maroi(params);
0132    case 'filename'
0133     o = my_roifname(varargin{:});
0134    otherwise % single filename
0135     if size(params, 1) > 1
0136       error('Use cell form of call to load multiple objects');
0137     end
0138     o = my_loadroi(params);
0139   end
0140   return
0141 end
0142 
0143 % cell array - array of filenames, or objects, or something
0144 if iscell(params)
0145   sz = size(params);
0146   o = cell(sz);
0147   for r = 1:prod(sz)
0148     o{r} = maroi(params{r});
0149   end
0150   return
0151 end
0152 
0153 % fill with defaults, parse into fields for this object, children
0154 [pparams, others] = mars_struct('ffillsplit', defstruct, params);
0155 
0156 % Check for default thresholds according to binarize flag
0157 if isfield(params, 'binarize') && ~isempty(params.binarize) && ...
0158       params.binarize == 0 && ( ~isfield(params, 'roithresh') || ...
0159       isempty(params.roithresh))
0160   pparams.roithresh = my_classdata('def_wtthresh');
0161 end
0162   
0163 % add version tag (was CVS; now marsbar version)
0164 pparams.cvs_version = marsbar('ver');
0165 
0166 % Set as object
0167 o  = class(pparams, myclass);
0168 
0169 return