datared module

Data reduction related functions.

datared.average_time_resolved_signal(diffs_all, delays, ref_delay, delay_lbl_digits=None, err=None, verbose=False)[source]

Average ‘i’ for equivalent values in ‘delays’.

Calculate ‘red_chi2’ and ‘pts_perc’.

Parameters:

  • diff_all (array_like (2D)) – Time-resolved signal.

  • delays (array_like (1D)) – List of time-delays associated to ‘diff_all’. Each column of ‘diff_all’ corresponds to an element of ‘delays’. A given element in ‘delays’ can be repeated several times, i.e. delays != np.unique(delays).

  • ref_delay (str) – Reference time-delay.

  • delay_lbl_digits (int or None, optional) – Number of digits used to convert float delays to strings (in case they were not converted before). Default is None. Default is 2 (i.e. 23.453e-9 –> ‘23ns’)

  • err (array_like (2D) or None, optional) – Errors associated to scattered intensities. If None (default), errors on the average time-resolved signal are calculated as the standard deviation over different shots.

  • use_ratio (bool, optional) – If True, the signal is the ratio between ‘i’ and ‘iref’. If False, the signal is the difference between ‘i’ and ‘iref’. Default is False.

  • red_chi2_max (float or 'auto' or None, optional) – Threshold level to filter out shots on the basis of their reduced-chi2 with respect to the median signal. If ‘auto’, the 95th percentile is used as a threshold. If None (default), the filter is not applied.

Returns:

res – Dictionary containing the following:

  • ’diff_av’: average time-resolved signals (one for each time-delay)

  • ’diff_err’: errors on diff_av.

  • ’t’: unique time-delays

  • ’diffs’: list of time-resolved signals (list of 2D numpy arrays)

  • ’red_chi2’: list of reduced-chi2 (list of 1D numpy arrays)

Notes

  • len(diffs) = len(t); each element in ‘diffs’ is a numpy array containing all shots taken at the same time-delay.

Return type:

dict

datared.calc_time_resolved_signal(i, delays, ref_delay, use_ratio=False, e=None)[source]

Compute time-resolved signals from a set of scattering patterns measured at different time-delays with repetitions.

The most important step is to calculate the appropriate reference pattern for each intensity curve. This is done by interp_refs().

No averaging is performed besides that done by interp_refs().

Paramaters

iarray_like (2D)

Scattered intensity measured at different time-delays.

delaysarray_like (1D)

List of time-delays at which each scattering pattern in ‘i’ has been collected.

ref_delaystr or float

Time-delay to be used as a reference.

use_ratiobool, optional

If True, signal is the ratio between ‘i’ and ‘iref’. If False (default), signal is the difference between ‘i’ and ‘iref’.

returns:

sig – Time-resolved scattering patterns. ‘sig’ has the same shape as ‘i’.

rtype:

2D np.ndarray

datared.datared(data, ref_delay, delay_lbl_digits=2, norm=None, qlim=None, shots=None, use_ratio=False, red_chi2_max=None, pts_perc_max=None, log='id09', scan_motor=None, verbose=True)[source]

Reduce time-resolved dataset.

Parameters:

  • data (dict) – Dictionary containing azimuthally averaged scattering patterns and information about azimuthal average. Keys are ‘q’, ‘i’, ‘e’, ‘folder’, …

  • ref_delay (str or float) – Reference time-delay. If ‘auto’, the minimum time-delay will be used.

  • delay_lbl_digits (int, optional) – Number of digits used to convert float delays to strings. Default is 2 (i.e. 23.453e-9 –> ‘23ns’)

  • norm (tuple or dict or str or None) – If tuple, data is divided (normalized) by the mean in the q-range between norm[0] and norm[1]. If str, ‘norm’ must be one the parameters in the dataset log file. Each pattern is then divided (normalized) by the corresponding parameter value.

  • shots – Mask for selecting a subset of all the collected shots.

  • log (str or dict, optional) – If of type str, the log file to be used to obtain the metadata. If of type dict, expects a dictionary containing the metadata. (default, ‘id09’)

  • scan_motor (None, optional) – Name of motor (as it appears in the log file) whose position was changed during data collection. If None (default), it is disregarded.

  • Results

  • -------

  • ...

Examples

>> datared(data, ref_delay=”-50us”, norm=(2.1, 2.2), qlim=(0, 2.5),

red_chi2_max=3, verbose=True)

datared.datared_core(q, i, delays, e=None, ref_delay=None, delay_lbl_digits=None, norm=None, qlim=None, shots=None, use_ratio=False, red_chi2_max=None, pts_perc_max=None, verbose=True)[source]

Reduce time-resolved dataset.

