Analysis Output Files

PQAnalysis analysis commands can write native text, CSV, TSV or XVG tables. The output filename selects the format:

Analysis output formats

Extension	Format	Intended use
.csv	Comma-separated values	Excel, LibreOffice Calc, pandas and other table tools
.tsv	Tab-separated values	Spreadsheets and tables whose values may later contain commas
.xvg	Grace XY data with plot directives	Direct inspection with xmgrace
Any other extension	Native PQAnalysis text	Self-describing scientific data and legacy workflows

This means that out_file table.csv in an RDF, MSD, VACF or vibrations input file writes CSV directly. Names ending in .dat, .out, .txt or no extension retain the native format.

Native format

Column numbers in this reference are one-based. Every native tabular output starts with a compact UTF-8 # metadata block. FIELDS lists one stable ASCII identifier per numeric column, SYMBOLS gives the corresponding scientific notation in Unicode, and UNITS lists the units in the same order. Values remain single whitespace-free tokens; compound units use a middle dot. Examples include ν̃, Å, ų and cm⁻¹. The tables below give the full quantities and definitions. Numeric rows retain the legacy ordering and formatting. Readers such as numpy.loadtxt ignore the comment block automatically and continue to work without special options.

For example, an RDF data file begins with

# PQAnalysis: Radial distribution function
# FIELDS r_i g_r_i N_r_i g_r_i_dV_i H_i_minus_E_i
# SYMBOLS rᵢ g(rᵢ) N(rᵢ) g(rᵢ)ΔVᵢ Hᵢ−Eᵢ
# UNITS Š1 1 ų pairs
0.5 0.0 0.0 0.0 -0.05026548245743666

Log files are labeled, human-readable text and are not described as columnar data here.

CSV and TSV

CSV and TSV files contain one header row followed by numeric rows. The header uses the stable identifiers from the native FIELDS line, for example:

r_i,g_r_i,N_r_i,g_r_i_dV_i,H_i_minus_E_i
0.5,0.0,0.0,0.0,-0.05026548245743666

These files open directly in Excel and LibreOffice Calc and can be read as ordinary CSV or TSV. Scientific symbols, units and definitions are documented by the field identifier in the tables below.

XVG and xmgrace

XVG files contain Grace @ directives and standard XY data-set blocks. They can be opened directly with xmgrace rdf.xvg; PQAnalysis does not launch the GUI itself. Each original analysis-table column is stored as one Grace data set with the selected x axis. Columns outside the selected quick plot are retained as hidden Grace sets. PQAnalysis metadata records the original schema and plot projection, making its XVG output fully convertible back to native, CSV, TSV or XVG without losing analysis columns. The default quick plots are:

Default XVG plots

Analysis table	x axis	y data sets
RDF	r_i	g_r_i
MSD	lag	msd_x, msd_y, msd_z
VACF or windowed correlation	time	Correlation value
VACF or broadened spectrum	wavenumber	Amplitude or intensity
Total momentum	frame	scaled_momentum_norm
Vibrations without IR intensities	One-based mode index	wavenumber
Vibrations with IR intensities	wavenumber	ir_intensity

Additional outputs

All tabular analysis CLIs accept repeatable --export FILE options. The primary output is still controlled by out_file or --output; every export filename independently selects its format.

$ pqanalysis rdf rdf.in \
    --export rdf.csv \
    --export rdf.tsv \
    --export rdf.xvg

The same option is available for msd, vacf, build_spectrum, check_momentum and vibrations. For VACF, --export represents the main correlation table. The configured spectrum_file and windowed_out_file select their own formats from their filenames.

Converting existing output

The converter reads native, CSV, TSV or PQAnalysis-generated XVG analysis tables and can create several outputs in one command:

$ pqanalysis convert rdf.dat \
    -o rdf.csv \
    -o rdf.tsv \
    -o rdf.xvg

The conversion also works in the other direction:

$ pqanalysis convert rdf.xvg \
    -o rdf.out \
    -o rdf.csv

Input format is detected from the file content rather than its extension, so a CSV table named table.dat or an XVG table named table.out can still be converted. Exact FIELDS headers restore the known scientific schema and XVG plot preset. --x FIELD and repeatable --y FIELD options override the default XVG projection without removing unplotted data from the XVG file. Input and output paths, and all output paths, must be distinct.

By default, conversion stops with an error naming the existing file if any output path already exists. No requested output is written in that case. Use --mode o only to request replacement explicitly.

RDF

The rdf command writes five columns to out_file. For bin \(i\), let \(H_i\) be the number of eligible reference-target pairs accumulated over all frames, \(N_R\) the number of reference atoms, \(N_F\) the number of frames and \(\rho_T\) the effective target number density. The bin edges and spherical-shell volume are

\[r_i^- = r_{\min} + i\,\Delta r, \qquad r_i^+ = r_i^- + \Delta r, \qquad \Delta V_i = \frac{4\pi}{3}\left((r_i^+)^3 - (r_i^-)^3\right).\]

