Managing IN/OUT data

Utilities for simple file I/O used in examples and scripts: saving/loading dictionaries, appending columns to plain-text tables, reading columnar data, and exporting sparse matrices.

Utilities for saving and loading dictionaries, tabular text data, and sparse matrices.

This module provides lightweight I/O helpers used by examples and scripts:

  • store Python dictionaries with pickle or NumPy .npz archives,

  • append data series to a simple comma-separated text file format,

  • read tabular text files back into NumPy arrays,

  • export sparse matrices to a human-readable .dat file.

edlgt.tools.manage_data.save_dictionary(dictionary, filename, file_format=None, compressed=True)[source]

Serialize a dictionary to a pickle file or NumPy .npz archive.

Parameters:

  • dictionary (dict) – Dictionary to save.

  • filename (str) – Output file path. If file_format is omitted, the archive format is inferred from the extension: .npz selects the NumPy archive path, while every other extension defaults to pickle.

  • file_format (str or None, optional) – Explicit archive format. Supported values are "pickle"/"pkl" and "npz". When omitted, the format is inferred from filename.

  • compressed (bool, optional) – Compression flag used only for .npz archives. It is ignored for pickle output.

Returns:

Final archive filename written to disk. For .npz archives the suffix is appended automatically when missing.

Return type:

str

Raises:

  • TypeError – If dictionary, filename, file_format, or compressed has an invalid type.

  • ValueError – If file_format is unsupported or if a value cannot be represented safely in .npz format.

Notes

The .npz path is intended for flat dictionaries of array-like values. Nested Python objects should be stored with pickle instead.

edlgt.tools.manage_data.load_dictionary(filename, file_format=None)[source]

Load a dictionary stored with pickle or as a NumPy .npz archive.

Parameters:

  • filename (str) – Path to the stored dictionary. If file_format is omitted, .npz files are detected from the extension. When file_format="npz", the suffix is added automatically if missing. For convenience, a bare file name also resolves to filename + ".npz" when that archive exists.

  • file_format (str or None, optional) – Explicit archive format. Supported values are "pickle"/"pkl" and "npz". When omitted, the format is inferred from filename.

Returns:

Deserialized dictionary. For .npz archives, 0-dimensional arrays are converted back to Python scalars while higher-dimensional entries are returned as NumPy arrays.

Return type:

dict

Raises:

  • TypeError – If filename or file_format has an invalid type.

  • ValueError – If file_format is unsupported.

edlgt.tools.manage_data.save_data_in_textfile(data_file, x_data, new_data)[source]

Append a data series as a new column in a simple text table.

The file format is line-based and comma-separated. On first write, the file is created and initialized with the values from x_data (usually an x-axis label followed by x values). On subsequent writes, each line gets one extra comma-separated entry from new_data.

Parameters:

  • data_file (str) – Path to the text file to create/update.

  • x_data (list) – Reference column written when the file does not yet exist. Conventionally the first item is a label and the remaining items are x values.

  • new_data (list) – Column to append to the file. It must contain the same number of entries as the current file line count. Conventionally the first item is a label.

Return type:

None

Raises:

TypeError – If the input arguments have invalid types.

Notes

This helper assumes x_data and new_data are already aligned line by line. It does not validate lengths or parse values.

edlgt.tools.manage_data.load_data_from_textfile(data_file_name, row_for_labels=False)[source]

Load columnar numeric data from a comma-separated text file.

Parameters:

  • data_file_name (str) – Path to the input file.

  • row_for_labels (bool, optional) – If True, interpret the first line as column labels and store them as "label_0", "label_1", … entries in the returned dictionary. Default is False.

Returns:

Dictionary containing one NumPy array per column under string keys "0", "1", … . If row_for_labels is True, label entries are also included.

Return type:

dict

Raises:

TypeError – If data_file_name or row_for_labels has an invalid type.

Notes

Data values are converted to float. This helper expects a regular comma-separated table with the same number of columns on each line.

edlgt.tools.manage_data.save_sparse_matrix_to_dat(sparse_matrix, filename)[source]

Export a sparse matrix to a human-readable .dat text file.

The output contains:

  • a header line with the matrix dimension,

  • one line per non-zero entry with row/column indices and complex value.

Parameters:
Return type:

None

Raises:

TypeError – If sparse_matrix or filename has an invalid type.