STData

class pyrost.STData(protocol, **kwargs)

Speckle Tracking algorithm data container class. Contains all the necessary data for the Robust Speckle Tracking algorithm (specified in attr_set and init_set), the list of all the SpeckleTracking objects derived from it, and two AbberationsFit objects to fit the phase along the fast and slow detector axes.

Parameters

• protocol (Protocol) – CXI Protocol object.

• **kwargs (dict) – Dictionary of the attributes’ data specified in attr_set and init_set.

Variables

• attr_set (set) – Set of attributes in the container which are necessary to initialize in the constructor.

• init_set (set) – Set of optional data attributes.

Raises

ValueError – If an attribute specified in attr_set has not been provided.

Notes

Necessary attributes:

• basis_vectors : Detector basis vectors

• data : Measured intensity frames.

• distance : Sample-to-detector distance [m].

• translations : Sample’s translations [m].

• wavelength : Incoming beam’s wavelength [m].

• x_pixel_size : Pixel’s size along the fast detector axis [m].

• y_pixel_size : Pixel’s size along the slow detector axis [m].

Optional attributes:

• defocus_ss : Defocus distance for the slow detector axis [m].

• defocus_fs : Defocus distance for the fast detector axis [m].

• error_frame : MSE (mean-squared-error) of the reference image and pixel mapping fit per pixel.

• good_frames : An array of good frames’ indices.

• mask : Bad pixels mask.

• phase : Phase profile of lens’ abberations.

• pixel_map : The pixel mapping between the data at the detector’s plane and the reference image at the reference plane.

• pixel_abberations : Lens’ abberations along the fast and slow axes in pixels.

• pixel_translations : Sample’s translations in the detector’s plane in pixels.

• reference_image : The unabberated reference image of the sample.

• roi : Region of interest in the detector’s plane.

• whitefield : Measured frames’ whitefield.

crop_data(roi)

Return a new STData object with the updated roi.

Parameters

roi (iterable) – Region of interest in the detector’s plane.

Returns

New STData object with the updated roi.

Return type

STData

integrate_data(axis=1)

Return a new STData object with the data summed over the axis.

Parameters

axis (int) – Axis along which a sum is performed.

Returns

New STData object with the updated data, whitefield, mask, and roi.

Return type

STData

mask_frames(good_frames)

Return a new STData object with the updated good frames mask.

Parameters

good_frames (iterable) – List of good frames’ indices.

Returns

New STData object with the updated good_frames and whitefield.

Return type

STData

make_mask(method='no-bad', percentile=99.99)

Return a new STData object with the updated bad pixels mask.

Parameters

• method ({'no-bad', 'eiger-bad', 'perc-bad'}, optional) –

  Bad pixels masking methods:

  • ’no-bad’ (default) : No bad pixels.

  • ’eiger-bad’ : Mask the pixels which value are higher than 65535 a.u. (for EIGER detector).

  • ’perc-bad’ : mask the pixels which values lie outside of the q-th percentile. Provide percentile value with percentile argument.

• percentile (float, optional) – Percentile to compute. Defines the ‘perc-bad’ masking method.

Returns

New STData object with the updated mask.

Return type

STData

make_whitefield()

Return a new STData object with the updated whitefield.

Returns

New STData object with the updated whitefield.

Return type

STData

make_pixel_map()

Return a new STData object with the default pixel_map.

Returns

New STData object with the updated pixel_map.

Return type

STData

update_defocus(defocus_fs, defocus_ss=None)

Return a new STData object with the updated defocus distances defocus_fs and defocus_ss for the fast and slow detector axes accordingly. Update pixel_translations based on the new defocus distances.

Parameters

• defocus_fs (float) – Defocus distance for the fast detector axis [m].

• defocus_ss (float, optional) – Defocus distance for the slow detector axis [m]. Equals to defocus_fs if it’s not provided.

Returns

New STData object with the updated defocus_ss, defocus_fs, and pixel_translations.

Return type

STData

defocus_sweep(defoci_fs, defoci_ss=None, ls_ri=30)

Calculate an array of reference_image for defoci and return fugures of merit of reference_image sharpness (the higher the value the sharper reference_image is). ls_ri should be large enough in order to supress high frequency noise.

Parameters

• defoci_fs (numpy.ndarray) – Array of defocus distances along the fast detector axis [m].

• defoci_ss (numpy.ndarray, optional) – Array of defocus distances along the slow detector axis [m].

