DataObjects.SecSaxsData

DataObjects.SecSacsData.py

class SecSaxsData(folder=None, object_list=None, uv_only=False, xr_only=False, trimmed=False, remove_bubbles=False, beamline_info=None, mapping=None, time_initialized=None, datafiles=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.

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.

• 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)

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)

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.

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, ranks=None, num_plates=None, **kwargs)

Performs a quick 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)

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