import::csv

Read CSV data from an ASCII file

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

import::csv(filename, <separator>, <NonNested>, <Trim>, <DecimalComma>)
import::csv(n, <separator>, <NonNested>, <Trim>, <DecimalComma>)

Description

import::csv is used to read CSV ("Comma Separated Values" or "Character Separated Values") data files produced by external programs, like Microsoft® Excel®. CSV is an ASCII based tabular data file format, formally defined in RfC 4180, that has fields separated by the comma character.

    Note:   Some localized versions of Microsoft Excel use semicolons instead of commas! Set the parameter separator to change the default separator.

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

import::csv(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::csv(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.

In contrast to finput, the data must not be ended by a colon or semicolon. Data separated by separator are interpreted as single data items. The default separator is a comma.

Empty lines are ignored.

All data elements in the file that cannot be converted to valid MuPAD® numbers are imported as MuPAD strings.

import::csv tries to convert a number contained in the CSV file to a valid MuPAD number. For example: 1,234.56 or 1 234.56 are converted to the MuPAD number 1234.56. Many countries use a comma to separate the integral and fractional part instead of the dot used in England and the US. For example: 1234,56 or 1.234,56 are converted to 1234.56. import::csv expects this number format if the option DecimalComma is given.

    Note:   A comma as CSV separator doesn't make sense if the comma is used to separate thousands in a number or the decimal comma is used. In most cases, the CSV file uses a semicolon to separate data. So, a semicolon should be used as separator.

    Note:   All numbers contained in the CSV file must use the same radix separator, mixed formats cannot be converted.

With NonNested, the result will be a list containing all data. Otherwise, the result is a list of list, each "inner" list representing a line of the CSV file.

With Trim, leading and trailing blanks in strings are removed.

If the file is specified by a string, the corresponding file is opened and closed, automatically. If the user has opened a text file in Read mode and passes the file descriptor to import::readdata, the file remains open and needs to be closed by the user.

Files compressed with gzip or in a compatible format, whose names end in ".gz", are automatically decompressed while being read by import::csv.

import::csv(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 directory path.

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.

Examples

Example 1

We wish to read CSV data into a MuPAD session. Assume that the file "datafile.csv" contains the following two columns of ASCII data:

a ,12.5
  a-b   ,1234.56

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

data := import::csv("datafile.csv")

data := import::csv("datafile.csv", Trim)

data := import::csv("datafile.csv", NonNested)

Example 2

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

a ;12.5
a-b;1,234.56 
a b; -12345.6789E-02

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

import::csv("datafile.csv", ";")

Example 3

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

abc;12,5
a-b;1.234,56 
a b; -12345.6789E-02

We specify the data separator ";" and the option DecimalComma for reading the data:

import::csv("datafile.csv", ";", DecimalComma)

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 a comma (the single character string ",").

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.

Trim

Leading and trailing blanks in strings are removed.

DecimalComma

A decimal comma instead of a decimal point is used as the radix separator in the CSV file.

Return Values

Nested list of lists. The sublists contain the data of the individual 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?