import::readdata

Read data from an ASCII file

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

import::readdata(filename | n, <separator>, <NonNested>)

Description

import::readdata(filename) reads the data in the file filename. File data separated by whitespace are regarded as different data elements. The result is a list of lists, each sublist representing one line of the file.

import::readdata(filename, separator) reads the data in the file filename. File data separated by the character separator are regarded as different data elements. The result is a list of lists, each sublist representing one line of the file.

import::readdata(filename, separator, NonNested) reads the data in the file filename as a single data record. File data separated by the character separator are regarded as different data elements. The result is a plain non-nested list containing the data of all lines of the file.

import::readdata(filename) searches for the file in various directories:

  • First, the name is interpreted as a relative file name: filename is concatenated to each directory given by the environment variable READPATH.

  • Then the file name is interpreted as an absolute path name.

  • Then the file name is interpreted relative to the "working directory."

  • Last, the file name is concatenated to the library directory.

If a file can be opened with one of this names, then the file is read.

Note that the meaning of "working directory" depends on the operating system. On Microsoft® Windows® systems and on Apple Mac OS X systems, the "working directory" is the folder where MuPAD® is installed. On UNIX® systems, it is the current working directory in which MuPAD was started; when started from a menu or desktop item, this is typically the user's home directory.

A path separator ("/") is inserted as necessary when concatenating a given path and filename.

If a file is specified by a file name, there is no need to open or close the file via fopen and fclose, respectively. This is done automatically by import::readdata.

Instead of a file name, also a file descriptor of a file opened via fopen can be used. Note that the file must have been opened in Read mode by fopen. If a file descriptor is used, the corresponding file is not closed automatically but must be closed by the user via fclose.

Files compressed by gzip or a compatible program (having a name ending in ".gz") are decompressed automatically upon reading.

All data elements in the file are interpreted as MuPAD objects. If a data element cannot be interpreted as a MuPAD object, it is imported as a MuPAD string. Otherwise, the corresponding MuPAD object is inserted into the list returned by import::readdata.

    Note:   Note that the MuPAD objects corresponding to the data elements are evaluated after reading. E.g., the data element "sin(0)" in the file is evaluated and imported as the MuPAD integer 0. Beware: the characters ";" and ":" have a specific meaning if not specified as separators in import::readdata: they separate MuPAD commands. Hence, if a read data element contains one of this characters, MuPAD interprets this data element as a sequence of statements and, upon evaluation, returns the value of the last statement as the MuPAD object corresponding to the data element. Cf. Example 3.

In contrast to finput, the data elements in the file do not have to be ended by a colon or a semicolon.

Empty lines in the file are ignored.

Examples

Example 1

We wish to read statistical data into a MuPAD session to test the correlation of two data samples. Assume that the file "datafile" contains the following two columns of ASCII data (each column representing a data sample):

      0.12    0.2534
      2.324   5.72
      1.02    2.2232
      4.02    7.321
      7.4    14.9
     -7.4   -15.1

import::readdata returns the following list representing the data in the file:

data := import::readdata("datafile")

The data structure stats::sample converts this nested list into two data columns:

s := stats::sample(data)
 0.12  0.2534
2.324    5.72
 1.02  2.2232
 4.02   7.321
  7.4    14.9
 -7.4   -15.1

The following computation shows that there is a very strong correlation between the data in the first column and the data in the second column:

stats::correlation(s, 1, 2)

If the data in the file are supposed to represent a single sample (data record), we may ignore the fact that the numbers are arranged on several lines. With NonNested, the data are read as a single sample:

data := import::readdata("datafile", NonNested)

Mean and standard deviation of the data are:

stats::mean(data), stats::stdev(data)

delete data, s:

Example 2

Let us assume that the file "datafile" contains the following ASCII data:

      1 | 2   | 3

      4| 5 | 6.65786
      7| 8 |9| 5 | "ahfjd" | ab100|-23

We specify the data separator "|" for reading the data:

import::readdata("datafile", "|")

Note that whitespace inside the data elements as well as the empty line in the file are ignored.

Example 3

We first create the ASCII data files that will be used in this example. We recall that x degrees Celsius are degrees Fahrenheit. First, two data files are created containing the matching temperatures from - 5 degrees Celsius to 30 degrees Celsius in steps of 5 degrees Celsius:

n1 := fopen(Text, "data1", Write):
n2 := fopen(Text, "data2", Write):
for celsius from -5 to 20 step 5 do 
  fahrenheit := 9/5*celsius + 32:
  fprint(Unquoted, n1, celsius, " ", fahrenheit):
  fprint(n2, celsius, fahrenheit):
end_for:
fclose(n1):
fclose(n2):

The file "data1" now contains the following data:

-5 23
0 32
5 41
10 50
15 59
20 68

The file "data2" contains the following data:

-5:23:
0:32:
5:41:
10:50:
15:59:
20:68:

Now, we import the data:

import::readdata("data1")

Reading data from the file "data2" yields an unexpected result:

import::readdata("data2")

What went wrong? Remember that the default data separator is whitespace. Consequently, MuPAD reads the expression -5:23: as the only data element in the first line. When MuPAD evaluates this data element, it interprets it as a sequence of two MuPAD statements. The result of the statement sequence is the result of the last of the two statements, i.e., the number 23. This is the first datum in the resulting list. For getting the data as desired, an appropriate separator must be specified. The file "data2" should be read as follows:

import::readdata("data2", ":")

We use the option NonNested to get a plain list containing all data elements without putting each record (line) in a sublist of its own:

import::readdata("data2", ":", NonNested)

delete n1, n2:

Example 4

Here we can see that the data are evaluated after reading. First, we create the data file:

n1 := fopen(Text, "data3", Write) :
fprint(Unquoted, n1, a, " 12 ", b):
fclose(n1):

Now, the data are read:

import::readdata("data3")

If a and b have values, we get:

a := 3:  b := 34:  import::readdata("data3")

delete n1, a, b:

Example 5

First, we create a data file with random floating-point data that a separated by blank characters:

n := fopen(Text, "data4", Write):
for i from 1 to 3 do
    fprint(Unquoted, n, (frandom(), " ") $ j = 1..4);
end_for;
fclose(n):

This file is reopened for reading with fopen:

n := fopen(Text, "data4", Read)

The file descriptor n returned by fopen can be passed to import::readdata:

import::readdata(n)

Note, however, that the file was opened explicitly by the user with fopen and is not closed automatically by import::readdata. Consequently, the user is supposed to close the file explicitly via fclose:

fclose(n):
delete i, n:

Parameters

filename

The file name: a non-empty character string

n

A file descriptor provided by fopen: a positive integer

separator

The separator between data elements: a character string of length 1 (a single character). The default separator is whitespace.

Options

NonNested

Return all file data as a single data record in a non-nested list. The data of all lines are ordered sequentially in this list.

Return Values

Nested list of lists. The sublists contain the data of the indiviual lines. With the option NonNested, a plain list containing all data elements from every line in the file.

See Also

MuPAD Functions

Was this topic helpful?