Parameters:

  • q (ndarray (1D)) – Scattering vector magnitude. Shape: (nq, ).

  • i (ndarray (2D)) – Azimuthally averaged scattering intensities. Shape: (nq, nshots)

  • delays (ndarray (1D)) – List of time-delays. Shape: (nshots, )

  • e (ndarray (2D) or None, optional) – Errors on i. Shape: (nq, nshots)

  • ref_delay (str or float or None, optional) – Reference time-delay to be used for calculating time-resolved signals. If not None, ‘ref_delay’ must be one of the elements of ‘delays’. If None (default), absolute patterns are averaged over different repetitions, but no time-resolved signal is calculated.

  • delay_lbl_digits (int or None, optional) – Number of digits used to convert float delays to strings (in case they were not converted before). Defaults is None.

  • norm (array-like or None, optional) – Data normalization parameter. If array-like, size must be either 2 (q-normalization) or ‘nshots’ (normalization with respect to a monitor). In the first case data are divided by their average in the q-range between norm[0] and norm[1]. In the second case, each scattering pattern is divided by the corresponing element of ‘norm’. If None (default), no normalization is applied.

  • qlim (tuple or dict or None, optional) – Data limits parameter. If tuple or dict, must have size 2. Data outside the (qlim[0], qlim[1]) q-range are discarded. Data limits are applied after data normalization. If None (default), data limits are not applied.

  • shots (array-like or None, optional) – Shots mask. If array-like, size must be either 2 or ‘nshots’. In the first case, shots outside the (shots[0], shots[1]) range are discarded. In the second case, ‘shots’ must be a boolean mask to select the shots to keep and those to discard. If None (default), all shots are retained for data reduction.

  • use_ratio (bool, optional) – If True, the time-resolved signal is calculated as a ratio of intensities. If False (default), the time-resolved signal is calculated as a difference of intensities.

  • red_chi2_max (float or None, optional) – Reduced-chi2 threshold. Patterns that deviate more than ‘red_chi2_max’ from the median over different shots are discarded.

  • pts_perc_max (float or None, optional) – Maximum percentage of points of a pattern that deviate more than sigma from the median over different shots. Default is None.

Returns:

res –

Dictionary containing the following:

  • ’diff_av’: average time-resolved signals (one for each delay)

  • ’diff_err’: errors on diff_av.

  • ’t’: unique time-delays

  • ’diffs’: list of time-resolved signals

  • ’red_chi2’: list of reduced-chi2

  • ’q’, ‘i’, ‘e’: arrays after ‘qlim’, ‘shots’ and ‘norm’

Return type:

dict

Examples

>>> datared(
...     data, ref_delay="-50us", qnorm=(2.1, 2.2), qlim=(0, 2.5),
...     red_chi2_max=3, verbose=True
... )
datared.filt_absolute_scattering()[source]

Filter out absolute patterns.

All patterns between nearest reference shots are also removed.

datared.filt_time_resolved_signal(data, red_chi2_max='auto', pts_perc_max=None, err=None, verbose=False)[source]

Filter time-resolved difference patterns.

filtered data: kept patterns outliers: filtered out patterns

Parameters:

  • data (dict) – Dictionary containing the following: - ‘diff_av’: average time-resolved signals (one for each time-delay) - ‘diff_err’: errors on diff_av. - ‘t’: unique time-delays - ‘diffs’: list of time-resolved signals (list of 2D numpy arrays) - ‘red_chi2’: list of reduced-chi2 (list of 1D numpy arrays)

  • red_chi2_max (float or string or None, optional) – Reduced-chi2 threshold for filtering. If ‘auto’ (default), the 95th-percentile is used as threshold.

  • pts_perc_max (float or None, optional) – Thresholde for the percentage of points …

  • err (array_like (2D) or None, optional) – Errors associated to scattered intensities.

Returns:

filt – Dictionary containing the following: - ‘diffs’: filtered time-resolved difference patterns - ‘diff_av: average of filtered time-resolved difference patterns - ‘diff_err’: errors on diff_av. - ‘red_chi2_filt’: reduced-chi2 on filtered difference patterns - ‘pts_perc_filt’: percentage of points on filtered difference patterns - ‘red_chi2_max’: threshold value actually used for filtering or None - ‘pts_perc_max’: threshold value actually used for filtering or None - ‘diffs_outliers’: outlier time-resolved differnce patterns - ‘outliers’: mask selecting outlier time-resolved difference patterns

Return type:

dict

datared.interp_refs(i, idx_ref)[source]

Linear interpolation of reference curves.

The reference curve for each “shot” is calculated as the average between its two closest reference curves. A weight is introduced in the average to account for the distance between the shot and each of the two closest reference curves.

The first available reference curve is used as the reference for all initial shots. The last available reference curve is used as the reference for all final shots.

The reference curve for each “reference” is not the reference curve itself, but the average of the two closest reference curves.

Parameters:

  • i ((M, N) ndarray) – Input data. The array first index corresponds to the “shot” number.

  • idx_ref (ndarray) – Indeces of reference curves.

Returns:

iref – Reference curves for each curve in ‘i’. If only one reference curve is available, a (N,) ndarray is returned.

Return type:

(M, N) ndarray or (N,) ndarray