LowRank.Decomposition

LowRank.Decomposition#

LowRank.LowRankInfo.py

This module contains the class LowRankInfo, which is used to store information about the components of a SecSaxsData, which is mathematically interpreted as a low rank approximation of a matrix.

class Decomposition(ssd, xr_icurve, xr_ccurves, uv_icurve, uv_ccurves, mapped_curve=None, paired_ranges=None, **kwargs)#

Bases: object

A class to store the result of decomposition which is a low rank approximation.

The result includes both components of X-ray and UV data and their associated information.

ssd#

The SecSaxsData object from which the decomposition was performed.

Type:: SecSaxsData

xr#

The XrData object from the SecSaxsData.

Type:: XrData

xr_icurve#

The i-curve used for the decomposition of the X-ray data.

Type:: Curve

xr_ccurves#

The component curves for the X-ray data.

Type:: list of Curve

xr_ranks#

The ranks for each component of the X-ray data. If None, default ranks are used.

Type:: list of int or None

uv#

The UvData object from the SecSaxsData.

Type:: UvData

uv_icurve#

The i-curve used for the decomposition of the UV data.

Type:: Curve

uv_ccurves#

The component curves for the UV data.

Type:: list of Curve

uv_ranks#

The ranks for each component of the UV data. If None, default ranks are used.

Type:: list of int or None

mapping#

The mapping information between the X-ray and UV data.

Type:: MappingInfo

mapped_curve#

The mapped curve from the X-ray to UV domain. If None, it can be computed when needed.

Type:: MappedCurve or None

paired_ranges#

The paired ranges for the X-ray and UV data. If None, it can be computed when needed.

Type:: list of PairedRange or None

num_components#

The number of components in the decomposition.

Type:: int

Initialize the Decomposition object.

Parameters:

ssd (SecSaxsData) – The SecSaxsData object from which the decomposition was performed.
xr_icurve (Curve) – The i-curve used for the decomposition of the X-ray data.
xr_ccurves (list of Curve) – The component curves for the X-ray data.
uv_icurve (Curve) – The i-curve used for the decomposition of the UV data.
uv_ccurves (list of Curve) – The component curves for the UV data.
mapped_curve (MappedCurve, optional) – The mapped curve from the X-ray to UV domain. If None, it can be computed when needed.
paired_ranges (list of PairedRange, optional) – The paired ranges for the X-ray and UV data. If None, it can be computed when needed.
kwargs (dict, optional) – Additional keyword arguments (not used).

copy_with_new_components(xr_ccurves, uv_ccurves)#

Create a new Decomposition with new component curves.

Parameters:

xr_ccurves (list of Curve) – The new component curves for the X-ray data.
uv_ccurves (list of Curve) – The new component curves for the UV data.

Returns:

A new Decomposition object with the specified component curves.

Return type:

Decomposition

property xr_components#: Alias for xr_ccurves — the XR component curves.

property uv_components#: Alias for uv_ccurves — the UV component curves.

get_num_components()#

Get the number of components.

Returns:: The number of components in the decomposition.
Return type:: int

get_guinier_objects(debug=False)#

Get the list of Guinier objects for the XR components.

Returns:: The list of Guinier objects for each XR component.
Return type:: list of Guinier

get_rgs()#

Get the list of Rg values for the XR components.

Returns:

rgs – Radius of gyration in Ångströms (Å) for each XR component, in the same order as get_xr_components(). If Guinier fitting fails for a component, float('nan') is returned for that position (never None), so the result is always safe to use in numeric / numpy operations.

Guard pattern:

import math
for i, rg in enumerate(decomp.get_rgs()):
    if math.isnan(rg):
        print(f"Component {i+1}: Guinier fit failed")
    else:
        print(f"Component {i+1}: Rg = {rg:.2f} Å")

Return type:

list of float, length n_components

get_rg_curve()#

Compute the per-frame Rg curve from the raw XR data.

Runs a Guinier fit on every elution frame independently and returns the results as an RgCurve object. This is useful for assessing whether a peak is a pure single-component species (flat Rg vs. frame) or a heterogeneous mixture (varying Rg).

