READ_ASCII

The READ_ASCII function reads data from an ASCII file into an IDL structure variable. READ_ASCII may be used with templates created by the ASCII_TEMPLATE function.

This routine handles ASCII files consisting of an optional header of a fixed number of lines, followed by columnar data. One or more rows of data constitute a record. Each data element within a record is considered to be in a different column, or field. The data in one field must be of, or promotable to, a single type (e.g., FLOAT). Adjacent fields may be collected into multi-column fields, called groups. Files may also contain comments, which exist between a user-specified comment string and the corresponding end-of-line.

READ_ASCII is designed to be used with templates created by the ASCII template function.

This routine is written in the IDL language. Its source code can be found in the file read_ascii.pro in the lib subdirectory of the IDL distribution.

Examples

To read ASCII data using default file attributes, except for setting the number of skipped header lines to 10, type:

data = READ_ASCII(file, DATA_START=10)

To use a template to define file attributes, overriding the number of skipped header lines defined in the template, type:

data = READ_ASCII(file, TEMPLATE=template, DATA_START=10)

To use the ASCII_TEMPLATE GUI to generate a template within the function, type:

data = READ_ASCII(myfile, TEMPLATE=ASCII_TEMPLATE(myfile))

Working with a READ_ASCII Data Structure

READ_ASCII returns a structure containing ASCII data, which is formatted according to specified keywords or a template. The following example returns a structure containing the data in the sine_waves.txt file, found in the examples/data subdirectory of the IDL installation directory.

  1. Enter the following statement at the IDL command line to open the ASCII Template dialog:

    sTemplate = ASCII_TEMPLATE()

  2. Complete the steps described in Using the ASCII Template Dialog to define the format of the data.

  3. Use READ_ASCII to access the data, defined by the template created in the previous step:

    data = READ_ASCII(FILEPATH('sine_waves.txt', $

       SUBDIRECTORY=['examples', 'data']), TEMPLATE = sTemplate)

  4. The variable data now contains the ASCII data. Use the format structureName.fieldName to access individual fields of data. The following lines plot each data field in an iPlot display:

    iPLOT, data.SmoothSine

    iPLOT, data.NoisySine, color = [255, 0, 0], /OVERPLOT

Note: The Variable Watch window contains the sTemplate and data structures. Expand these items for information about the structure fields.

Syntax

Result = READ_ASCII( [Filename] [, COMMENT_SYMBOL=string] [, COUNT=variable] [, DATA_START=lines_to_skip] [, DELIMITER=string] [, HEADER=variable] [, MISSING_VALUE=value] [, NUM_RECORDS=value] [, RECORD_START=index] [, TEMPLATE=value] [, /VERBOSE] )

Return Value

The result is an IDL structure array containing the data. Each field in the structure corresponds to a different column of data and each element in the array corresponds to a different record (a row of data).

Arguments

Filename

A string containing the name of an ASCII file to read into an IDL variable. If filename is not specified, a dialog allows the user to choose a file.

Keywords

You can define the attributes of a field in two ways. If you use a template, you can either use a previously generated template, or create a template with ASCII_TEMPLATE. You can use COMMENT_SYMBOL, DATA_START, DELIMITER, or MISSING_VALUE to either override template attributes or to provide one-time attributes for the file to be read, without a template.

COMMENT_SYMBOL

Set this keyword to a string that identifies the character used to delineate comments in the ASCII file to be read. When READ_ASCII encounters the comment character, it discards data from that point until it reaches the end of the current line, identifying the rest of the line as a comment. The default character an empty string, ‘’, specifying that no comments will be recognized.

COUNT

Set this keyword equal to a named variable that will contain the number of records read.

DATA_START

Set this keyword equal to the number of header lines you want to skip. The default value is 0 if no template is specified.

DELIMITER

Set this keyword to a string that identifies the end of a field. If no delimiter is specified, READ_ASCII uses information provided by the template in use. The default is a space, ‘ ’, specifying that an empty element constitutes the end of a field.

HEADER

Set this keyword equal to a named variable that will contain the header in a string array of length DATA_START. If no header exists, an empty string is returned.

MISSING_VALUE

Set this keyword equal to a value used to replace any missing or invalid data. The default value, if no template is supplied, is !VALUES.F_NAN. See !VALUES for details.

NUM_RECORDS

Set this keyword equal to the number of records to read. The default is to read up to and including the last record.

RECORD_START

Set this keyword equal to the index of the first record to read. The default is the first record of the file (record 0).

TEMPLATE

Use this keyword to specify the ASCII file template (generated by the function ASCII_TEMPLATE), that defines attributes of the file to be read. Specific attributes of the template may be overridden by the following keywords: COMMENT_SYMBOL, DATA_START, DELIMITER, MISSING_VALUE.

VERBOSE

Set this keyword to print runtime messages.

Version History

5.0

Introduced

See Also

ASCII_TEMPLATE, IOPEN, QUERY_ASCII