shnitsel.io.format_reader_base

Attributes

_default_trajid_pattern_regex

Classes

FormatInformation

Information to keep track of relevant information for

FormatReader

Abstract base class for all input formats to define a unified input reader interface.

Module Contents

class FormatInformation

Information to keep track of relevant information for

format_name: str = 'none'
version: str = 'none'
trajid: int | None = None
path: pathlib.Path | None = None
_default_trajid_pattern_regex
class FormatReader

Bases: abc.ABC

Abstract base class for all input formats to define a unified input reader interface.

Should be subclassed and the functions check_path_for_format_info() and read_from_path() overridden in the subclass

abstractmethod find_candidates_in_directory(path)

Function to return a all potential matches for the current file format within a provided directory at path.

Returns:

A list of paths that should be checked in detail for whether they represent the format of this FormatReader. None: No potential candidate found

Return type:

List[PathOptionsType]

Parameters:

path (shnitsel.io.helpers.PathOptionsType)

abstractmethod check_path_for_format_info(path, hints_or_settings=None)

Checks if a path is of a given format and returns a struct containing all relevant info for reading the format at this location. Additionally checks configured user settings provided in hints_or_settings whether they are consistent with the file format.

Needs to be overridden by each format.

Parameters:

  • path (os.PathLike) – The path to look for data from the respective method for. Depending on the format, this would need to point to a file or a directory containing the actual trajectory information

  • hints (Dict|None, optional) – Potential hints/configuration options provided by the user as input to the reader which can be checked for conflicts with the requirements of the format (i.e. requesting a static initial condition from a dynamic trajectory in SHARC). Defaults to None

  • hints_or_settings (Dict | None)

Raises:

  • FileNotFoundError – If required files were not found, i.e. if the path does not actually constitute input data of the denoted format

  • ValueError – If the hints/settings provided by the user conflict with the requirements of the format

Returns:

A structure containing all of the information relevant to the interpretation or reading of the format. Can be used to differentiate different versions of the same format. Should be passed to the read_from_path() method of the same class.

Return type:

FormatInformation

abstractmethod read_from_path(path, format_info, loading_parameters=None)

Method to read a path of the respective format (e.g. ) into a shnitsel-conform trajectory.

The return value of type Trajectory is a wrapper for the raw xarray.Dataset read from the path. This allows provision of extra features like keeping track of the original data while post-processing is performed.

Parameters:

  • path (pathlib.Path) – Path to either the input file or input folder to be read.

  • format_info (FormatInformation) – Format information previously constructed by check_path_for_format_info(). If None, will be constructed by calling Self.check_path_for_format_info() first. Defaults to None.

  • loading_parameters (shnitsel.io.helpers.LoadingParameters | None) – (LoadingParameters|None, optional): Loading parameters to e.g. override default state names, units or configure the error reporting behavior

Raises:

  • FileNotFoundError – If required files were not found, i.e. if the path does not actually constitute input data of the denoted format

  • ValueError – If the format_info provided by the user conflicts with the requirements of the format

  • Valueerror – If neither path nor format_info are provided

Returns:

The parsed dataset as wrapper around xarray.Dataset to keep track of original data.

Return type:

Trajectory

read_trajectory(path, format_info=None, loading_parameters=None)

Wrapper function to perform some potential initialization and finalization on the read trajectory objects.

Uses the format-specific self.read_from_path() method to read the trajectory and then performs some standard post processing on it.

Parameters:

  • path (PathOptionsType, optional) – Path to either the input file or input folder to be read.

  • format_info (FormatInformation, optional) – Format information previously constructed by check_path_for_format_info(). If None, will be constructed by calling Self.check_path_for_format_info() first. Defaults to None.

  • loading_parameters (shnitsel.io.helpers.LoadingParameters | None) – (LoadingParameters|None, optional): Loading parameters to e.g. override default state names, units or configure the error reporting behavior

Raises:

  • FileNotFoundError – If required files were not found, i.e. if the path does not actually constitute input data of the denoted format

  • ValueError – If the format_info provided by the user conflicts with the requirements of the format

  • Valueerror – If neither path nor format_info are provided

Returns:

Returns a wrapped Trajectory/xr.Dataset object with standard units, only assigned variables remaining and all

variables with appropriate attributes. If no result was obtained by the call to self.read_from_path(), it will return None.

Return type:

Trajectory|None

abstractmethod get_units_with_defaults(unit_overrides=None)

Apply units to the default unit dictionary of the format

Parameters:

unit_overrides (Dict[str, str] | None, optional) – Units denoted by the user to override format default settings. Defaults to None.

Raises:

NotImplementedError – The class does not provide this functionality yet

Returns:

The resulting, overridden default units

Return type:

Dict[str, str]

get_loading_parameters_with_defaults(base_loading_parameters)

Populate loading parameters with default settings for this format

Parameters:

base_loading_parameters (LoadingParameters | None) – User-provided parameter overrides

Returns:

The default parameters modified by user overrides

Return type:

LoadingParameters