ModelDetector

class cbclib.ModelDetector(data, frames, num_threads, parent, models, streaks=<factory>, patterns=None)

A streak detector class based on the CBD pattern prediction. Uses cbclib.CBDModel to predict a pattern and filters out all the predicted streaks, that correspond to the measured intensities above the certain threshold. Provides an interface to generate an indexing tabular data.

Parameters

• data (ndarray) – Background corrected detector data.

• frames (ndarray) – Frame indices of the detector images.

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

• parent (ReferenceType[CrystData]) – A reference to the parent cbclib.CrystData container.

• models (Dict[int, CBDModel]) – A dictionary of CBD models.

• streaks (Dict[int, Streaks]) – A dictionary of detected cbclib.Streaks streaks.

• patterns (Optional[ndarray]) – Normalized diffraction patterns.

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.

count_outliers(hkl, width=4.0, alpha=0.05)

Count the number of photon counts for a set of diffraction orders hkl, that lie above the \(\alpha\) quantile for the Poisson distribution with the mean equal to the background signal.

Parameters

• hkl (ndarray) – Miller indices.

• width (float) – Diffraction streak width in pixels.

• alpha (float) – Quantile level, which must be between 0 and 1 inclusive.

Return type

DataFrame

Returns

A dataframe with the columns corresponding to the outlier and total counts.

detect(hkl, width=4.0, hkl_index=False)

Perform the streak detection based on prediction. Generate a predicted pattern and filter out all the streaks, which pertain to the set of reciprocal lattice points hkl.

Parameters

• hkl (ndarray) – A set of reciprocal lattice points used in the detection.

• width (float) – Diffraction streak width in pixels of a predicted pattern.

• hkl_index (bool) – Save lattice point indices in generated streaks (cbclib.Streak) if True.

Return type

ModelDetectorFull

Returns

New cbclib.ModelDetector streak detector with updated streaks.

draw(max_val=1, dilation=0.0, profile='tophat')

Draw a pattern mask by using the detected streaks streaks.

Parameters

• max_val (int) – Maximal mask value

• dilation (float) – Line mask dilation in pixels.

• profile (str) –

  Line width profiles. The following keyword values are allowed:

  • tophat : Top-hat (rectangular) function profile.

  • linear : Linear (triangular) function profile.

  • quad : Quadratic (parabola) function profile.

  • gauss : Gaussian function profile.

Raises

ValueError – If there is no streaks inside the container.

Return type

ndarray

Returns

A pattern mask.

export_streaks()

Export streak_mask to the parent cbclib.CrystData data container.

Raises

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

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

export_table(dilation=0.0, concatenate=True)

Export normalised pattern into a pandas.DataFrame table.

Parameters

• dilation (float) – Line mask dilation in pixels.

• concatenate (bool) – Concatenate sets of patterns for each frame into a single table if True.

Raises

ValueError – If there is no streaks inside the container.

Return type

Union[DataFrame, List[DataFrame]]

Returns

List of pandas.DataFrame tables for each frame in frames if concatenate is False, a single pandas.DataFrame otherwise. Table contains the following information:

• frames : Frame index.

• x, y : Pixel coordinates.

• p : Normalised pattern values.

• rp : Reflection profiles.

• I_raw : Measured intensity.

• bgd : Background values.

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.

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.

mask_frames(idxs)

Choose a subset of frames stored in the container and return a new detector object.

Parameters

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

Return type

~D

Returns

New detector object with the updated frames, data, streak_data, and streaks.

refine_streaks(dilation=0.0)

Refine detected diffraction streaks by fitting a Gaussian across the line.

Parameters

dilation (float) – Dilation radius in pixels used for the Gaussian fit.

Return type

~D

Returns

A new detector with the updated diffraction streaks.

replace(**kwargs)

Return a new container object with a set of attributes replaced.

Parameters

kwargs (Any) – A set of attributes and the values to to replace.

Return type

~D

Returns

A new container object with updated attributes.

to_dataframe(concatenate=True)

Export detected streak lines streaks to a pandas.DataFrame table.

Parameters

concatenate (bool) – Concatenate sets of streaks for each frame into a single table if True.

Raises

ValueError – If there is no streaks inside the container.

Return type

Union[DataFrame, List[DataFrame]]

Returns

List of pandas.DataFrame tables for each frame in frames if concatenate is False, a single pandas.DataFrame otherwise. Table contains the following information:

• frames : Frame index.

• streaks : Line index.

• x0, y0, x1, y1 : Line point coordinates in pixels.

• width : Line width.

• length : Line length.

update_patterns(dilations=(1.0, 3.0, 7.0))

Return a new detector object with updated normalised CBC patterns. The image is segmented into two region around each reflection to calculate the local background and local peak intensity. The estimated values are used to normalise each diffraction streak separately.

Parameters

dilations (Tuple[float, float, float]) –

A tuple of three dilations (d0, d1, d2) in pixels of the streak mask that is used to define the inner and outer streak zones:

• The inner zone is based on the mask dilated by d0.

• The outer zone is based on the difference between a mask dilated by d2 and by d1.

Return type

~D

Returns

A new detector object with updated patterns.

values()

Return the attributes’ data stored in the container.

Return type

ValuesView

Returns

List of data stored in the container.