CrystData

class cbclib.CrystData(input_file=None, transform=None, num_threads=2, output_file=None, data=None, good_frames=None, mask=None, frames=None, whitefield=None, cor_data=None, background=None, streak_mask=None)

Convergent beam crystallography data container class. Takes a cbclib.CXIStore file handler. Provides an interface to work with the detector images and detect the diffraction streaks. Also provides an interface to load from a file and save to a file any of the data attributes. The data frames can be tranformed using any of the cbclib.Transform classes.

Parameters

• input_file (Optional[CXIStore]) – Input file cbclib.CXIStore file handler.

• transform (Optional[Transform]) – An image transform object.

• num_threads (int) – Number of threads used in the calculations.

• output_file (Optional[CXIStore]) – On output file cbclib.CXIStore file handler.

• data (Optional[ndarray]) – Detector raw data.

• good_frames (Optional[ndarray]) – An array of good frames’ indices.

• mask (Optional[ndarray]) – Bad pixels mask.

• frames (Optional[ndarray]) – List of frame indices inside the container.

• whitefield (Optional[ndarray]) – Measured frames’ white-field.

• cor_data (Optional[ndarray]) – Background corrected data.

• background (Optional[ndarray]) – Detector image backgrounds.

• streak_mask (Optional[ndarray]) – A mask of detected diffraction streaks.

backward_points(x, y)

Transform detector coordinates back.

Parameters

• x (ndarray) – A set of transformed x coordinates.

• y (ndarray) – A set of transformed y coordinates.

Return type

Tuple[ndarray, ndarray]

Returns

A tuple of x and y coordinates.

blur_pupil(setup, padding=0.0, blur=0.0)

Blur pupil region in the background corrected images.

Parameters

• setup (ScanSetup) – Experimental setup.

• padding (float) – Pupil region padding in pixels.

• blur (float) – Blur width in pixels.

Raises

ValueError – If there is no whitefield inside the container.

Return type

~C

Returns

New CrystData object with the updated cor_data.

clear(attributes=None)

Clear the data inside the container.

Parameters

attributes (Union[str, List[str], None]) – List of attributes to clear in the container.

Return type

~C

Returns

New CrystData object with the attributes cleared.

contents()

Return a list of the attributes stored in the container that are initialised.

Return type

List[str]

Returns

List of the attributes stored in the container.

forward_points(x, y)

Transform detector coordinates.

Parameters

• x (ndarray) – A set of x coordinates.

• y (ndarray) – A set of y coordinates.

Return type

Tuple[ndarray, ndarray]

Returns

A tuple of transformed x and y coordinates.

get(attr, value=None)

Retrieve a dataset, return value if the attribute is not found.

Parameters

• attr (str) – Data attribute.

• value (Optional[Any]) – Data which is returned if the attribute is not found.

Return type

Any

Returns

Attribute’s data stored in the container, value if attr is not found.

get_pca()

Perform the Principal Component Analysis [PCA] of the measured data and return a set of eigen flat-fields (EFF).

Return type

Dict[float, ndarray]

Returns

A tuple of (‘effs’, ‘eig_vals’). The elements are as follows:

• ’effs’ : Set of eigen flat-fields.

• ’eig_vals’ : Corresponding eigen values for each of the eigen flat-fields.

Raises

ValueError – If there is no whitefield inside the container.

References

PCA

Vincent Van Nieuwenhove, Jan De Beenhouwer, Francesco De Carlo, Lucia Mancini, Federica Marone, and Jan Sijbers, “Dynamic intensity normalization using eigen flat fields in X-ray imaging,” Opt. Express 23, 27975-27989 (2015).

import_mask(mask, update='reset')

Return a new CrystData object with the new mask.

Parameters

• mask (ndarray) – New mask array.

• update (str) – Multiply the new mask and the old one if ‘multiply’, use the new one if ‘reset’.

Raises

• ValueError – If the mask shape is incompatible with the data.

• ValueError – If there is no data inside the container.

Return type

~C

Returns

New CrystData object with the updated mask.

import_patterns(table)

Import a streak mask from a CBC table.

Parameters

table (DataFrame) – CBC table in pandas.DataFrame format.

Return type

~C

Returns

New container with updated streak_mask.

See also

cbclib.CBCTable : More info about the CBC table.

import_whitefield(whitefield)

Return a new CrystData object with the new whitefield.

Parameters

whitefield (ndarray) – New whitefield array.

Raises

• ValueError – If the whitefield shape is incompatible with the data.

• ValueError – If there is no data inside the container.

Return type

~C

Returns

New CrystData object with the updated whitefield.

items()

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

Return type

ItemsView

Returns

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

keys()

Return a list of the attributes available in the container.

Return type

List[str]

Returns

List of the attributes available in the container.

load(attributes=None, idxs=None, processes=1, verbose=True)

Load data attributes from the input files in files file handler object.

Parameters

• attributes (Union[str, List[str], None]) – List of attributes to load. Loads all the data attributes contained in the file(s) by default.

• idxs (Union[int, slice, ndarray, List[int], Tuple[int], None]) – List of frame indices to load.

• processes (int) – Number of parallel workers used during the loading.

• verbose (bool) – Set the verbosity of the loading process.

Raises

• ValueError – If attribute is not existing in the input file(s).

• ValueError – If attribute is invalid.

Return type

~C

Returns

New CrystData object with the attributes loaded.

lsd_detector()

Return a new cbclib.LSDetector object based on cor_data attribute.

