====== 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>