User Tools

Site Tools


acsvread

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

acsvread [2010/06/22 23:21] (current)
jochen created
Line 1: Line 1:
 +====== acsvread ======
  
 +===== Motivation =====
 +Very frequently data analysis is performed using several different programs at a time (e.g. Excel for text file pre-processing,​ Matlab for fMRI data analysis and R/SAS/SPSS for specific group statistic models), which leads to the question of how to best transfer data between programs. ''​acsvread''​ is one way to read in an Excel sheet that was saved as a CSV (comma-separated-values) file into a Matlab cell or struct array.
 +
 +===== Requirements =====
 +You should have the data you wish to read in prepared in one common format (that is, make sure to use the same delimiter, etc., when you save the files as CSV).
 +
 +===== Function reference ('help acsvread'​) =====
 +<​file> ​ acsvread ​ - reads a text based (non-numeric) csv file
 + 
 +  due to the different approaches when reading csv files, both a cell
 +  and a struct oriented method can be used.
 + 
 +  FORMAT: ​        table = acsvread(file,​ [delimiter,​] options)
 + 
 +  Input fields:
 +     ​file ​        ​either filename (preferably absolute) to input or
 +                  a newline seperated string containing a table or
 +                  even a cell array with input lines to process
 +     ​delimiter ​   delimiter character(s) (used for MATLAB'​s strtok)
 +     ​options ​     struct array with multiple of the following options
 +     ​.asmatrix ​   table array is a MxN cell array, not 1xM of 1xN
 +     ​.convert ​    if given, try to convert numerical values to such;
 +                  plus if set to '​deblank',​ deblanks all fields
 +     ​.headline ​   if given, functions assumes named fields (heads);
 +                  this results in a struct array, not a cell array!
 +                  further, if headline is empty read headline from
 +                  given input, otherwise use this at headline!
 +     ​.multidelim ​ if given, treat delimiter as multiple tokens
 +     ​.numonly ​    if given, only reads numbers
 +     ​.range ​      if given, acsvread only reads within range can be
 +                  either [upper-left-x,​y,​ lower-right-x,​y] coordinates
 +                  or a string in MS-Excel notation ('​A4:​F9'​) where
 +                  any missing coordinate is stretched to the edge
 +     ​.readstart ​  if given, start reading at line after given token
 +     ​.readstop ​   if given, stop reading at line before given token
 +                  meaning: lines must contain this token to match
 +     ​.replacef ​   cell array with "​replace from" strings
 +     ​.replacet ​   cell array with "​replace to" string
 + 
 +  See also asciiread, splittocell.</​file>​
 +
 +===== Options =====
 +==== asmatrix ====
 +If not given or set to ''​1'',​ the function will create a nested cell array of cell arrays. If set to ''​1'',​ the output will be a Rows-by-Columns cell array.
 +
 +==== convert ====
 +This flag controls whether or not ''​acsvread''​ attempts to convert numeric values (and whether or not deblanking of strings occurs).
 +
 +==== headline ====
 +This option can either be set to a string that, when split with the delimiter, contains the field names of the table to read. Or if the file itself contains that information,​ you can set ''​.headline''​ to ''<​nowiki>''</​nowiki>'',​ which then attempts to read the headers from the first row in the selected range.
 +
 +==== multidelim ====
 +Flag whether or not to concatenate multiple consecutive delimiters into one (only useful for very special cases).
 +
 +==== numonly ====
 +Flag whether non-numeric data should be discarded.
 +
 +==== range ====
 +By default, ''​acsvread''​ will attempt to read the entire file, but sometimes you want to discard part of the information right away (e.g. the first two columns). In that case, you can set the ''​.range''​ option to a Microsoft Excel compatible Range descriptor (e.g. '''​C1:​Z1000'''​).
 +
 +==== readstart / readstop ====
 +These two optional settings are useful if the content to read is embedded in information that is of variable length but contains a specific keyword/​token to identify the line from where to begin reading, e.g. by setting ''​.readstart''​ to '''​Logfilename''',​ any lines before and including the line containing this keyword are discarded.
 +
 +==== replacef / replacet ====
 +Sometimes you want to perform a "​Search-and-Replace"​ before (or while) data is being read. You can pass two cell arrays which will then, in turn, be passed to ''​strrep''​.
 +
 +===== Exemplary calls =====
 +  * to read in a file which was saved with '',''​ (comma) as field separator, you could use: <code matlab acsvread_example_flat.m>​table = acsvread('​tabularfile.csv',​ struct( ...
 +    '​asmatrix',​ 1, ...
 +    '​convert',​ 1));</​code>​
 +  * in case this file also has header fields (names in the first row) and you wish to convert the read file into a NrOfRows-by-1 struct, use: <code matlab acsvread_asstruct.m>​tstruct = acsvread('​tabularfile.csv',​ struct( ...
 +    '​asmatrix',​ 1, ...
 +    '​convert',​ 1, ...
 +    '​headline',​ ''​));</​code>​
acsvread.txt ยท Last modified: 2010/06/22 23:21 by jochen