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 file name or URL of the multi-column ASCII or CSV file to read. If no path is given for a file name, 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}}

Example:

W1: readt("https://www.nsstc.uah.edu/data/msu/v6.1/tlt/uahncdc_lt_6.1.txt", 1, 1, -1, -1, 0, " ", 1, -1, 0, 1, 0)

W2: extract(W1, 2, length(w1)-11, 0)

W3: col(w2, 3);setdate("1/1/1979");sethunits("monthly");setvunits("Anomaly C")

W4: (y, slope) = linreg(W3);y;label(sprintf(`Trend: %2.3f \u2103 / Decade`, slope*12*10));overp(w3);lines

W1 reads a space delimited table of monthly global temperature satellite data updated and maintained by the University of Alabama in Huntsville.

W2 extracts out the temperatures starting in January 1979 to the current date.

W3 obtains the global temperature column, sets the time axis to monthly and the Y units to "Anomaly C".

W4 computes and displays the overall linear trend in degrees C per decade.

By re-evaluating W1, the trend is updated with the latest readings.

Remarks:

READTABLE reads one or more columns from an ASCII (i.e. human readable text form) data file. The data file can be obtained from a file or URL.

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.

READTABLE

Purpose:

Syntax:

Returns:

Example:

Example:

Example:

Example:

Example:

Remarks:

See Also: