SDDS Modules

Classes

This module holds classes to handle different namelist commands in an SDDS file. Implementation are based on documentation at: https://ops.aps.anl.gov/manuals/SDDStoolkit/SDDStoolkitsu2.html

Array (&array) command container, a data definition.

This optional command defines an array that will appear along with the tabular data section of each data page.

Fields:

field_length (int): Optional. Length of the field (Not sure, actually. jdilly2022). group_name (int): Optional. Allows specification of a string giving the

name of the array group to which the array belongs; such strings may be defined by the user to indicate that different arrays are related (e.g., have the same dimensions, or parallel elements).

dimensions (int): Optional. Gives the number of dimensions in the array.: If not given, defaults to 1 upon reading.

class sdds.classes.Column(name: str, type: str, symbol: str | None = None, units: str | None = None, description: str | None = None, format_string: str | None = None)[source]

Column (&column) command container, a data definition.

This optional command defines a column that will appear in the tabular data section of each data page.

class sdds.classes.Data(mode: str)[source]

Data (&data) command container.

This command is optional unless parameter commands without fixed_value fields, array commands, or column commands have been given.

Fields:: mode (str): File/Data mode. Either “binary” or “ascii”.

class sdds.classes.Definition(name: str, type: str, symbol: str | None = None, units: str | None = None, description: str | None = None, format_string: str | None = None)[source]

Abstract class for the common behaviour of the data definition commands.

The Column, Array and Parameter definitions inherit from this class. They can be created just by passing name and type and optionally more parameters that depend on the actual definition type.

Fields:

name (str): Name of the data. type (str): Type of the data.

One of “short”, “long”, “float”, “double”, “character”, or “string”.

symbol (str): Optional. Allows specification of a symbol to represent the parameter;: it may contain escape sequences, for example, to produce Greek or mathematical characters.

units (str): Optional. Allows specification of the units of the parameter. description (str): Optional. Provides for an informal description of the parameter. format_string (str): Optional. Specification of the print format string to be used to print the data

(e.g. for ASCII in SDDS or other formats).

get_key_value_string() → str[source]

Return a string with comma separated key=value pairs.

Hint: ClassVars (like TAG) are ignored in fields.

class sdds.classes.Description(text: str | None = None, contents: str | None = None)[source]

Description (&description) command container.

This optional command describes the data set in terms of two strings. The first, text, is an informal description that is intended principally for human consumption. The second, contents, is intended to formally specify the type of data stored in a data set. Most frequently, the contents field is used to record the name of the program that created or most recently modified the file.

Fields:: text (str): Optional. Informal description intended for humans. contents (str): Optional. Formal specification of the type of data stored in a data set.

class sdds.classes.Include(filename: str)[source]

Include (&include) command container.

This optional command directs that SDDS header lines be read from the file named by the filename field. These commands may be nested.

Fields:: filename (str): Name of the file to be read containing header lines.

Parameter (&parameter) command container, a data definition.

This optional command defines a parameter that will appear along with the tabular data section of each data page.

Fields:

fixed_value (str): Optional. Allows specification of a constant value for a given parameter.: This value will not change from data page to data page, and is not specified along with non-fixed parameters or tabular data. This feature is for convenience only; the parameter thus defined is treated like any other.

class sdds.classes.SddsFile(version: str, description: Description | None, definitions_list: List[Definition], values_list: List[Any])[source]

Holds the contents of the SDDS file as a pair of dictionaries.

The first dictionary “definitions” has the form: name (str) -> Definition, containing an object of each field in the SDDS file (of type Parameter, Array or Column). The “values” dictionary has the form: name (str) -> value. To access them: sdds_file = SddsFile(...).

def_ = sdds_file.definitions["name"]
val = sdds_file.values["name"]
# The definitions and values can also be accessed like:
def_, val = sdds_file["name"]

Parameters:

version (str) -- Always needs to be “SDDS1”!
description (Description) -- Optional. Description Tag.
definitions_list (list[Definition]) -- List of definitions objects, describing the data.
values_list (list[Any]) -- List of values for the SDDS data. Same lengths as definitions.

Fields:: version (str): Always needs to be “SDDS1”! description (Description): Optional. Description Tag. definitions (dict[str, Definition]): Definitions of the data, mapped to their name. values (dict[str, Any]): Values of the data, mapped to their name.

Reader

This module contains the reading functionality of sdds. It provides a high-level function to read SDDS files in different formats, and a series of helpers.

sdds.reader.read_sdds(file_path: ~pathlib.Path | str, endianness: str | None = None, opener: ~collections.abc.Callable[[~os.PathLike], ~contextlib.AbstractContextManager[~typing.IO]] = functools.partial(<built-in function open>, mode='rb')) → SddsFile[source]

Reads an SDDS file from the specified file_path.

Parameters:

file_path (Union[pathlib.Path, str]) -- Path object to the input SDDS file. Can be a string, in which case it will be cast to a Path object.
endianness (str) -- Endianness of the file, either ‘big’ or ‘little’. If not given, the endianness is either extracted from the comments in the header of the file (if present) or determined by the machine you are running on. Binary files written by this package are all big-endian, and contain a comment in the file.
opener (OpenerType) -- Callable to open the SDDS file. Uses open(file, mode=”rb”) by default. One can use provided openers for specific format or bring their own, see the examples below.

Returns:

An SddsFile object containing the loaded data.

Examples

To read a typical file, one can use the default options:

import sdds

data = sdds.read("some/location/to/file.sdds")

To read a gzip-compressed file, use the provided opener function:

import sdds
from sdds.reader import gzip_open

data = sdds.read("some/location/to/file.sdds.gz", opener=gzip_open)

To read another specific compression format, bring your own opener abstraction. It should take a single parameter for the path-like object pointing to the file, and return a context manager providing byte-data of the file. For instance the gzip_opener from the example above is built as functools.partial(gzip.open, mode=”rb”).

import sdds
from functools import partial
from relevant_module import opening_function

your_opener = partial(opening_function, some_option)
data = sdds.read("some/location/to/file.sdds.extension", opener=your_opener)

Writer

This module contains the writing functionality of sdds. It provides a high-level function to write SDDS files in different formats, and a series of helpers.

sdds.writer.write_sdds(sdds_file: SddsFile, output_path: Path | str) → None[source]

Writes SddsFile object into output_path. The byteorder will be big-endian, independent of the byteorder of the current machine.

Parameters:

sdds_file -- SddsFile object to write
output_path (Union[pathlib.Path, str]) -- Path object to the output SDDS file. Can be a string, in which case it will be cast to a Path object.