DataObjects.SsMatrixData

DataObjects.SsMatrixData#

DataObjects.SsMatrixData.py

class SsMatrixData(M, iv, jv, E=None, moment=None, baseline_method='linear', allow_negative_peaks=False, negative_peak_mask=None)#

Bases: object

A class to represent a SAXS/UV matrix data object. It contains a 2D matrix M where M[i,j] is the intensity value at the i-th value of the first variable (iv) and the j-th value of the second variable (jv).

iv#

The values of the first variable (e.g., scattering angle or q).

Type:

array-like

jv#

The values of the second variable (e.g., time or wavelength).

Type:

array-like

M#

The 2D matrix of intensity values.

Type:

2D array-like

data#

Human-readable alias for M — the core intensity matrix.

Type:

2D array-like (property)

E#

The 2D matrix of error values. It can be None if errors are not available

Type:

2D array-like or None

moment#

The moment of the data along the iv axis. It can be None if not computed.

Type:

Moment or None

baseline_method#

The method used for baseline correction. Default is ‘linear’.

Type:

str

allow_negative_peaks#

Deprecated alias for has_anomaly_mask.

Type:

bool

has_anomaly_mask#

If True, frames in the anomaly region are excluded from LPM’s anchor pool before baseline fitting, preventing contamination from physically anomalous frames (e.g. negative-peak regions). Default False.

Type:

bool

negative_peak_mask#

Deprecated alias for anomaly_mask.

Type:

array-like of bool, slice, or None

anomaly_mask#

Explicit mask of frames to exclude from LPM fitting when has_anomaly_mask=True. If None (default), the mask is derived automatically from the recognition curve (frames where y < 0).

Type:

array-like of bool, slice, or None

Initialize the SsMatrixData object.

Parameters:

  • M (2D array-like, shape (len(iv), len(jv))) – The 2D intensity matrix. Row axis = iv, column axis = jv.

  • iv (array-like) – Row-axis values (e.g. q-values for XR, wavelengths for UV).

  • jv (array-like or None) – Column-axis values (frame numbers). If None, defaults to np.arange(M.shape[1]).

  • E (2D array-like or None, optional) – Error matrix with the same shape as M. Default None.

property data#

The 2D intensity matrix (alias for M, following numpy/pandas/xarray convention).

property q_values#

Row-axis values (alias for iv), typically scattering vector q.

property frame_indices#

Column-axis values (alias for jv), typically frame numbers.

copy(slices=None)#

Return a copy of the SsMatrixData object.

Parameters:

slices (tuple of slices, optional) – The slices to apply to the iv, jv, and M attributes.

get_icurve(pickat)#

get an i-curve from the matrix data.

Parameters:

pickat (float) – Specifies the value to pick an i-curve. The i-curve will be made from ssd.M[i,:] where ssd.iv[i] is the largest value that is less than or equal to pickat.

Examples

>>> curve = md.get_icurve(0.1)
get_jcurve(j)#

Returns a j-curve from the matrix data.

Parameters:

j (int) – Specifies the index to pick a j-curve. The j-curve will be made from ssd.xrM[:,j].

Examples

>>> curve = md.get_jcurve(150)
get_recognition_curve()#

Return the elution curve used for peak detection and buffer-frame classification. The base implementation always returns the sum over all rows (M.sum(axis=0)). XrData overrides this to honour the 'elution_recognition' global option.

Returns:

The recognition elution curve.

Return type:

Curve

get_moment()#

Get the moment of the matrix data along the iv axis.

Returns:

moment – The moment object representing the moment along the iv axis.

Return type:

EghMoment

set_baseline_method(method)#

Set the baseline method for this data object.

get_baseline_method()#

Get the baseline method for this data object.

set_anomaly_mask(mask=None)#

Declare that this dataset contains anomalous frames to exclude from baseline fitting.

When set, get_baseline2d() excludes the specified frames from LPM’s anchor pool before baseline fitting. LPM itself is unchanged; only the frame set it operates on is filtered.

Parameters:

mask (array-like of bool, slice, or None, optional) – Explicit mask of frames to exclude (True = exclude). If None (default), the mask is derived automatically at fitting time from the recognition curve (frames where y < 0). Use a manual mask when the anomalous region is known from domain knowledge (e.g. mask=slice(1200, 1350)). When a slice is given, start and stop are interpreted as frame numbers (values in jv), not array indices.

Notes

Both has_anomaly_mask and anomaly_mask are propagated by copy() and corrected_copy(), so the typical workflow is:

ssd.set_anomaly_mask()            # auto-detect
# or:
ssd.set_anomaly_mask(mask=slice(1200, 1350))  # manual
corrected = ssd.corrected_copy()  # mask applied automatically
set_allow_negative_peaks(value=True, mask=None)#

