# Reading Data from ASCII Tables

The ASCII Table reader reads in a flat ascii file with one record per line. Each line of the file is identified as a record or non-record. Autoplot URIs are the name of the ascii file and parameters that specify how to parse the file, listed below. A GUI is also provided that allows the URI to be created graphically. This does not provide access to all the available controls, but is much easier to use.

- mime type: text/plain
- extensions: .dat, .txt, .csv
- example URLs:

    ftp://nssdcftp.gsfc.nasa.gov/spacecraft_data/omni/omni2_1963.dat&column=field17
    ftp://nssdcftp.gsfc.nasa.gov/spacecraft_data/omni/omni2_$Y.dat?time=field0&timeFormat=$Y+$d+$H&column=field17
    http://goes.ngdc.noaa.gov/data/avg/2004/A1050412.TXT?skip=23&timeFormat=$y$m$d+$H$M&column=E1&time=YYMMDD

    ftp://nssdcftp.gsfc.nasa.gov/spacecraft_data/omni/omni2_$Y.dat?column=field17&timerange=1963&timeFormat=$Y+$j+$H&time=field0&validMax=999

- parameters
  - fixedColumns an optimized parser should be used since each row of the file has a fixed column width. By default the row are split into columns using a delimiter. The value may take several forms:
    - value contains ",": specify column locations as in "0-10,20-34"
    - value is int: specify the number of columns in each row. Actual may be less.
    - value is unspecified: the first row is split to determine the column locations.
  - columnCount override the number of columns.
  - column identifies the field in each record to treat as the dependent variable. By default the columns are named field0, field1, field2, etc.
  - depend0 identifies a field as the independent variable.
  - rank2 when in the URL indicates that the dataset produced should be a rank 2 dataset, and the number of fixed columns indicates the number of elements per row. When the value contains a colon (:), this indicates a range. The range is <firstColumn>:<lastColumn exclusive> or <firstColumn>-<lastColumn inclusive>.
    - value may be empty, meaning use all columns
    - 1: means the second row and up.
    - -5: means the last five rows.
    - 20:24 means the four rows starting at the 21st row.
    - field3:field6 three columns
    - B_x_gsm-B_z_gsm three columns.
  - depend1Labels indicates the first record contains the labels for the rank 2 dataset. (<firstColumn>:<lastColumn exclusive>)
  - depend1Values indicates the first record contains the values for the rank 2 dataset (so it is displayed as a spectrogram). (<firstColumn>:<lastColumn exclusive>)
  - skip is an integer indicating the number of lines that should be skipped before processing begins.
  - fill is the number that indicates missing or fill data.
  - timeFormat specifies the time format, based on the Unix `date` command. "ISO8601" means the times are ISO8601 conforment, or use template with fields from [1].
  - time specifies the field that is the time record. This also sets the independent variable.
  - delim identifies the delimiter character. By default, the first record is inspected for commas, tabs and then whitespace.
  - comment prefix string that indicates records to ignore.
  - fill values to be treated as fill data.

# ASCII Table Data Source Editor Panel

A GUI editor can be used to make it easier to read in data. A table is displayed showing how the reader would parse the file. Darker lines that are not broken into columns are lines identified as non-records, such as header lines. Here is an explaination of the controls:

## header tab: identify records and non-records.

Skip Lines: the number of lines to skip before attempting to parse records. Press "Select" then click on the first parseable line.
Comment Prefix: lines starting with this are treated as non-records.

## times tab: specify how times are parsed

Time Format: format for interpretting times. For example "$Y $m $d" means the first three fields are interpretted as year, month, and day. "$Y$m$d" means the first field is an 8-digit date. Press "Select" and highlite the fields in one of the records. This will copy the fields up into the Time Format text field. Then in the text field, highlite each field and use the droplist to identify the field type. Note if the field is already ISO8601 compliant, the parser should not need the time format to be specified.

## data: identify data to plot and interdependence.

Column: the column to plot. Note if the first record is column labels, then these labels can be used to identify columns. Press "Select", then click on a field to select the column. If a several adjacent fields are selected, then a rank 2 table is plotted (e.g. as a spectrogram)
Depends On: the column that tags the column to plot. This is the independent parameter upon which the dependent parameter depends. Press "Select" then click on the field to select the column.
Time checkbox: identify the "Depends On" as times.

# Formatting to ASCII Tables

Data can also be formatted to ascii tables. Presently data is formatted to a comma-separated-values (csv) file, and no formatting options are provided. Use Autoplot's "File->Export Data", then select a file name with a .csv, .dat, or .txt extension. this page in the wiki