bcdi.utils: various utilities for DFT registration and subpixel shift, data loading and fitting, validating parameters

utilities

Various non-specific utilities for i/o, fitting curves, generic functions for cropping or padding a dataset…

API Reference

format

Functions and class related to string formatting for JSON dump and repr.

API Reference

Functions related to formatting for string representation.

class bcdi.utils.format.CustomEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Class to handle the serialization of np.ndarrays, sets.

default(obj)

Override the JSONEncoder.default method to support more types.

bcdi.utils.format.create_repr(obj: Any, cls: type) → str

Generate the string representation of the object.

It uses the parameters given to __init__, except self, args and kwargs.

Parameters

  • obj – the object for which the string representation should be generated

  • cls – the cls from which __init__ parameters should be extracted (e.g., base class in case of inheritance)

Returns

the string representation

bcdi.utils.format.format_repr(value: Optional[Any], quote_mark: bool = True) → str

Format strings for the __repr__ method.

Parameters

  • value – string or None

  • quote_mark – True to put quote marks around strings

Returns

a string

bcdi.utils.format.format_value(value: Any) → Tuple[Any, bool]

Format the value for a proper representation.

bcdi.utils.format.ndarray_to_list(array: numpy.ndarray) → List

Convert a numpy ndarray of any dimension to a nested list.

Parameters

array – the array to be converted

image_registration

Functions related to image registration and the alignment of datasets in direct or reciprocal space.

API Reference

io_helper

Class and decorators related to the safe opening of files.

API Reference

Module containing decorators and context manager classes for input-output.

class bcdi.utils.io_helper.ContextFile(filename: str, open_func: Callable, scan_number: Optional[int] = None, mode: str = 'r', encoding: str = 'utf-8', longname: Optional[str] = None, shortname: Optional[str] = None, directory: Optional[str] = None, **kwargs)

Convenience context manager to open files.

The supported opening callables are silx.io.specfile.Specfile, io.open, h5py.File and SIXS (nxsReady.Dataset, ReadNxs3.Dataset).

Parameters

kwargs –

  • ‘logger’: an optional logger

bcdi.utils.io_helper.safeload(func: Callable) → Callable

Decorate a class method to safely opening files.

Parameters

func – a class method accessing the file

bcdi.utils.io_helper.safeload_static(func: Callable) → Callable

Decorate a class static method or a function to safely opening files.

Parameters

func – a class static method accessing the file

parameters

Classes and functions related to the validation of configuration parameters.

API Reference

parser

Class and functions related to loading of the config file and command line parameters.

API Reference

snippets_logging

API Reference

text

This module provides the class used to define filename when saving data and figures during processing.

API Reference

validation

This module contains all validation functions that are used throughout the code, in order to test the input parameters of functions.

API Reference

Functions related to the validation of input parameters.

bcdi.utils.validation.is_float(string)

Return True is the string represents a number.

Parameters

string – the string to be checked

Returns

True of False

bcdi.utils.validation.valid_1d_array(array, length=None, min_length=None, allow_none=True, allowed_types=None, allowed_values=None, name=None)

Check if the array is 1D and satisfies the requirements.

Parameters

  • array – the numpy array to be checked

  • length – int, required length

  • min_length – int, minimum length of the array

  • allow_none – bool, True if the array can be None

  • allowed_types – list or tuple of valid types

  • allowed_values – Sequence of allowed values for the array

  • name – name of the calling object appearing in exception messages

Returns

bool, True if all checks passed

bcdi.utils.validation.valid_container(obj, container_types, length=None, min_length=None, max_length=None, item_types=None, name=None, min_included=None, min_excluded=None, max_included=None, max_excluded=None, allow_none=False)

Check that the input object as three elements fulfilling the defined requirements.

Parameters

  • obj – the object to be tested

  • container_types – list of the allowed types for obj

  • length – int, required length

  • min_length – mininum length (inclusive)

  • max_length – maximum length (inclusive)

  • item_types – list of the allowed types for the object items

  • min_included – minimum allowed value (inclusive)

  • min_excluded – minimum allowed value (exclusive)

  • max_included – maximum allowed value (inclusive)

  • max_excluded – maximum allowed value (exclusive)

  • allow_none – True if the container items are allowed to be None

  • name – name of the calling object appearing in exception messages

Returns

True if checks pass, raise some error otherwise

bcdi.utils.validation.valid_item(value, allowed_types, min_included=None, min_excluded=None, max_included=None, max_excluded=None, allow_none=False, name=None)

Check that the input object as three elements fulfilling the defined requirements.

Parameters

  • value – the value to be tested

  • allowed_types – allowed types of the object values

  • min_included – minimum allowed value (inclusive)

  • min_excluded – minimum allowed value (exclusive)

  • max_included – maximum allowed value (inclusive)

  • max_excluded – maximum allowed value (exclusive)

  • allow_none – True if the container items are allowed to be None

  • name – name of the calling object appearing in exception messages

Returns

True if checks pass, raise some error otherwise

bcdi.utils.validation.valid_kwargs(kwargs, allowed_kwargs, name='kwargs')

Check if the provided parameters belong to the set of allowed kwargs.

Parameters

  • kwargs – dictionnary of kwargs to check

  • allowed_kwargs – set of allowed keys

  • name – name of the calling object appearing in exception messages

Returns

True if checks pass, raise some error otherwise

bcdi.utils.validation.valid_ndarray(arrays: Union[numpy.ndarray, Tuple[numpy.ndarray, ...]], ndim: Optional[Union[int, Tuple[int, ...]]] = None, shape: Optional[Tuple[int, ...]] = None, fix_ndim: bool = True, fix_shape: bool = True, name: Optional[str] = None) → bool

Check that arrays have the same shape and the correct number of dimensions.

Parameters

  • arrays – a sequence of numpy ndarrays

  • ndim – int, the number of dimensions to be compared with

  • shape – sequence of int, shape to be compared with

  • fix_ndim – bool, if True the shape of all arrays should be equal

  • fix_shape – bool, if True the shape of all arrays should be equal

  • name – name of the calling object appearing in exception messages

Returns

True if checks pass, raise some error otherwise