Deprecated: use set_anomaly_mask(mask) instead.

When value is True, delegates to set_anomaly_mask(mask). When value is False, clears the anomaly mask.

property allow_negative_peaks#

Deprecated alias for has_anomaly_mask.

property negative_peak_mask#

Deprecated alias for anomaly_mask.

detect_anomaly(sigma_scale=3.0, buffer_fraction=0.1)#

Detect the anomalous frame range from the pre-correction recognition curve.

Uses a three-step algorithm:

  1. Estimate buffer-zone noise σ from the first and last buffer_fraction fraction of frames.

  2. Find the largest contiguous run of frames below -sigma_scale * σ (the “deep-negative core”).

  3. Expand the core outward while the recognition curve remains negative (fringe expansion).

This algorithm works on the pre-correction recognition curve, so it can be called before corrected_copy() and the result passed directly to set_anomaly_mask(mask=slice(start, stop)).

Parameters:

  • sigma_scale (float, optional) – Threshold multiplier for the deep-negative core. Default 3.0.

  • buffer_fraction (float, optional) – Fraction of frames at each end used to estimate noise σ. Default 0.1 (first and last 10 %).

Returns:

A slice of frame numbers slice(start, stop) covering the detected anomaly region, or None if no anomaly was found.

Return type:

slice or None

Examples

>>> anom = ssd.xr.detect_anomaly()
>>> if anom is not None:
...     ssd.set_anomaly_mask(mask=anom)
>>> corrected = ssd.corrected_copy()
get_baseline2d(**kwargs)#

Get the 2D baseline for the matrix data using the specified method.

Parameters:

  • method (str, optional) – Baseline method to use. If given, overrides the instance’s baseline_method for this call only. Valid values are 'buffit', 'linear', 'uvdiff', 'integral'.

  • endpoint_fraction (float, optional) – Only used when method='linear'. If given and > 0, switches the LPM anchor from the bottom-25th-percentile frames to the leading and trailing k = max(2, int(endpoint_fraction * n)) frames. Only valid for “easy” datasets where the run starts and ends in clean buffer. Not the recommended approach for negative-peak datasets — use set_anomaly_mask() instead. Default None — standard LPM unchanged.

  • method_kwargs (dict, optional) – Additional keyword arguments to pass to the baseline fitting method.

  • debug (bool, optional) – If True, enable debug mode.

Returns:

baseline – The 2D baseline array with the same shape as self.M.

Return type:

ndarray

Examples

>>> bl = xr.get_baseline2d()                        # standard LPM
>>> bl = xr.get_baseline2d(endpoint_fraction=0.15)  # endpoint-anchored (easy datasets only)
>>> xr.set_anomaly_mask()                   # auto-detect negative frames, mask from LPM
>>> bl = xr.get_baseline2d()                        # LPM with anomalous frames excluded
>>> xr.set_anomaly_mask(mask=slice(1200, 1350))  # manual region known from observation
get_snr_weights()#

Per-q-row signal-to-noise ratio weights.

Returns:

weights – w_i = mean(I_i) / sigma_noise_i, clipped to >= 0.

Return type:

ndarray, shape (n_q,)

get_positive_ratio(baseline=None, weighting='snr')#

Fraction of non-negative residual elements, optionally SNR-weighted.

Parameters:

  • baseline (ndarray or None) – 2D baseline array with the same shape as self.M. If None (default), the data is assumed already corrected and a zero baseline is used.

  • weighting ({'snr', 'uniform'}) – ‘snr’ (default) weights each q-row by its SNR so that informative low-q rows dominate over noisy high-q rows.

Returns:

positive_ratio

Return type:

float

get_bpo_ideal(weighting='snr')#

Get the dataset-relative ideal positive_ratio for baseline evaluation.

With weighting='snr' (default), computes per-q-row noisiness, looks up per-row ideal from the BPO table, and aggregates with SNR weights. With weighting='uniform', uses the original single global noisiness.

Parameters:

weighting ({'snr', 'uniform'})

Returns:

bpo_ideal – The expected positive_ratio in [0, 1].

Return type:

float

get_ideal_positive_ratio(weighting='snr')#

Expected positive_ratio for a perfect baseline, given this dataset’s noise and peak geometry.

Alias for get_bpo_ideal() with a self-documenting name.

evaluate_baseline(baseline, weighting='snr')#

Evaluate baseline quality in a single call.

Parameters:

  • baseline (ndarray) – 2D baseline array with the same shape as self.M.

  • weighting ({'snr', 'uniform'})

Returns:

result – Namedtuple with fields positive_ratio, ideal, delta.

Return type:

BaselineEvaluation