transio
no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
— | transio [2011/04/04 19:12] (current) – created jochen | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== transio (transparent file I/O access class) ====== | ||
+ | |||
+ | ===== Motivation ===== | ||
+ | Neuroimaging datasets can easily reach very large sizes (e.g. running a study with 2 groups of 24 subjects each and a 3x2x2 within-subject design requires to store a total of at least 48 * 13 = 624 maps, if each of these maps fully covers the brain at a 3mm resolution this amounts to up to 200,000 voxels per map requiring 800,000 bytes of diskspace leading to a total of about 500MByte of required storage capacity). | ||
+ | |||
+ | Working with such large datasets can become difficult if several larger datasets must be "kept in memory" | ||
+ | |||
+ | To simplify this concept, the class is highly integrated into the [[xff]] class, which allows binary data file to be read with " | ||
+ | |||
+ | <code matlab xff_transio.m> | ||
+ | xff(0, ' | ||
+ | |||
+ | % disable transio access | ||
+ | xff(0, ' | ||
+ | |||
+ | % enabled transio access for VTCData elements only | ||
+ | xff(0, ' | ||
+ | |||
+ | % get current xff/transio configuration settings | ||
+ | xff_tio_config = xff(0, ' | ||
+ | |||
+ | % restore configuration | ||
+ | xff(0, ' | ||
+ | |||
+ | ===== Requirements ===== | ||
+ | Currently, the transio access is limited to the following conditions: | ||
+ | |||
+ | * data is stored at a known and fixed " | ||
+ | * size of accessed array does not change (other than regular arrays, transio access references do not allow changes in size at run-time) | ||
+ | * if complex indexing is performed, each index is only used once | ||
+ | |||
+ | ===== Class reference ('help transio' | ||
+ | < | ||
+ | |||
+ | FORMAT: | ||
+ | |||
+ | Input fields: | ||
+ | |||
+ | file filename where data is stored in | ||
+ | endian | ||
+ | class | ||
+ | offset | ||
+ | size size of array in file | ||
+ | |||
+ | Output fields: | ||
+ | |||
+ | tio_obj | ||
+ | - subsref | ||
+ | - subsasgn : same as subsref | ||
+ | - size : retrieving the array size | ||
+ | - end : for building relative indices | ||
+ | - display | ||
+ | |||
+ | Note 1: enlarging of existing files (if the array is the last element | ||
+ | in the file) can be done by adding a (class-independent) sixth | ||
+ | parameter to the call. | ||
+ | |||
+ | Note 2: both subsref and subsasgn will only work within the existing | ||
+ | limits; growing of the array as with normal MATLAB variables | ||
+ | is *NOT* supported--so tio_obj(:,:, | ||
+ | |||
+ | ===== Syntax overview ===== | ||
+ | |||
+ | ==== Creating a transio object ==== | ||
+ | Creating a transio object is done by a call to the constructor ('' | ||
+ | |||
+ | <code matlab transio_createobj.m> | ||
+ | niidata = transio(' | ||
+ | |||
+ | If the file does not exist or is not "large enough" | ||
+ | |||
+ | <code matlab transio_extentobj.m> | ||
+ | niidata = transio(' | ||
+ | |||
+ | ==== Accessing a transio object ==== | ||
+ | In principle, data access works seemlessly, just as with a regular matlab variable... | ||
+ | |||
+ | <code matlab transio_access.m> | ||
+ | niivol = niidata(:, :, :, 1581); | ||
+ | |||
+ | % setting one volume of data | ||
+ | niidata(:, :, :, 2711) = newvol;</ | ||
+ | |||
+ | As this class is integrated into the [[xff]] class, it can be directly used, for instance to read only time courses of a VTC that fall within a mask: | ||
+ | |||
+ | <code matlab transio_read_masked_vtc.m> | ||
+ | xff(0, ' | ||
+ | |||
+ | % load MSK and VTC | ||
+ | msk = xff(' | ||
+ | vtc = xff(' | ||
+ | |||
+ | % check objects | ||
+ | if isxff(msk, ' | ||
+ | |||
+ | % get mask indices | ||
+ | maski = find(msk.Mask(: | ||
+ | | ||
+ | % read only the data we need | ||
+ | maskedvtcdata = vtc.VTCData(:, | ||
+ | end | ||
+ | |||
+ | % clear objects | ||
+ | clearxffobjects({msk, | ||
+ | |||
+ | The referencing of '' | ||
+ | |||
+ | And the same syntax can also be used for write access "into a transio" | ||
+ | |||
+ | ==== Additional notes ==== | ||
+ | Some of the more typical functions applied to numerical data (plus, minus, times, mtimes, etc.) have been overloaded so that transio objects can potentially be used in expressions in a formula. But as it might be more prudent to use a double-precision version for complex computations, | ||
transio.txt · Last modified: 2011/04/04 19:12 by jochen