DataObjects.SecSaxsData

DataObjects.SecSaxsData#

DataObjects.SecSacsData.py

class SecSaxsData(folder=None, object_list=None, uv_only=False, xr_only=False, trimmed=False, trimming=None, remove_bubbles=False, beamline_info=None, mapping=None, time_initialized=None, datafiles=None, uv_pickat=None, xr_pickat=None, debug=False)#

Bases: object

A class to represent a SEC-SAXS data object. It contains a pair of XrData and UvData objects. It also contains the beamline information and mapping information if available.

xr#

The XR data object.

Type:

XrData or None

uv#

The UV data object.

Type:

UvData or None

trimmed#

Indicates whether the data has been trimmed. This attribute is used to avoid minor redundant trimming operations which may cause inconsistency from the algorithmic reasons.

Type:

bool

mapping#

The mapping information between XR and UV data.

Type:

MappingInfo or None

beamline_info#

The beamline information.

Type:

BeamlineInfo or None

time_initialized#

The time when the object was initialized.

Type:

float

time_required#

The time required for processing the data.

Type:

float

time_required_total#

The total time required for processing all data. This includes the time required for processing the data

Type:

float

datafiles#

The list of data files used for the analysis.

Type:

list of str or None

logger#

The logger object for logging messages.

Type:

logging.Logger

ssd = SecSacsData(data_folder)

Creates a SEC-SAXS data object.

Parameters:

  • folder (str, optional) – Specifies the folder path where the data are stored. It is required if the data_list parameter is ommitted.

  • object_list (list, optional) – A list which includes [xr_data, uv_data] in this order to be used as corresponding data items. It is required if the folder parameter is ommitted.

  • uv_only (bool, optional) – If it is True, only UV data will be loaded to suppress unnecessary data access.

  • xr_only (bool, optional) – If it is True, only XR data will be loaded to suppress unnecessary data access.

  • trimmed (bool, optional) – If it is True, the data will be treated as trimmed.

  • remove_bubbles (bool, optional) – If it is True, bubbles will be removed from the data.

  • beamline_info (BeamlineInfo, optional) – If specified, the beamline information will be used.

  • mapping (MappingInfo, optional) – If specified, the mapping information will be used.

  • time_initialized (float, optional) – If specified, the time when the object was initialized. If it is None, the time will be set to the time taken for initialization.

  • datafiles (list of str, optional) – If specified, the list of data files used for the analysis. If it is None, the data files will be set to the list of files loaded from the folder.

  • uv_pickat (float, optional) – The wavelength (nm) at which to extract the UV elution profile. Defaults to 280 nm when None. Use 290 for samples like ATP or MY where the UV signal is measured at 290 nm.

  • xr_pickat (float, optional) – The q-value (Å⁻¹) at which to extract the XR elution profile. Defaults to 0.02 when None.

  • debug (bool, optional) – If True, enables debug mode for more verbose output.

Examples

>>> ssd = SecSacsData('the_data_folder')

>>> uv_only_ssd = SecSacsData('the_data_folder', uv_only=True)
has_xr()#

Returns whether the XR data is available.

Parameters:

None

Returns:

has_xr – True if the XR data is available, False otherwise.

Return type:

bool

has_uv()#

Returns whether the UV data is available.

Parameters:

None

Returns:

has_uv – True if the UV data is available, False otherwise.

Return type:

bool

plot_3d(title=None, view_init=None, view_arrows=False, with_2d_section_lines=False, **kwargs)#

Plots a pair of 3D figures of UV and XR data.

Parameters:

  • title (str, optional) – If specified, add a super title to the plot.

  • view_init (dict, optional) – A dictionary which specifies the view_init parameters. The default is dict(elev=30, azim=-60) as of matplotlib 3.10.

  • view_arrows (bool, optional) – If it is True, the 2D view arrows are drawn on the 3D plot. One of the arrows shows the elutional view, while the other shows the spectral view. The default is False.

  • with_2d_section_lines (bool, optional) – If it is True, the 2D section lines are drawn on the 3D plot. The default is False.

Returns:

result – A PlotResult object which contains the following attributes.

fig: Figure axes: Axes

Return type:

PlotResult

plot_compact(title=None, baseline=False, ratio_curve=None, moment_lines=False, **kwargs)#

Plots a pair of compact figures of UV and XR data.

Parameters:

  • title (str, optional) – If specified, add a super title to the plot.

  • baseline (bool, optional) – If it is True, the baseline will be plotted.

  • ratio_curve (Curve, optional) – If specified, the ratio curve will be plotted.

  • moment_lines (bool, optional) – If it is True, the moment lines will be plotted.

Returns:

result – A PlotResult object which contains the following attributes.

fig: Figure axes: Axes mapping: MappingInfo (if available) xr_curve: Curve (if available) uv_curve: Curve (if available) mp_curve: Curve (if available) moment: Moment of the XR data (if available)

Return type:

PlotResult

