<< Overview dataINT DI_readcsv >>

dataINT >> dataINT > DI_read

DI_read

Imports a data file (comma-separated-value, Excel-xls, text-based) in a matrix variable interactively. Combined functionality of DI_readcsv() and DI_readxls().

Calling Sequence

[dataMat] = DI_read()
[dataMat] = DI_read(path)
[dataMat, exitID] = DI_read()
[dataMat, exitID] = DI_read(path)

Parameters

path:

a string, target path for the file selector (OPTIONAL)

dataMat:

a string, name of the matrix which stores the imported data

exitID:

an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below.

Description

Read numerical data from a comma-separated-value (*.csv) or another text-based data file (*.dat, *.txt) or a binary Excel 95-2003 file (*.xls) and stores it into a matrix variable interactively.

Many field or decimal delimiters in text-based files are accepted (see below).

DI_read combines the functionality of DI_readcsv and DI_readxls in one function.

path:

You can commit an optional path to the function. This is used to open the file selector at the committed target path. If you omit it your home directory is set as the target path.

dataMat:

This is the name of the matrix variable which will content the imported data for further processing in Scilab's console or in a script.

exitID:

The exitID gives a feedback what happened inside the function. If something went wrong dataMat is always [] (empty). To handle errors in a script you can evaluate exitID's error codes (negative numbers):

  • 0: Everything is OK. Matrix dataMat was created

  • -1: User canceled file selection

  • -2: User canceled parameter dialog box

  • -3: Cannot read or interpret data file

  • -4: Cannot interpret file correctly - maybe header present (only CSV/TXT data files)

Comma-Separated-Value-, Text-Based Data Files

Read text-based data files which contains numerical data. The following field delimiters are accepted: Comma, semicolon, space(s), tabular(s). The decimal delimiter can be point or comma.

Note that the file has to be correctly formated. All rows have to have the same number of columns.

Import Parameter:

Field Separator:

This is the character which separates the fields and numbers, resp. In general CSV-files it is the comma (,), in European ones it is often the semicolon (;). Sometimes it is a tabulator (tab). Text-based data files has a space or spaces as delimiters. E.g. to specify a tabulator as separator, type in the word "tab", for a space separator the word "space" without quotes.

Decimal separator:

The character which indentifies the decimal place. In general CSV files it is the point (.), in most European ones it is the comma (,).

Number of Header Lines to Skip:

The number of lines to be ignored at the beginning of the file. This is useful to skip table headers.

Row/Columns Range Start:

The row/column at which the import is going to start. Type a number. 1 means import starts at row/column 1 inclusively.

Row/Columns Range End:

The row at which the import is going to end. Type a number or $ (dollar- sign). 12 means the import stops at row 12 inclusively, $ means that all rows/columns are read to the end.

For CSV and text-based data files there are different prerequisites to consider.

Comma-separated-value (*.csv):

All rows have to have the same number of columns. That does not mean that every cell has to be occupied by a number. Only the separator has to be present:

2.3 , 4.4 , 7.6 , 9.5
5.6 , 6.9 ,     ,

Strings or missing data (see above) are represented as Nan (not-a-number) in the matrix. E.g.:

2.3  4.4  7.6  9.5
5.6  6.9  Nan  Nan

Text-based data (*.dat, *.txt):

All rows have to have the same number of columns and should not contain strings (text). Otherwise the data will be imported as a string matrix and not a number matrix.

| 2.3  4.4  7.6  9.5 |
|                    |
| 5.6  6.9           |

Excel 95-2003 Files

Read numerical data from XLS-files

DI_read can read binary Excel-files (*.xls) from Excel 95-2003 only. XML-based Excel files (*.xlsx) from Excel 2010 and higher are not supported!

DI_read handles numerical data only. Strings or missing data are imported as Nan (Not-a-number, %nan).

Import Parameter:

Sheet#:

The number of the sheet of the Excel file you want to import from. The names of the sheets are not evaluated. The 1st sheet is 1 the 2nd is 2 independent of their names in Excel.

Row/Columns Range Start:

The row/column at which the import is going to start. Type a numer. 1 means import starts at row/column 1 inclusively.

Row/Columns Range End:

The row at which the import is going to end. Type a number or $ (dollar- sign). 12 means the import stops at row 12 inclusively, $ means that all rows/columns are read to the end.

Examples

[mat, id] = DI_read(fullfile(DI_getpath(), "demos")); // Read CSV file
disp("Exit-Code: "+string(id),mat,"data:") // Displays imported data "mat" and exit code "id"
if id == 0 then // Plot data if import was sucessful
plot(mat(:,1),mat(:,14),".-")
xtitle("Central England Temperature","Year","Mean Temperature [°C]")
end

See also

Authors


Report an issue
<< Overview dataINT DI_readcsv >>