output

Read, write and convert self-describing analysis tables.

Summary

Exceptions:

AnalysisOutputError

Raised when an analysis table cannot be read, written or converted.

Classes:

AnalysisDataWriter	Base writer that preserves native formatting and adds table exports.
AnalysisOutputFormat	Supported analysis-table output formats.
AnalysisTable	A validated numerical table with scientific column metadata.
AnalysisTableWriter	Write an AnalysisTable using a suffix-selected format.

Functions:

convert_analysis_output	Convert one analysis table to one or more output files.
infer_output_format	Infer a requested output format from a recognized filename suffix.
read_analysis_table	Read native, CSV, TSV or XVG analysis data by content.
write_analysis_table	Write an analysis table to an open text stream.

__all__: AnalysisColumn, AnalysisDataWriter, AnalysisOutputError, AnalysisOutputFormat, AnalysisPlotPreset, AnalysisSchema, AnalysisTable, AnalysisTableWriter, BROADENED_SPECTRUM_SCHEMA, MOMENTUM_SCHEMA, MSD_SCHEMA, RDF_SCHEMA, VACF_SCHEMA, VACF_SPECTRUM_SCHEMA, VACF_WINDOWED_SCHEMA, VIBRATIONAL_IR_SCHEMA, VIBRATIONAL_SCHEMA, convert_analysis_output, infer_output_format, normal_mode_schema, read_analysis_table, write_analysis_table

Reference

exception AnalysisOutputError

Bases: PQException

Raised when an analysis table cannot be read, written or converted.

class AnalysisDataWriter(

filename: str | None,

mode: str | FileWritingMode = 'w',

export_files: Sequence[str] | None = None,

)

Bases: BaseWriter

Base writer that preserves native formatting and adds table exports.

Parameters:

• filename (str | None) – Primary output path, or None for native text on stdout.

• mode (str | FileWritingMode, optional) – Output writing mode, by default w.

• export_files (Sequence[str] | None, optional) – Additional distinct output paths, by default None.

write_table(

table: AnalysisTable,

native_writer: Callable[[TextIO | StringIO], None],

) → None

Write the primary file and all requested additional exports.

schema: AnalysisSchema

class AnalysisOutputFormat(*values)

Bases: str, Enum

Supported analysis-table output formats.

CSV = 'csv'

NATIVE = 'native'

TSV = 'tsv'

XVG = 'xvg'

class AnalysisTable(

schema: AnalysisSchema,

data: ndarray,

)

Bases: object

A validated numerical table with scientific column metadata.

classmethod from_columns(

schema: AnalysisSchema,

columns: Sequence[Sequence[Real] | ndarray],

) → AnalysisTable

Build a table from equally sized one-dimensional columns.

column(field: str) → ndarray

Return one data column selected by its stable field identifier.

data: ndarray

schema: AnalysisSchema

class AnalysisTableWriter(

filename: str,

mode: str | FileWritingMode = 'w',

)

Bases: BaseWriter

Write an AnalysisTable using a suffix-selected format.

Parameters:

• filename (str) – Output path whose suffix selects the format.

• mode (str | FileWritingMode, optional) – Output writing mode, by default w. Append mode is only valid for native text.

write(

table: AnalysisTable,

x_field: str | None = None,

y_fields: Sequence[str] | None = None,

) → None

Write a table and close the output stream.

convert_analysis_output(

input_file: str,

output_files: Sequence[str],

x_field: str | None = None,

y_fields: Sequence[str] | None = None,

mode: str | FileWritingMode = 'w',

) → None

Convert one analysis table to one or more output files.

Parameters:

• input_file (str) – Native, CSV, TSV or PQAnalysis XVG input table.

• output_files (Sequence[str]) – Distinct output paths. Each suffix selects its format.

• x_field (str | None, optional) – XVG x-axis field override, by default None.

• y_fields (Sequence[str] | None, optional) – XVG y-axis fields, by default None.

• mode (str | FileWritingMode, optional) – Output writing mode, by default w.

infer_output_format(

filename: str | None,

) → AnalysisOutputFormat

Infer a requested output format from a recognized filename suffix.

Unrecognized suffixes and stdout retain the native PQAnalysis format.

Parameters:

filename (str | None) – Requested output filename, or None for stdout.

Returns:

Format selected from the case-insensitive suffix.

Return type:

AnalysisOutputFormat

read_analysis_table(

filename: str,

) → AnalysisTable

Read native, CSV, TSV or XVG analysis data by content.

Parameters:

filename (str) – Input table. Its extension is not used for format detection.

Returns:

Numeric data and reconstructed scientific schema.

Return type:

AnalysisTable

Raises:

AnalysisOutputError – If metadata, headers or numeric rows are malformed.

write_analysis_table(

table: AnalysisTable,

file: TextIO | StringIO,

output_format: AnalysisOutputFormat,

x_field: str | None = None,

y_fields: Sequence[str] | None = None,

) → None

Write an analysis table to an open text stream.

Parameters:

• table (AnalysisTable) – Validated data and scientific schema.

• file (TextIO) – Open UTF-8 text stream.

• output_format (AnalysisOutputFormat) – Format to write.

• x_field (str | None, optional) – XVG x-axis field override, by default None.

• y_fields (Sequence[str] | None, optional) – XVG y-axis fields, by default None.