READTABLE

Purpose:

Reads a multi-column ASCII or CSV file and returns a series or table.

Syntax:

READTABLE(

"filename", startrow, startcol, collist, numrows, hex, "delstr", "nanstr", "infstr", "decstr", skipdl, numcols, getsize, commentrow, unitsrow, verbose)

"filename"

-

A string. The name of the multi-column ASCII or CSV file to read. If no path is given, READTABLE searches the current working directory for the file.

startrow

-

Optional. An integer. The starting line number of the data. Defaults to 1, the first line in the file.

startcol

-

Optional. An integer. The starting column number of data. Defaults to 1, the first column.

collist  

-

Optional. List of integers indicating which columns of data to accept. Defaults to -1, all columns.

numrows    

-

Optional. An integer. The number of rows to accept. Defaults to -1, all rows.

hex

-

Optional. An integer. The numeric format.

0:

Interpret values as normal ASCII values (default).

1:

Interpret values as hex numbers.

"delstr"  

-

Optional. A string. Column delimiter (or separator). Defaults to " ", the space character.

"nanstr"

-

Optional. A string. The text used to indicate a NaN (not a number) value. Defaults to "nan".

"infstr"  

-

Optional. A string. The text used to indicate an infinity value. Defaults to "inf".

"decstr"

-

Optional. A string. The decimal point character. Defaults to ".", the period character.

skipdl   

-

Optional. An integer. The multiple delimiter mode:

0:

Interpret each delimiter as marking a (potentially missing) column.

1:

Skip consecutive delimiters (default).

numcols  

-

Optional. An integer. The number of columns. If numcols < 0, implies scan the entire file before reading to determine number of columns. If numcols == 0, use first read line to determine the number of columns. If READT_AUTOCOL is 1, defaults to 1 (scan entire file) else 0 (use first line).

getsize  

-

Optional. An integer. If 1, return the number of columns and number of rows as a 2 point series. Used to determine the size of the file. Defaults to 0, no action.

commentrow

-

Optional. An integer. The explicit row (line number) that contains a comment or header text for each column. If commentrow < 0 (the default), the comment line is determined automatically. If commentrow == 0, the comment line is ignored and no attempt is made to determine the comment. If commentrow > 0, the delimited text found at commentrow is used as the comment.

unitsrow

-

Optional. An integer. The explicit row (line number) that contains the units text for each column. If unitsrow < 0 (the default), the units line is determined automatically. If unitsrow == 0, the units line is ignored and no attempt is made to determine the units. If unitsrow > 0, the delimited text found at unitsrow is used as the units.

verbose

-

Optional. An integer. The message progress flag:

0:

Do not display progress message

1:

Display progress message (default).

2:

Display progress message including the total number of lines in the source file.

Returns:

A series, or table.

 

Example:

readtable("mytable.dat",1,1,12,17)

 

returns a table with two columns of data, as found in columns 12 and 17 of mytable.dat.

 

a = readtable("table.dat",1,1,-1,10)

 

assigns the first 10 rows of the file table.dat to variable a.

Example:

readtable("data.tab",5,1,2,3,-1,10)

 

returns the first 10 rows starting at row 5, and only accepting columns 2 and 3.

Example:

writetable("table.csv",ravel(0..14, 5), ",")

readt("table.csv", 1, 1, -1, -1, 0, ",")

 

returns the following 5x3 table:

 

 {{0, 5, 10}

  {1, 6, 11}

  {2, 7, 12}

  {3, 8, 13}

  {4, 9, 14}}

 

This is an example of a file in Comma Separated File or CSV format where the "," is the column delimiter.

Example:

fopen("hex.dat", "w+");

fputs("000a 000b 000c ", "hex.dat");

fputs("000d 000e 000f ", "hex.dat");

fclose("hex.dat");

readt("hex.dat", 1, 1, -1, -1, 1, " ");

 

returns the 2x3 series

 

 {{10, 11, 12},

  {13, 14, 15}}

Remarks:

READTABLE reads one or more columns from an ASCII (i.e. human readable text form) data file.

 

READTABLE translates the NA, NaN or NULL (without quotes) in a file to NA in the resulting table.

 

If specified, collist must terminate with -1 to indicate the end of the list.

 

If numcols < 0, READTABLE first scans the entire file to determine the number of data columns. This allows READTABLE to automatically read files with missing columns but at slower execution speed because the file is read twice.

 

If numcols == 0, the first successfully read line is used to determine the number of data columns. This results in faster execution, but missing columns may not be read properly.

 

If the configuration parameter READT_AUTOCOL is 1, numcols defaults to 1, scan the entire file, else numcols defaults to 0, use the first read line.

 

If verbose == 2, the entire file is scanned (if necessary) to determine the total number of lines for reporting purposes.

 

For Comma Separated Variable or CSV files,  use the "," as the column delimiter.

 

For European and other files that use the comma as the decimal character, set decsrtr to ",".

 

See WRITETABLE to write a multi-column ASCII or CSV file

 

READTABLE can be abbreviated READT.

See Also:

EXPORTFILE

FREADA

IMPORTFILE

READA

WRITEA

WRITETABLE