tecio.cli.tectable

tecio.cli.tectable#

Convert a delimited text table to ordered Tecplot zones.

Simplify loading plain text tables into Tecplot with some additional tools that operate on database-like text tables from a command-line interface.

Automatically parse numeric columns to ordered zone variables variables. While text columns cannot be represented in data arrays, if every entry of the column is the same within a zone, the text is stored as zone-level auxiliary data column_header=column_text and otherwise automatically skipped. Database parsing tools allow families of data to be grouped my constant values similar to pivot tables with -g/--group. The group values are stored in each zone as auxiliary data, and in its title. For data that is a function of two or more independent variables, optional -m/--mesh allow the uesr to specify columns containing one-dimensional coordinate arrays to be converted to N-dimensional IJ(K) ordered arrays (such as a surface of a coefficient over two angles). The user may filter data that is written to file with --filter supporting all math comparison operators.

Usage:

tectable [-h] [-o PATH] [-f] [-d DELIMITER] [--header {auto,yes,no}]
         [-n NAMES] [--filter EXPR [--filter ...]] [-g COLUMN [-g ...]]
         [-r | --no-sort] [--keep-group] [-m COLUMN [-m ...]]
         [--precision {auto,single,double}] [--comment PREFIX] [PATH]
Positional Arguments:
PATH

Path to the delimited text table. Use - or leave it out to read standard input.

Options:
-o PATH, --output PATH

Output file path. The extension determines the output format (either .szplt, .plt, or .dat). Defaults to the input path with the extension .szplt, or to table.szplt when reading standard input.

-f, --force

Overwrite the output file if it already exists. Files are not overwritten by default.

-d DELIMITER, --delimiter DELIMITER

Field separator: comma, space (any run of spaces and tabs), tab, or a single character such as ;. The default, auto, picks comma if the first line holds a comma and space otherwise. Spaces around the fields are removed, and fields may be quoted with ".

--header {auto,yes,no}

Whether the first line holds the column names. With auto, the first line is a header if a column that is numeric in the other rows is not numeric there. Without a header the variables are named V1, V2, and so on.

-n NAMES, --names NAMES

Comma-separated column names, replacing the header. A header line is then dropped only with --header yes.

--filter EXPR

Keep only the rows where COLUMN OP VALUE holds, with OP one of ==, !=, <, <=, > and >=. The column is named exactly as in the header (case-sensitive), so quote the expression in a shell, for example --filter 'Alpha!=0'. Text columns support == and != only. Repeatable: a row is kept if it satisfies all of the filters. Missing values (NaN) fail every comparison except !=.

-g COLUMN, --group COLUMN

Split the rows into zones by the values of this column, named exactly as in the header (case-sensitive). Names with spaces are quoted in the shell, for example -g "Mach number". Repeatable: with several columns, rows are grouped by the first, then by the second within each of those, and so on. Zones are ordered by the group values, numerically for numeric columns and alphabetically for text columns. Rows keep their file order within a zone.

-r, --reverse

Order the zones by descending group values.

--no-sort

Order the zones by the first appearance of each group in the table.

--keep-group

Keep numeric group columns as variables. By default they are dropped, since each zone holds a single constant value that is stored as auxiliary data.

-m COLUMN, --mesh COLUMN

Write each zone as an IJ (two columns) or IJK (three columns) ordered zone instead of a list of points. The first column varies fastest. Every zone must hold each combination of the distinct values of these columns exactly once, which is a complete, not necessarily square, grid. Otherwise the command fails and names the zone. The columns must be numeric and not be group columns. They stay in the file as variables.

--precision {auto,single,double}

Data type of the variables. With auto a column of whole numbers is stored as the smallest of uint8, int16 and int32 that holds it. Any other column is stored in single precision if every value has at most 6 significant digits, which single precision holds as written, and in double precision otherwise. .szplt files choose per variable. A .dat file chooses the integer types per variable, and one precision for its other variables. A .plt file has no integer variables, and one precision for all of them. Use single or double to store every variable as a float of that precision. Default auto.

--comment PREFIX

Ignore text from this prefix to the end of a line. Default #. An empty string turns it off.

Returns:

A Tecplot file with one ordered zone per group, or one zone without -g. Exit code 0 on success and non-zero if the input cannot be read or parsed, a column cannot be resolved, a filter removes every row, a mesh is not complete, no numeric column remains, or the output file already exists and --force is not set.

Notes

A column is numeric if its first rows (up to 200,000) are all numbers. Empty fields and NA, N/A, null, none and nan are read as NaN, and Fortran D exponents are accepted. Any other text in such a column later in the table is an error.

Text values are matched exactly, apart from the removal of surrounding spaces. Auxiliary data names are the column names with other characters than letters, digits, _ and . replaced by _. Text columns that vary within some zone are skipped in that zone, with a note on standard error.

Examples

Convert a CSV file with a header row into results.szplt:

$ tectable results.csv

Read from a pipe, picking the output format by extension:

$ awk '$3 > 0' raw.txt | tectable -o filtered.plt

Split rows into one zone per category, with the category as auxiliary data:

$ tectable -g Category runs.csv

Group by two columns, in descending order of the first:

$ tectable -g Case -g Run -r runs.csv -o runs.szplt

From an aerodynamic database, one zone for each Mach, Altitude and Beta, with the columns Alpha, CX, CY and so on as variables, and the three group values as auxiliary data of the zone:

$ tectable -g Mach -g Altitude -g Beta --filter 'Alpha!=0' aero.csv

Surfaces over Alpha and Beta, one for each Mach and Altitude:

$ tectable -g Mach -g Altitude -m Alpha -m Beta aero.csv

A semicolon separated table without a header:

$ tectable -d ';' -n x,y,p scan.txt -o scan.dat

Call directly from a Python session:

from tecio.cli.tectable import main as tectable

tectable(["-g", "Category", "table.csv", "-o", "table.szplt"])

Without a file, table.szplt is written to the current directory:

$ cat table.csv | tectable

See also

tecio.cli.teconvert - Convert between Tecplot file formats.

Functions

main([argv])

Convert a delimited text table to ordered Tecplot zones.