libics.core.io

class libics.core.io.base.FileBase

Bases: object

Base class for object serialization and file storage.

Usage:

To enable I/O functionality for custom classes, subclass this base class.
By default the serialization algorithm calls attributes(), which returns a name->value dictionary of the attributes to be serialized. These attributes are given in the class variable SER_KEYS, which is a set containing the respective attribute names.
The subclass should add the required attribute names to this set, i.e. setting SER_KEYS = FileBase.SER_KEYS | {“ATTR0”, “ATTR1”, …}.
Alternatively, the attributes() method itself can be overwritten to obtain more customizability.

Methods

`attributes`()	Default saved attributes getter.
`load`(file_path, **kwargs)	Wrapper for `load()` function.
`save`(file_path, **kwargs)	Wrapper for `save()` function.

SER_KEYS = {}

attributes()

Default saved attributes getter.

Returns

attrsdict(str->object): Saved attributes dictionary mapping the attribute name to the attribute value.

load(file_path, **kwargs)

Wrapper for load() function.

Loads into current object.

save(file_path, **kwargs)

Wrapper for save() function.

Saves current object.

class libics.core.io.base.ID_NOT_SPECIAL: Bases: object

class libics.core.io.base.ObjDecoder

Bases: object

Deserializes a file or dictionary to an object.

For deserialization from file (with metadata), use decode(). For legacy fully qualified name to class map (CLS_MAP), inherit from this class and populate the attribute according to get_class_from_fqname().

Raises

KeyError: If deserialization failed.

Attributes

CLS_MAP

Methods

decode(ser[, obj, req_version, raise_err])

Decodes a dictionary into a deserialized object.

deserialize(ser[, obj, raise_err])

Parameters

CLS_MAP = None

classmethod decode(ser, obj=None, req_version=None, raise_err=True)

Decodes a dictionary into a deserialized object.

Parameters

serdict: File-serialized object.
objobject: If specified, and if the top-level object is a custom class, it is deserialized into this given object.
req_versionNone, float or (float, float): Required libics version. Tuples specify minimum and maximum versions, a single float a minimum version. Raises a RuntimeError if this condition is not fulfilled.
raise_errbool: Flag whether to raise an error on deserialization failure or to proceed silently.

Returns

objobject: Deserialized object.

Raises

RuntimeError: If the required version is not fulfilled.
KeyError: If the serialized object is invalid.

classmethod deserialize(ser, obj=None, raise_err=True)

Parameters

serdict: Dictionary representing serialized object.
objobject: If specified, and if the top-level object is a custom class, it is deserialized into this given object.
raise_errbool: Flag whether to raise an error on deserialization failure or to proceed silently.

Returns

objobject: Deserialized object.

Raises

KeyError: If deserialization failed and raise_err flag is set.

class libics.core.io.base.ObjEncoder

Bases: object

Serializes an object to a file or dictionary.

For serialization to file (with metadata), use encode(). For legacy class to fully qualified name map (CLS_MAP), inherit from this class and populate the attribute according to get_fqname_from_class().

Raises

NotImplementedError: If class of object to be serialized is not supported.

Attributes

CLS_MAP

Methods

encode(obj)

Encodes an object into a serializable format.

serialize

CLS_MAP = None

classmethod encode(obj)

Encodes an object into a serializable format.

Parameters

objobject: Object to be deserialized.

Returns

serdict: Object serialized into a dictionary.

classmethod serialize(obj)

libics.core.io.base.filter_primitive(obj)

Filters primitive types requiring special handling (i.a. np.generic) into Python built-in types.

Parameters

objobject: Object to be filtered.

Returns

objobject: Converted object if applicable, otherwise returns identity.

libics.core.io.base.get_class_from_fqname(fqname, cls_map=None)

Gets the class specified by the given fully qualified class name.

Parameters

fqnamestr: Fully qualified class name (i.e. Python-attribute-style string specifying class), e.g. libics.core.data.arrays.ArrayData.
cls_mapdict(str->cls): Dictionary mapping fully qualified name to a class. Is handled prioritized, so it can be used for legacy purposes, where dependencies have changed.