Note

This can be slow for large datasets because it fits one Guinier region per frame.

Returns:

rgcurve – An RgCurve with attributes:

.x — frame indices (integer array)
.y — Rg values in Å; NaN where Guinier fit failed
.scores — Guinier fit quality scores (0–1)

Return type:

molass.Guinier.RgCurve.RgCurve

Examples

rgcurve = decomp.get_rg_curve()
import matplotlib.pyplot as plt
plt.plot(rgcurve.x, rgcurve.y, '.')
plt.xlabel("Frame")
plt.ylabel("Rg (Å)")
plt.title("Rg vs. elution frame")
plt.show()

get_P_at(q_target, normalize=False)#

Return the XR scattering matrix P interpolated onto q_target.

Parameters:

q_target (array-like, shape (m,)) – Target q-values in Å⁻¹.
normalize (bool, optional) – If True, each component column is divided by its maximum so that all columns peak at 1. Default False.

Returns:

P_interp – Scattering matrix P evaluated at q_target.

Return type:

np.ndarray, shape (m, n_components)

component_quality_scores()#

Compute a per-component reliability score in [0, 1].

Scores blend Rg distinctiveness (70 %) and area proportion (30 %). A score of 0.0 means Guinier fitting failed or Rg is indistinguishable from another component’s. A score near 1.0 means the component is well-separated in Rg and carries a non-trivial fraction of the signal.

Returns:: scores – Reliability score for each component, in the same order as get_rgs() and get_proportions().
Return type:: list of float

See also

is_component_reliable: threshold-based boolean version.

Examples

scores = decomp.component_quality_scores()
for i, s in enumerate(scores):
    print(f"Component {i+1}: reliability = {s:.2f}")

is_component_reliable(index, threshold=0.5)#

Return True if component index has a quality score ≥ threshold.

Parameters:

index (int) – Zero-based component index.
threshold (float, optional) – Minimum score considered reliable. Default 0.5.

Return type:

bool

Examples

if not decomp.is_component_reliable(1):
    print("Component 2 may be a noise artifact.")

plot_components(title=None, fig=None, axes=None, **kwargs)#

Plot the components.

Parameters:

title (str, optional) – If specified, add a super title to the plot.
fig (matplotlib.figure.Figure, optional) – An existing Figure to draw into. If None (default), a new figure is created automatically.
axes (array-like of shape (2, 3), optional) –
A 2×3 array of Axes to draw into. Must be provided together with fig when injecting into an existing subplot grid. If None (default), axes are created automatically inside fig.

Expected layout:
```
axes[0, 0]  UV elution curves
axes[0, 1]  UV absorbance curves
axes[0, 2]  (UV spare / unused)
axes[1, 0]  XR elution curves
axes[1, 1]  XR scattering curves (log scale)
axes[1, 2]  XR Guinier plot  ← Kratky is omitted when axes are injected
```
Note

When both fig and axes are provided the caller is responsible for creating axes with compatible geometry.

Returns:

result – A PlotResult object which contains the following attributes.

fig: The matplotlib Figure object.
axes: A 2×3 array of Axes objects.

Return type:

PlotResult

update_xr_ranks(ranks, debug=False)#

Update the ranks for the X-ray data.

Default ranks are one for each component which means that interparticle interactions are not considered. This method allows the user to set different ranks for each component.

Parameters:: ranks (list of int) – The ranks for each component.
Return type:: None

get_xr_matrices(debug=False)#

Get the factorized matrices for the X-ray (SAXS) data.

Parameters:

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

Returns:

M (np.ndarray, shape (n_q, n_frames)) – Measured scattering intensity matrix. Rows are q-points; columns are elution frames.
C (np.ndarray, shape (n_components, n_frames)) – Elution curves (concentration profiles) for each component. Each row is one component’s elution curve over frames.
P (np.ndarray, shape (n_q, n_components)) – Scattering profiles (form factors) for each component. Each column is one component’s P(q) in absolute or relative intensity units (matching the scale of M).
Pe (np.ndarray, shape (n_q, n_components)) – Estimated error (standard deviation) on P, propagated from the measurement error matrix.