make_trimming(xr_qr=None, xr_mt=None, uv_wr=None, uv_mt=None)#

Returns a pair of indeces which should be used as slices for the spectral axis and the temporal axis to trim the data.

Parameters:

  • xr_qr (tuple of (int, int), optional) – The angular range (start, stop) to be used for the XR data. If it is None, the full range will be used.

  • xr_mt (tuple of (int, int), optional) – The temporal range (start, stop) to be used for the XR data. If it is None, the full range will be used.

  • uv_wr (tuple of (int, int), optional) – The wavelength range to be used for the UV data. If it is None, the full range will be used.

  • uv_mt (tuple of (int, int), optional) – The temporal range (start, stop) to be used for the UV data. If it is None, the full range will be used.

Returns:

trimming – A TrimmingInfo object which contains the trimming information.

Return type:

TrimmingInfo

See also

ssd.copy

Examples

>>> trim = ssd.make_trimming()
plot_trimming(trim=None, baseline=False, title=None, return_fig=False, **kwargs)#

Plots a set of trimming info.

Parameters:

  • trim (TrimmingInfo or dict, optional) – The trimming information to be used for the plot.

  • baseline (bool, optional) – If it is True, the baseline will be plotted.

  • title (str, optional) – If specified, add a super title to the plot.

  • return_fig (bool, optional) – If it is True, returns the figure object.

Returns:

result – A PlotResult object which contains the following attributes.

fig: Figure axes: Axes trimming : TrimmingInfo

Return type:

PlotResult

copy(xr_slices=None, uv_slices=None)#

Returns a deep copy of this object.

Parameters:

  • xr_slices ((xr_islice, xr_jslice), optional.) – If specified, the returned copy contains the deep copies of elements xrM[xr_islice:xr_jslice] and qv[xr_islice]. Otherwise, the returned copy contains the deep copies of elements xrM and qv.

  • uv_slices ((uv_islice, uv_jslice), optional.) – If specified, the returned copy contains the deep copies of elements uvM[uv_islice:uv_jslice] and wv[uv_islice]. Otherwise, the returned copy contains the deep copies of elements uvM and wv.

Returns:

A deep copy of the SSD object with the specified slices applied.

Return type:

SecSaxsData

Examples

>>> copied_ssd = ssd.copy()
>>> trimming = ssd.make_trimming()
>>> trimmed_ssd = ssd.copy(xr_slices=trimming.xr_slices, uv_slices=trimming.uv_slices)
trimmed_copy(trimming=None, jranges=None, mapping=None, nsigmas=None)#
Parameters:

  • trimming (TrimmingInfo, optional) – If specified, the trimming information will be used for the copy.

  • jranges (tuple of (double, double), optional) – The temporal ranges to apply for trimming in the form of [(start1, end1), (start2, end2)].

  • mapping (MappingInfo, optional) – If specified, the mapping information will be used for the copy. It must be provided if jranges is specified.

  • nsigmas (int or float, optional) – If specified, passed to make_trimming() to control the σ-window width.

Returns:

A trimmed copy of the SSD object with the specified trimming specification applied.

Return type:

SecSaxsData

set_baseline_method(method)#

Sets the baseline method to be used for the baseline correction.

See also: Baseline Correction

Parameters:

method (str or (str, str)) –

Specifies the baseline method to be used. If it is a string, it will be used for both XR and UV data. If it is a tuple of two strings, the first string will be used for XR data and the second string will be used for UV data.

The available methods are:

  • linear : Linear baseline (default)

  • uvdiff : UV differential method (for UV data only)

  • integral : Integral method

Return type:

None

get_baseline_method()#

Returns the baseline method used for the baseline correction.

See also: Baseline Correction

Parameters:

None

Returns:

method – A tuple of two strings which contains the baseline methods used for XR and UV data. If the baseline method is the same for both XR and UV data, it returns a single string instead of a tuple.

Return type:

(str, str)

corrected_copy()#

Returns a deep copy of this object which has been corrected subtracting the baseline from the original data.

Parameters:

debug (bool, optional) – If True, enables debug mode for more verbose output.

Returns:

A deep copy of the SSD object with the baseline correction applied.

Return type:

SecSaxsData

estimate_mapping()#

Estimates the mapping information between UV and XR data. :param debug: If True, enables debug mode for more verbose output. :type debug: bool, optional

Returns:

mapping – A MappingInfo object which contains the mapping information. If the mapping information is not available, returns None.

Return type:

MappingInfo

get_mapping()#

Returns the mapping information object.

Parameters:

None

Returns:

mapping – A MappingInfo object which contains the mapping information. If the mapping information is not available, returns None.

Return type:

MappingInfo

get_concfactor()#

Returns the concentration factor from the beamline information.

Parameters:

None

Returns:

concfactor – The concentration factor from the beamline information. If the beamline information is not available, returns None.

Return type:

float or None