Returns

_clsclass: Requested class object.

libics.core.io.base.get_file_format(file_path, fmt=None)

Deduces the file format (or returns the format if given).

Raises

KeyError: If format deduction error occured.

libics.core.io.base.get_fqname_from_class(_cls, cls_map=None)

Gets the fully qualified class name from the given class.

Parameters

_clsclass: Class object.
cls_mapdict(cls->str): Dictionary mapping class to a fully qualified name. Is handled prioritized, so it can be used for legacy purposes, where dependencies have changed.

Returns

fqnamestr: Requested fully qualified class name.

Notes

See: https://stackoverflow.com/questions/2020014

libics.core.io.base.load(file_path, obj_or_cls=None, dec=<class 'libics.core.io.base.ObjDecoder'>, fmt=None, req_version=None, raise_err=True, **kwargs)

Loads and deserializes an object from file.

Parameters

file_pathstr: Saved file path.
obj_or_clsobject: Object or class to be deserialized to.
decObjDecoder: Deserialization class.
fmtstr: Supported file formats: “json”, “bson”, “hdf”, “bmp”, “png”, “wct”, “sif”, “mat”.
req_versionNone, float or (float, float): Required libics version. Tuples specify minimum and maximum versions, a single float a minimum version. Raises a RuntimeError if this condition is not fulfilled.
raise_errbool: Flag whether to raise an error on deserialization failure or to proceed silently.
**kwargs: Keyword arguments passed to the loader function.

Returns

objobject: Deserialized object.

libics.core.io.base.save(file_path, obj, enc=<class 'libics.core.io.base.ObjEncoder'>, fmt=None, **kwargs)

Serializes and saves an object to file.

Parameters

file_pathstr: Saved file path.
objobject: Object to be serialized and saved.
encObjEncoder: Serialization class.
fmtstr: File format: “json”, “bson”, “hdf”.
**kwargs: Keyword arguments passed to the respective write functions.

libics.core.io.base.type_is_primitive(obj)

Returns whether the given object is of primitive type.

Notes

complex is not considered a primitive, but a special type.

image

libics.core.io.image.compress_numpy_array_as_png(ar, encode=None)

Compresses an integer array with png.

Parameters

arnp.ndarray(int): Integer numpy array.
encodeNone or str: If str, converts the bytes object into a string. Available formats: “base64”.

Returns

im_datastr: (Encoded) png-compressed array.

libics.core.io.image.decompress_numpy_array_from_png(im_data)

Decompresses an integer array compressed with png.

Parameters

im_databytes or str: If bytes, assumes the png data. If str, assumes an encoding with header describing encoding scheme, e.g. “data:image/png;base64,”.

Returns

arnp.ndarray(int): Decompressed integer numpy array.

libics.core.io.image.load_bmp_to_arraydata(file_path, ad=None)

Reads a bitmap (bmp) file and loads the data as grayscale image into a data.arrays.ArrayData structure.

Parameters

file_pathstr: Path to the bitmap image file.
addata.arrays.ArrayData or None: Sets the array data to the loaded bitmap values. If None, creates a new ArrayData object using the default values as defined in cfg.default.

Returns

addata.arrays.ArrayData: Image grayscales as ArrayData.

Raises

FileNotFoundError: If file_path does not exist.
AttributeError: If given file is not a bitmap file.

libics.core.io.image.load_png_to_arraydata(file_path, ad=None)

Reads a portable network graphic (png) file and loads the data as grayscale image into a data.arrays.ArrayData structure.

Parameters

file_pathstr: Path to the bitmap image file.
addata.arrays.ArrayData or None: Sets the array data to the loaded bitmap values. If None, creates a new ArrayData object using the default values as defined in cfg.default.

Returns

addata.arrays.ArrayData: Image grayscales as ArrayData.

Raises