• ls_ri (float, optional) – reference_image length scale in pixels.

Returns

Array of the average values of reference_image gradients squared.

Return type

numpy.ndarray

See also

SpeckleTracking.update_reference

reference_image update algorithm.

fit_phase(axis=1, max_order=2, xtol=1e-14, ftol=1e-14, loss='cauchy', roi=None)

Fit pixel_abberations with the polynomial function using nonlinear least-squares algorithm. The function uses least-squares algorithm from scipy.optimize.least_squares().

Parameters

• axis (int, optional) – Axis along which pixel_abberations is fitted.

• max_order (int, optional) – Maximum order of the polynomial model function.

• xtol (float, optional) – Tolerance for termination by the change of the independent variables.

• ftol (float, optional) – Tolerance for termination by the change of the cost function.

• loss ({'linear', 'soft_l1', 'huber', 'cauchy', 'arctan'}, optional) –

  Determines the loss function. The following keyword values are allowed:

  • ’linear’ : rho(z) = z. Gives a standard least-squares problem.

  • ’soft_l1’ : rho(z) = 2 * ((1 + z)**0.5 - 1). The smooth approximation of l1 (absolute value) loss. Usually a good choice for robust least squares.

  • ’huber’ : rho(z) = z if z <= 1 else 2*z**0.5 - 1. Works similarly to ‘soft_l1’.

  • ’cauchy’ (default) : rho(z) = ln(1 + z). Severely weakens outliers influence, but may cause difficulties in optimization process.

  • ’arctan’ : rho(z) = arctan(z). Limits a maximum loss on a single residual, has properties similar to ‘cauchy’.

• roi (iterable, optional) – Region of interest. Full region if roi is None.

Returns

dict with the following fields defined:

• alpha : Third order abberations ceofficient [rad/mrad^3].

• fit : Array of the polynomial function coefficients of the pixel abberations fit.

• ph_fit : Array of the polynomial function coefficients of the phase abberations fit.

• rel_err : Vector of relative errors of the fit coefficients.

• r_sq : R**2 goodness of fit.

Return type

dict

See also

AbberationsFit.fit

get(attr, value=None)

Return a dataset with mask and roi applied. Return value if the attribute is not found.

Parameters

• attr (str) – Attribute to fetch.

• value (object, optional) – Return if attr is not found.

Returns

attr dataset with mask and roi applied. value if attr is not found.

Return type

numpy.ndarray or object

get_fit(axis=1)

Return an AbberationsFit object for parametric regression of the lens’ abberations profile. Return None if defocus_fs or defocus_ss doesn’t exist in the container.

Parameters

axis (int) – Detector axis along which the fitting is performed.

Returns

An instance of AbberationsFit class. None if defocus_fs or defocus_ss is None.

Return type

AbberationsFit or None

get_st()

Return SpeckleTracking object derived from the container. Return None if defocus_fs or defocus_ss doesn’t exist in the container.

Returns

An instance of SpeckleTracking derived from the container. None if defocus_fs or defocus_ss is None.

Return type

SpeckleTracking or None

get_st_list()

Return a list of all the SpeckleTracking objects bound to the container.

Returns

List of all the SpeckleTracking objects bound to the container.

Return type

list

items()

Return (key, value) pairs of the datasets stored in the container.

Returns

(key, value) pairs of the datasets stored in the container.

Return type

dict_items

keys()

Return the list of attributes stored in the container.

Returns

List of attributes stored in the container.

Return type

dict_keys

update_phase(st_obj)

Update pixel_abberations, phase, and reference_image based on SpeckleTracking object st_obj data. st_obj must be derived from the STData object, an error is raised otherwise.

Parameters

st_obj (SpeckleTracking) – SpeckleTracking object derived from the STData object.

Returns

STData object with the updated pixel_abberations, phase, and reference_image.

Return type

STData

Raises

ValueError – If st_obj doesn’t belong to the STData object.

values()

Return the attributes’ data stored in the container.

Returns

List of data stored in the container.

Return type

dict_values

write_cxi(cxi_file, overwrite=True)

Write all the attr to a CXI file cxi_file.

Parameters

• cxi_file (h5py.File) – h5py.File object of the CXI file.

• overwrite (bool, optional) – Overwrite the content of cxi_file file if it’s True.

Raises

ValueError – If overwrite is False and the data is already present in cxi_file.