quick_decomposition(num_components=None, proportions=None, xr_peakpositions=None, ranks=None, num_plates=None, **kwargs)#

Performs a quick decomposition of the SEC-SAXS data.

See also: Nontrivial Decomposition

Three decomposition algorithms are available, selected by keyword:

  1. Default (no extra keywords) — greedy peak-recognition.

  2. Proportional (proportions) — area-ratio slicing.

  3. Positioned (xr_peakpositions) — peaks pinned to specified frame positions.

proportions and xr_peakpositions are mutually exclusive.

Parameters:

  • num_components (int, optional) – Specifies the number of components which also implies the SVD rank used to denoise the matrix data.

  • proportions (list of float, optional) –

    Specifies the approximate area ratios of the elution peaks. The values do not need to be normalized; for example, [1, 1], [0.5, 0.5], and [3, 3] all produce the same result because they are normalized internally.

    When this option is given, a proportional decomposition algorithm is used instead of the default peak-recognition algorithm. The proportional algorithm divides the total elution curve by cumulative area according to the given ratios, and fits an EGH model to each slice independently. This provides better initialization for cases with highly overlapping peaks, where the default algorithm may produce unstable results.

    The exact ratios do not need to be known precisely; even a rough estimate (e.g., [2, 1] when the true ratio is [1, 1]) is usually sufficient.

  • xr_peakpositions (list of float, optional) –

    Specifies the frame positions where peaks should be pinned. Uses a penalty-based optimizer (Nelder-Mead) that fits EGH peaks with a strong position constraint. num_components is inferred from the length if not provided.

    Mutually exclusive with proportions.

  • ranks (list of int, optional) – Specifies the ranks to be used for XR data.

  • num_plates (int, optional) – Specifies the number of theoretical plates to be used for the optimization constraint.

  • tau_limit (float, optional) – Maximum allowed ratio |tau| / sigma for positioned decomposition. Default 0.6.

  • max_sigma (float, optional) – Maximum allowed Gaussian width (sigma) for positioned decomposition. Default 80.

  • min_sigma (float, optional) – Minimum allowed Gaussian width (sigma) for positioned decomposition. Default 5.

  • debug (bool, optional) – If True, reload internal modules and show diagnostic plots. Default False.

Returns:

decomposition – A Decomposition object which contains the decomposition result.

Return type:

Decomposition

rigorous_decomposition(num_components=None, proportions=None, ranks=None, num_plates=None, **kwargs)#

Performs a rigorous decomposition of the SEC-SAXS data.

Parameters:

  • num_components (int, optional) – Specifies the number of components which also implies the SVD rank used to denoise the matrix data.

  • proportions (list of float, optional) – Specifies the proportions to be used for XR data.

  • ranks (list of int, optional) – Specifies the ranks to be used for XR data.

  • num_plates (int, optional) – Specifies the number of theoretical plates to be used for the optimization constraint.

Returns:

decomposition – A Decomposition object which contains the decomposition result.

Return type:

Decomposition

inspect_ip_effect()#

Inspects the inter-particle effect of the SEC-SAXS data.

Parameters:

debug (bool, optional) – If True, enables debug mode for more verbose output.

Returns:

ip_effect_info – An IpEffectInfo object which contains the inspection result.

Return type:

IpEffectInfo

get_uv_device_id()#

Returns the UV device ID from the beamline information.

Parameters:

None

Returns:

uv_device_id – The UV device ID from the beamline information. If the beamline information is not available, returns None.

Return type:

str or None

get_beamline_name()#

Returns the beamline name from the beamline information.

Parameters:

None

Returns:

beamline_name – The beamline name from the beamline information. If the beamline information is not available, returns None.

Return type:

str or None

export(folder, prefix=None, fmt='%.18e', xr_only=False, uv_only=Fals)#

Exports the data to a file.

Parameters:

  • folder (str) – Specifies the folder path where the data will be exported.

  • prefix (str, optional) – Specifies the filename prefix to be used for the exported data. If it is None, “PREFIX_” will be used.

  • fmt (str, optional) – Specifies the format to be used for the exported data. The default is ‘%.18e’.

  • xr_only (bool, optional) – If True, only export XR data.

  • uv_only (bool, optional) – If True, only export UV data.

Returns:

filepath – The full path of the exported file.

Return type:

str

plot_varied_decompositions(proportions, **kwargs)#

Plots a set of varied decompositions.

Parameters:

  • proportions (list of float) – A list of proportions to be used for the varied decompositions.

  • rgcurve (object, optional) – A reference to the RG curve to be used for the plot.

  • best (int, optional) – number of best results to be highlighted.

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

Returns:

result – A PlotResult object which contains the following attributes.

fig: Figure axes: Axes

Return type:

PlotResult

get_spectral_vectors()#

Returns the spectral vectors for XR and UV data.

Parameters:

None

Returns:

spectral_vectors – A list of two numpy arrays which contain the spectral vectors for XR and UV data.

Return type:

list of np.ndarray

Contents