from_file

  • Austin C Bullock

interface from_file

Description: Subroutine for reading an external file of uniform numeric, logical or text data into an array.

For reading textual data into an array into of rank 1 or 2 and of type integer:

call from_file(file, into [, header, delim, fmt, stat, errmsg, format, column_names])
  • file is of type character(len=*)
  • header is optional and of type logical
  • delim is optional and of type character(len=*)
  • fmt is optional, may be one of INT_FMTS
  • stat is optional and of type integer
  • errmsg is optional and of type character(len=*)
  • column_names is optional and of type type(String), allocatable, dimension(:)

For reading textual data into an array into of rank 1 or 2 and of type real:

call from_file(file, into [, header, locale, delim, fmt, stat, errmsg, format, column_names])
  • file is of type character(len=*)
  • header is optional and of type logical
  • locale is optional, may be one of LOCALES
  • delim is optional and of type character(len=*)
  • fmt is optional, may be one of REAL_FMTS
  • stat is optional and of type integer
  • errmsg is optional and of type character(len=*)
  • column_names is optional and of type type(String), allocatable, dimension(:)

For reading textual data into an array into of rank 1 or 2 and of type complex:

call from_file(file, into [, header, locale, delim, fmt, im, stat, errmsg, format, &
                           column_names])
  • file is of type character(len=*)
  • header is optional and of type logical
  • locale is optional, may be one of LOCALES
  • delim is optional and of type character(len=*)
  • fmt is optional, may be one of REAL_FMTS
  • im is optional and of type character(len=*)
  • stat is optional and of type integer
  • errmsg is optional and of type character(len=*)
  • column_names is optional and of type type(String), allocatable, dimension(:)

For reading textual data into an array into of rank 1 or 2 and of type logical:

call from_file(file, into [, header, delim, fmt, stat, errmsg, format, column_names])
  • file is of type character(len=*)
  • header is optional and of type logical
  • delim is optional and of type character(len=*)
  • fmt is optional, and may be "tf" (the default) or "bit"
  • stat is optional and of type integer
  • errmsg is optional and of type character(len=*)
  • column_names is optional and of type type(String), allocatable, dimension(:)

With fmt="tf", a cell is read as list-directed input reads a logical: the value is the first letter, T or F in either case, after any blanks and an optional period, so T, .true. and False all read. With fmt="bit", a cell must be 1 or 0. Anything else, including an empty cell, is an error that gives the cell's row and column.

For reading textual data into an array into of rank 1 or 2 and of type String:

call from_file(file, into [, header, delim, stat, errmsg, format, column_names])
  • file is of type character(len=*)
  • header is optional and of type logical
  • delim is optional and of type character(len=*)
  • stat is optional and of type integer
  • errmsg is optional and of type character(len=*)
  • column_names is optional and of type type(String), allocatable, dimension(:)

Each cell becomes one element, unquoted as read_file does. Text data can only be read from a text file, so read character data into a String array.

For reading binary data into an array into of any rank 1-15 and of type integer, real, complex:

call from_file(file, into, data_shape [, stat, errmsg, format])

For reading a NumPy .npy file, which records its own shape, into an array into of any rank 1-15 and of type integer, real, complex or logical:

call from_file(file, into [, stat, errmsg, format])

For reading the array name in a NumPy .npz archive into an array into of the same types and ranks:

call from_file(file, into [, name, stat, errmsg, format])

data_shape may also be passed for a .npy or .npz file, and must then match the array.

  • file is of type character(len=*)
  • data_shape is of type integer, dimension(:)
  • name is optional and of type character(len=*)
  • stat is optional and of type integer
  • errmsg is optional and of type character(len=*)

Note

file may be a relative path, but absolute paths are not guaranteed to work on every platform.

Warning

In all cases, into must be allocatable, and will lose its allocation status upon passing into from_file if already allocated. As a result, from_file does not allow reading into sections of already allocated arrays.

Note

When reading raw binary data, data_shape must be present and its size must equal the rank of into.

Optional Arguments

Header (default is .false.): specifies whether a header line is present.

Name: the name of the array to read from a .npz archive, as NumPy gives it: numpy.savez("data.npz", x=x) stores x under "x". A name ending in .npy also matches, as with numpy.load, and trailing blanks are ignored. It may be left out when the archive holds one array. It is an IOFL_ARG_ERR for any other file, or when the archive holds several arrays and name is absent. npz_names lists the names in an archive:

real, allocatable :: x(:,:)

call from_file("data.npz", into=x, name="x")

Column names: returns the header line's cells, one per column, with any quotes around a cell removed, as read_file does. It implies header=.true., so it may be given without header. Giving it with header=.false., or for a .npy or .npz file, which has no header, is an IOFL_ARG_ERR:

type(String), allocatable :: names(:)
real, allocatable :: x(:,:)

call from_file("data.csv", into=x, column_names=names)   ! names(j) is the name of column j

Locales (default is "US"):

LOCALES = [ "US", "EU" ]

Delimiter: data separator. Default is a tab for a .tsv file. For other files, it is "," for integer data and for real/complex data with "US" locale, and ";" for real/complex data with "EU" locale. It is always recommended to omit the delimiter argument for default unless a custom delimiter is really necessary. If x has rank 1 and the data is ordered down the rows, then the delim argument is ignored.

Integer formats (default is "i"):

INT_FMTS = [ "i", "z" ]

Real formats (default is "e"):

REAL_FMTS = [ "e", "f", "z" ]

Imaginary unit: im specifies the form of a complex number. If not present, complex numbers will be assumed to be written as ordered pairs, e.g. (2.45,3.45).

Empty cells: an empty or blank cell in real or complex data reads as NaN, including a cell missing from a short row. For integer data, which has no NaN, it is an error. Any other text that is not a valid number is an error, and errmsg gives the text with its row and column.

Format: format is optional, and may be "text", "binary", "npy" or "npz". If it is not present, the format comes from the file extension.