The ideal-gas pair count for the shell is \(E_i = \rho_T N_R N_F \Delta V_i\).

RDF out_file columns

Column	Quantity	Definition	Unit
1	Bin-center distance	\(r_i = (r_i^- + r_i^+) / 2\)	Angstrom
2	Radial distribution function	\(g_i = H_i / E_i\)	Dimensionless
3	Cumulative coordination number	\(\sum_{j=0}^{i} H_j / (N_R N_F)\), the average number of eligible target atoms per reference atom up to \(r_i^+\)	Dimensionless
4	Density-normalized shell population	\(H_i / (\rho_T N_R N_F) = g_i\Delta V_i\)	Angstrom3
5	Ideal-gas pair-count residual	\(H_i - E_i\); positive values are an excess and negative values are a deficit relative to the ideal-gas shell count	Pair count

Self pairs are excluded. When no_intra_molecular is enabled, pairs from the same molecule are excluded from \(H_i\) and from the effective target density.

MSD

The msd command writes the legacy Diffcalc layout to out_file.

MSD out_file columns

Column	Quantity	Definition	Unit
1	Lag index	Frame lag from zero through window	Frames
2	\(\mathrm{MSD}_x\)	Mean squared displacement along x	Angstrom2
3	\(\mathrm{MSD}_y\)	Mean squared displacement along y	Angstrom2
4	\(\mathrm{MSD}_z\)	Mean squared displacement along z	Angstrom2

The total MSD is the sum of columns 2 through 4. It is returned by the Python API but is not repeated in the file. If time_step is provided, multiply column 1 by it to obtain lag time in ps. The fitted diffusion coefficients are written to log_file, not out_file.

VACF and charge-flux correlation

The vacf command can write three two-column files. Correlations are normalized by their zero-lag value, including charge-weighted correlations.

VACF out_file columns

Column	Quantity	Definition	Unit
1	Lag time	Frame lag multiplied by time_step	ps
2	Normalized correlation	VACF, or charge-flux autocorrelation when charges are supplied	Dimensionless

VACF spectrum_file columns

Column	Quantity	Definition	Unit
1	Wavenumber	Legacy cosine-transform frequency axis	cm-1
2	Spectrum amplitude	Absolute cosine-transform amplitude of the optionally windowed normalized correlation	Arbitrary units

VACF windowed_out_file columns

Column	Quantity	Definition	Unit
1	Lag time	Same axis as out_file	ps
2	Windowed correlation	Column 2 of out_file multiplied by the selected apodization window	Dimensionless

Broadened spectrum

The build_spectrum command writes two columns to --output or standard output.

build_spectrum output columns

Column	Quantity	Definition	Unit
1	Wavenumber	Regular output grid from --min to the exclusive --max	cm-1
2	Broadened intensity	Sum of the Gaussian or Lorentzian peak-height profiles	Same as the input intensities

The broadening uses a peak-height convention and does not normalize peak area.

Total linear momentum

The check_momentum command writes two columns to --output or standard output.

check_momentum output columns

Column	Quantity	Definition	Unit
1	Frame index	One-based index across all input trajectory files	Frames
2	Scaled momentum norm	scale multiplied by \(\left|\sum_i m_i\mathbf{v}_i\right|\)	Set by --scale; default is amu Angstrom fs-1

Vibrational analysis

The vibrations command writes one required table and up to three optional normal-mode representations.

out_file

Without a moldescriptor_file, the table has three columns. With partial charges, the IR-intensity column is inserted as column 2 and the table has four columns. The file’s FIELDS and UNITS lines reflect the selected layout. The accompanying SYMBOLS line provides the Unicode scientific notation.

Vibrational out_file columns

Column	Quantity	Availability	Unit
1	Signed wavenumber	Always; negative values represent imaginary modes	cm-1
2	IR intensity	Only with partial charges	km mol-1
2 or 3	Force constant	Always	mdyn Angstrom-1
3 or 4	Reduced mass	Always	amu

normal_modes_file

This file contains the normal-mode matrix. Its metadata identifies the matrix element as \(e_{\alpha j}\), the row order as x_1,y_1,z_1,..., and each column as mode_1, mode_2 and so on. Columns are modes in the same order as the rows of out_file. Values are dimensionless normalized Cartesian mode components.

modes_prefix

One multi-frame XYZ animation named <prefix>-<mode>.xyz is written per selected mode. Each atom row contains species, x, y and z in Angstrom. The XYZ comment records the one-based mode number, wavenumber in cm^-1, frame number and sinusoidal phase.

modes_file

This extended XYZ file contains one image per selected mode. The atom columns are species, equilibrium x/y/z coordinates in Angstrom and normalized mode x/y/z components. The comment declares Properties=species:S:1:pos:R:3:mode:R:3 and records the one-based mode number, wavenumber and optional IR intensity.