FileNotFoundError: If file_path does not exist.
AttributeError: If given file is not a bitmap file.

libics.core.io.image.load_sif_to_arraydata(file_path, ad=None)

Reads a bitmap (bmp) file and loads the data as grayscale image into a data.arraydata.ArrayData structure.

Parameters

file_pathstr: Path to the bitmap image file.
addata.arrays.ArrayData or None: Sets the array data to the loaded bitmap values. If None, creates a new ArrayData object using the default values as defined in cfg.default.

Returns

adslist(data.arrays.ArrayData): Image grayscales as list of ArrayData objects.

Raises

FileNotFoundError: If file_path does not exist.
AttributeError: If given file is not a bitmap file.

libics.core.io.image.load_tif_to_arraydata(file_path, ad=None)

Reads a tagged image file format (tif) file and loads the data as grayscale image into a data.arrays.ArrayData structure.

Parameters

file_pathstr: Path to the tif image file.
addata.arrays.ArrayData or None: Sets the array data to the loaded bitmap values. If None, creates a new ArrayData object using the default values as defined in cfg.default.

Returns

addata.arrays.ArrayData: Image grayscales as ArrayData.

Raises

FileNotFoundError: If file_path does not exist.
AttributeError: If given file is not a bitmap file.

libics.core.io.image.load_wct_to_arraydata(file_path, ad=None)

Reads a WinCamD text (wct) file and loads the data as grayscale image into a data.arrays.ArrayData structure.

Parameters

file_pathstr: Path to the WinCamD text file.
addata.arrays.ArrayData or None: Sets the array data to the loaded WinCamD values. If None, creates a new ArrayData object using the default values as defined in cfg.default. When available, the wct header data overwrites the current metadata.

Returns

addata.arrays.ArrayData: Image grayscales as ArrayData.

Raises

FileNotFoundError: If file_path does not exist.
AttributeError: If the wct file is corrupt.

iomisc

class libics.core.io.iomisc.NumpyJsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

JSON encoder class which converts numpy types to built-in types.

Examples

>>> ar = np.arange(5)
>>> json.dumps(ar)
TypeError: Object of type ndarray is not JSON serializable
>>> json.dumps(ar, cls=NumpyJsonEncoder)
'[0, 1, 2, 3, 4]'

Methods

`default`(obj)	Implement this method in a subclass such that it returns a serializable object for `o`, or calls the base implementation (to raise a `TypeError`).
`encode`(o)	Return a JSON string representation of a Python data structure.
`iterencode`(o[, _one_shot])	Encode the given object and yield each string representation as available.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

trace

libics.core.io.trace.load_csv_span_agilent_to_arraydata(file_path)

Reads an Agilent spectrum analyzer text (csv) file into an ArrayData.

Parameters

file_pathstr: Path to the Agilent spectrum analyzer text file.

Returns

dsdict: Power spectral density data set containing metadata “data” : data.arrays.ArrayData

Power spectral density.

Raises

FileNotFoundError: If file_path does not exist.

libics.core.io.trace.load_txt_span_numpy_to_arraydata(file_path, spectral_quantity=None, weight_quantity=None, normalization=None)

Reads a numpy spectrum text (txt) file into an ArrayData.

Assumes a 2D array with spectral data in the first dimension and the spectral weight in the second dimension.

Parameters

file_pathstr

Path to the numpy text file.

spectral_quantitydata.types.Quantity

Quantity description for spectral data (usually frequency or wavelength).

weight_quantitydata.types.Quantity

Quantity description for spectral weight (usually relative or power density).

normalizationNone or str or float

None:: No normalization performed.
“max”:: Normalizes to the weights’ maximum.
“sum”:: Normalizes to the weights’ sum.
“weighted_sum”:: Normalizes to the weighted sum, i.e. weighs the sum by the spectral bin size.
float:: Normalizes such that the maximum has the given value.

Returns

addata.arrays.ArrayData: Spectral density.

Raises

FileNotFoundError: If file_path does not exist.
ValueError: If quantities are invalid.