Notes

The q-values corresponding to the n_q rows are stored in decomp.xr.qv (shape (n_q,), units Å⁻¹).

Example

M, C, P, Pe = decomp.get_xr_matrices()
# P[:, 0]  →  scattering profile of component 1
# C[0, :]  →  elution curve of component 1

get_xr_components(debug=False)#

Get the per-component objects for the X-ray (SAXS) data.

Parameters:

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

Returns:

components – One XrComponent per decomposed component, in component order.

Each XrComponent exposes:

get_guinier_object() → Guinier fit result (Rg, I0, fit range)
get_jcurve_array() → np.ndarray shape (n_q, 3): columns are [q, P(q), Pe(q)] in Å⁻¹ and intensity units.
icurve_array → np.ndarray shape (2, n_frames): rows are [frame_x, elution_y].
compute_area() → scalar, integrated elution area.

Return type:

list of XrComponent, length n_components

get_uv_matrices(debug=False)#

Get the matrices for the UV data.

Parameters:: debug (bool, optional) – If True, enable debug mode.
Returns:: The matrices for the UV data.
Return type:: tuple of (np.ndarray, np.ndarray, np.ndarray, np.ndarray)

get_uv_components(debug=False)#

Get the components for the UV data.

Return type:: List of UvComponent objects.

get_pairedranges(mapped_curve=None, area_ratio=0.7, concentration_datatype=2, debug=False)#

Get the paired ranges.

Parameters:

mapped_curve (MappedCurve, optional) – If specified, use this mapped curve instead of computing a new one.
area_ratio (float, optional) – The area ratio for the range computation.
concentration_datatype (int, optional) – The concentration datatype for the range computation.
debug (bool, optional) – If True, enable debug mode.

Returns:

The list of PairedRange objects.

Return type:

list of PairedRange

get_proportions()#

Get the relative area fractions of the XR components.

Returns:: proportions – Normalised elution-curve area fraction for each component, summing to 1.0. Values are in the range [0, 1]. Proportional to the amount (concentration × volume) of each species in the SEC peak region.
Return type:: np.ndarray, shape (n_components,)

compute_scds(debug=False)#

Get the list of SCDs (Score of Concentration Dependence) for the decomposition.

Returns:: The list of SCD values for each component.
Return type:: list of float

get_cd_color_info()#

Get the color information for the concentration dependence.

Returns:

peak_top_xes (list of float) – The list of peak top x values for each component.
scd_colors (list of str) – The list of colors for each component based on their ranks.

optimize_with_model(model_name, rgcurve=None, model_params=None, debug=False)#

Optimize the decomposition with a model.

Parameters:

model_name (str) –
The name of the model to use for optimization.

Supported models:
- SDM: Stochastic Dispersive Model
- EDM: Equilibrium Dispersive Model
rgcurve (Curve, optional) – The Rg curve to use for the optimization.
model_params (dict, optional) – The parameters for the model.
debug (bool, optional) – If True, enable debug mode.

Returns:

result – A new Decomposition object with optimized components.

Return type:

Decomposition

make_rigorous_initparams(baseparams, debug=False)#

Make initial parameters for rigorous optimization.

Parameters:: debug (bool, optional) – If True, enable debug mode.
Returns:: The initial parameters for rigorous optimization.
Return type:: np.ndarray

optimize_rigorously(rgcurve=None, analysis_folder=None, method='BH', niter=20, debug=False)#

Perform a rigorous decomposition.

Parameters:

rgcurve (Curve) – The Rg curve to use for the decomposition.
analysis_folder (str, optional) – The folder to save analysis results.
method (str, optional) – The method to use for rigorous optimization. Default is ‘BH’.
niter (int, optional) – The number of iterations for the optimization. Default is 20.
debug (bool, optional) – If True, enable debug mode.

Returns:

result – A new Decomposition object after rigorous decomposition.

Return type:

Decomposition

LowRank.Decomposition

Contents

LowRank.Decomposition#