Using the PlainText reader

Using the PlainText File Format Reader

The PlainText file format reader, in its current form, allows you to load whitespace- or comma-delimited files as either 2D grids, 1D curves, or as a 2- or 3-dimensional point mesh.

Note that there are other file formats which are allow more arbitrary and descriptive formats -- the legacy ASCII VTK file format is the best supported, and is very easy to use for some simple formats. The PlainText reader is intended more for very quick-and-dirty import of data which has been pasted from other sources, or maybe exported as TSV or CSV files from spreadsheet applications.

Note that you may need to set some options for the PlainText reader to change how it parses date. There are two ways to set file format reader options: (A) In Options -> Plugin Manager, in the Databases tab, you can select the PlainText reader and choose "Set default open options", where the next time you open a file, or re-open an already-opened file, it will interpret it with those options. Or, (B) use the File -> Open dialog box, and there is a choice of forcing it to use a given plugin to open a file -- next to that choice, you can set the options directly.

If you have multiple plain text files that you want to convert into a single 3D volume, see Converting Multiple 2D Files Into One 3D File.

Basic Input Format

As of this writing, the format supports two main formats: a 2D grid of data and 1D columns of data. The file can contain only one section of data. Note that the reader plugin has several options; you will likely have to set some of these options (either through the File/Open dialog, or through Options/Plugin Manager) to have it read your data file correctly.

2D Grid Format

The 2D grid format returns a regular grid of scalar data with coordinate values from 0...nc-1 and 0..nr-1 for each axis, respectively.

An example file which could be read with this format could be the 2x3 grid:

1,3,6
4,5,7

... or, with a whitespace delimiter instead of a comma:

1  3 6
4 5  7
1D Columns (as Curves)

The 1D column format returns a selection of 1D scalar ("curve") variables; one for each column. The parametric positions of each point in these curves will be 0..n-1.

An example file which could be read with this format could be the two scalar quantities below, each with three values. This example uses whitespace as a delimiter:

1 2
6 7
9 8

And this version uses a comma delimiter:

1 ,2
6, 7
 9,8
1D Columns (as a Point Mesh)

If you have multiple columns of data and want to interpret some columns as the X, Y (and Z) values of a 2D (or 3D) point mesh, you can use the 1D Columns format, and specify a 0-origin column index of your coordinate data arrays. For example, if your first column is X, second is Y, and third is Z, then you would enter "0", "1", and "2" as the column for the X, Y, and Z coordinates, respectively. You may still have other columns of data, before, after, or interspersed with your coordinate columns.

Advanced Topics and Usage Notes

Header

There is an option which allows you to specify the your first row of data is actually a textual header row. For example, a 1D Column file with a header row could be:

pressure density
6        2
3        6
2        4

For 2D Grids, there is only one scalar and so the header row need only contain a single variable name. For example:

temperature
3 5 6 1
8 7 6 3
2 3 1 9
Delimiter

The PlainText reader detects the delimiter automatically. It checks the first line for the delimiter -- if that first line has any commas, it assumes a comma is the delimiter. If not, it takes any continuous chunk of whitespace as a single delimiter.

The reader does not use fixed-width columns, so there is no need for any care with respect to alignment of each entry. It simply either treats one comma, or one continuous chunk of whitespace, as one delimiter. This does mean that does not support missing values in files very well, and in fact, treats missing values as a sign to stop parsing. (More discussion below.)

Coordinate Values

The 2D Grid version does not support coordinates; it will always return results in a regular grid.

The 1D Columns version does allow you to specify the index of an X, Y, and/or Z column. These are zero-origin values, so the first column will be column index "0". If you have no coordinate columns, use the value "-1" (which is the default). If you have an X/Y or X/Y/Z coordinate value for this format, the data can be plotted as points in 2D or 3D space instead of as 1D curves. There is currently no connectivity between these points.

Starting Parsing Late

The reader has an option allowing you to skip some lines at the beginning of the file before it starts parsing. Note that these lines are skipped before any parsing happens. So if you set the option to have a row of variable names (a header row), and set the option to skip 3 lines of text, then your header row will be the 4th line of the file. Furthermore, those skipped lines will not be used for automatic delimiter detection.

Stopping Parsing Early

The reader stops parsing as soon as it finds a line with the wrong number of values. For example, this file:

1 2 5 6
8 1 4 2
9   6

... and this file:

1,2,5,6
8,1,4,2
garbage text

.... will both be interpreted as having only two lines of data.