Raises

ValueError – If there is no whitefield inside the container.

Return type

LSDetector

Returns

A CBC pattern detector based on cbclib.bin.LSD Line Segment Detection [LSD] algorithm.

mask_frames(frames=None)

Return a new CrystData object with the updated good frames mask. Mask empty frames by default.

Parameters

frames (Union[int, slice, ndarray, List[int], Tuple[int], None]) – List of good frames’ indices. Masks empty frames if not provided.

Raises

ValueError – If there is no data inside the container.

Return type

~C

Returns

New CrystData object with the updated frames and whitefield.

mask_pupil(setup, padding=0.0)

Return a new CrystData object with the pupil region masked.

Parameters

• setup (ScanSetup) – Experimental setup.

• padding (float) – Pupil region padding in pixels.

Raises

ValueError – If there is no data inside the container.

Return type

~C

Returns

New CrystData object with the updated mask.

mask_region(roi)

Return a new CrystData object with the updated mask. The region defined by the [y_min, y_max, x_min, x_max] will be masked out.

Parameters

roi (Union[int, slice, ndarray, List[int], Tuple[int]]) – Bad region of interest in the detector plane. A set of four coordinates [y_min, y_max, x_min, x_max].

Raises

ValueError – If there is no data inside the container.

Return type

~C

Returns

New CrystData object with the updated mask.

model_detector(basis, samples, setup)

Return a new cbclib.ModelDetector object based on cor_data attribute and the solution of sample and indexing refinement.

Parameters

• basis (Basis) – Indexing solution.

• samples (ScanSamples) – Sample refinement solution.

• setup (ScanSetup) – Experimental setup.

Raises

ValueError – If there is no whitefield inside the container.

Return type

ModelDetector

Returns

A CBC pattern detector based on cbclib.CBDModel CBD pattern prediction model.

replace(**kwargs)

Return a new cbclib.CrystData container with replaced data.

Parameters

kwargs (Any) – Replaced attributes.

Return type

~C

Returns

A new cbclib.CrystData container.

save(attributes=None, apply_transform=False, mode='append', idxs=None)

Save data arrays of the data attributes contained in the container to an output file.

Parameters

• attributes (Union[str, List[str], None]) – List of attributes to save. Saves all the data attributes contained in the container by default.

• apply_transform (bool) – Apply transform to the data arrays if True.

• mode (str) –

  Writing modes. The following keyword values are allowed:

  • append : Append the data array to already existing dataset.

  • insert : Insert the data under the given indices idxs.

  • overwrite : Overwrite the existing dataset.

• idxs (Union[int, slice, ndarray, List[int], Tuple[int], None]) – Indices where the data is saved. Used only if mode is set to ‘insert’.

Raises

ValueError – If the output_file is not defined inside the container.

Return type

None

update_background()

Return a new CrystData object with a new set of backgrounds. A set of backgrounds is generated by fitting a white-field profile to the measured data.

Raises

ValueError – If there is no whitefield inside the container.

Return type

~C

Returns

New CrystData object with the updated background.

update_cor_data()

Return a new CrystData object with new background corrected detector images.

Raises

ValueError – If there is no whitefield inside the container.

Return type

~C

Returns

New CrystData object with the updated cor_data.

update_mask(method='range-bad', pmin=0.0, pmax=99.99, vmin=0, vmax=65535, update='reset')

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

Parameters

• method (str) –

  Bad pixels masking methods. The following keyword values are allowed:

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

  • ’range-bad’ : Mask the pixels which values lie outside of (vmin, vmax) range.

  • ’perc-bad’ : Mask the pixels which values lie outside of the (pmin, pmax) percentiles.

• vmin (int) – Lower intensity bound of ‘range-bad’ masking method.

• vmax (int) – Upper intensity bound of ‘range-bad’ masking method.

• pmin (float) – Lower percentage bound of ‘perc-bad’ masking method.

• pmax (float) – Upper percentage bound of ‘perc-bad’ masking method.

• update (str) – Multiply the new mask and the old one if ‘multiply’, use the new one if ‘reset’.

Raises

• ValueError – If there is no data inside the container.

• ValueError – If method keyword is invalid.

• ValueError – If update keyword is invalid.

• ValueError – If vmin is larger than vmax.

• ValueError – If pmin is larger than pmax.

Return type

~C

Returns

New CrystData object with the updated mask.

update_output_file(output_file)

Return a new CrystData object with the new output file handler.

Parameters

output_file (CXIStore) – A new output file handler.

Return type

~C

Returns

New CrystData object with the new output file handler.

update_transform(transform)

Return a new CrystData object with the updated transform object.

Parameters

transform (Transform) – New Transform object.

Return type

~C

Returns

New CrystData object with the updated transform object.

update_whitefield(method='median', num_medians=5)

Return a new CrystData object with new whitefield as the median taken through the stack of measured frames.

Parameters

• method (str) –

  Choose a method to generate a white-field. The following keyboard attributes are allowed:

  • mean : Taking a mean through the stack of frames.

  • median : Taking a median through the stack of frames.

  • median + mean : Taking num_medians medians through subsets of frames and then taking a mean through the stack of medians.

• num_medians (int) – Number of medians to generate for median + mean method.

Raises

ValueError – If there is no data inside the container.

Return type

~C

Returns

New CrystData object with the updated whitefield.

values()

Return the attributes’ data stored in the container.

Return type

ValuesView

Returns

List of data stored in the container.