Textreadr

Purpose

Reads ASCII flat files from MS Excel and other spreadsheets as a DataSet Object.

Synopsis

out = xclreadr(file,delim,options)

Description

XCLREADR reads tab, space, comma, semicolon or bar delimited files with names on the columns (variables) and rows (samples). Also handles Excel XLS files.

If XCLREADR is called with no input, or an empty matrix for file name file, a dialog box allows the user to select a file to read from the hard disk.

Inputs

• file = One of the following identifications of files to read:

a) a single string identifying the file to read

('example.txt')

b) a cell array of strings giving multiple files to read

({'example_a' 'example_b' 'example_c'})

c) an empty array indicating that the user should be prompted to locate the file(s) to read

([])

• delim = An optional string used to specify the delimiter character.

Supported delimiters include:

• 'tab' or '\t' or sprintf('\t')
• 'space' or ' '
• 'comma' or ','
• 'semi' or ';'
• 'bar' or '|'

If (delim) is omitted, the file will be searched for a delimiter common to all rows of the file and producing an equal number of columns in the result.

Outputs

• out = A DataSet object with date, time, info (data from cell (1,1)) the variable names vars, sample names samps, and data matrix data. Note that the primary difference between this function and the Mathworks function xlsread is the parsing of labels and output of a dataset object.

Options

Optional input options = a structure array with the following fields:

• parsing: [ 'manual' | {'automatic'} | 'auto_strict' | 'gui' ] determines the type of parsing to perform:

'automatic' : the file is automatically parsed for labels and header information. This works on many standard arrangements with different numbers of rows and column labels. May take some time to complete with larger files. See note below regarding additional options available with 'automatic' parsing.

'auto_strict' : faster automatic parsing which does not handle header lines, and expects that all row labels will be on the left-hand side of the data and all column labels will be on the top of the columns. If this returns the wrong result, try 'automatic'.

'manual' : the options below are used to determine the number of labels and header information.

'stream' : nearly identical to 'automatic' but reads from the file in pieces. This allows reading somewhat larger files than might otherwise be readable because of memory limitations.

'gui' : allows selection of standard options using a GUI.

Note that when the file type is XLS, 'automatic' parsing is always performed.

• commentcharacter: [''] any line that starts with the given character will be considered a comment and parsed into the "comment" field of the DataSet object. Deafult is no comment character. Example: '%' uses % as a comment character.

NOTE: Only used with 'automatic' and 'manual' parsing, NOT with 'auto_strict' parsing.

• headerrows : [{0}] number of header rows to expect in the file.

NOTE: Only used with 'automatic' and 'manual' parsing, NOT with 'auto_strict' parsing.

• rowlabels  : [{1}] number of row labels to expect in the file

NOTE: Only used with 'manual' parsing. See parsemixed for similar options to use with 'automatic' parsing.

• collabels : [{1}] number of column labels to expect in the file

NOTE: Only used with 'manual' parsing. See parsemixed for similar options to use with 'automatic' parsing.

• waitbar : [ 'off' |{'on'}] Governs use of waitbars to show progress

The default options can be retrieved using: options = xclreadr('options');

In addition to the above options, if option parsing is set to 'automatic', any option used by the parsemixed function can be input to XCLREADR. These options will be passed directly to parsemixed for use in parsing the file. See parsemixed for details.

Examples

Reading a file (in this case an XLS file) which has a single row of axis scale information at the top (first row) of the table and a single column of axis scale information at the left (first column) of the table can be done using this code:

  opts = xclreadr('options');
  opts.axisscalecols = [1];
  opts.axisscalerows = [1];
  data = xclreadr('myfile.xls',opts);

See Also

areadr, dataset, parsemixed, spcreadr, xclgetdata, xclputdata, xlsreadr