Series objects¶

class bioxtasraw.SECM.SECM(file_list, sasm_list, frame_list, parameters, settings)¶

Bases: object

Series measurement object. Was originally a SEC-SAXS measurement (SECM) object. Contains all the information about a series, including the individual scattering profiles, subtracted scattering profiles, baseline corrected scattering profiles, calculated parameter values such as Rg, total and mean intensity for each profile, information about selected buffer ranges and baseline correction ranges, etc.

Variables:

qref (float) – The reference q value specified by I().
qrange (tuple) – The q range specified by calc_qrange_I().
buffer_range (list) – A list defining the set buffer range. The list is made up of a set of sub-ranges, each defined by an entry in the list. Each sub-range item should be a list or tuple where the first entry is the starting index of the range and the second entry is the ending index of the range. So a list like [[0, 10], [100, 110]] would define a buffer range consisting of two sub-ranges, the first from profiles 0-10 in the series and the second from profiles 100-110 in the series.
window_size (int) – The size of the average window used when calculating parameters such as Rg.
mol_type (str) – The macromolecule type used when calculating the Vc M.W.
mol_density (float) – The macromolecular density used when calculating the Vp M.W.
already_subtracted (bool) – Whether the initial input profiles represent an already subtracted series or not.
average_buffer_sasm (bioxtasraw.SASM.SASM) – The average buffer profile from the buffer_range.
baseline_start_range (tuple) – A tuple where the first item is the start of the baseline start range and the second item is the end of the baseline start range.
baseline_end_range (tuple) – A tuple where the first item is the start of the baseline end range and the second item is the end of the baseline end range.
baseline_corr (list) – A list of the baseline correction applied. Each item is a bioxtasraw.SASM.SASM, and there is one for every baseline corrected profile. The intensity is the value subtracted from the starting intensity of the corresponding profile to achieve the baseline corrected intensity.
baseline_type (str) – The baseline type.
baseline_extrap (bool) – Whether the baseline was extrapolated to all profiles.
baseline_fit_results (list) – Only contains items if a linear baseline correction is done. In that case, each item is the linear fit results a, b, and corresponding covariances for a given q value. There is one item per q value of the input profiles.
sample_range (list) – A list defining the set sample range. The list is made up of a set of sub-ranges, each defined by an entry in the list. Each sub-range item should be a list or tuple where the first entry is the starting index of the range and the second entry is the ending index of the range. So a list like [[0, 10], [100, 110]] would define a sample range consisting of two sub-ranges, the first from profiles 0-10 in the series and the second from profiles 100-110 in the series.

I(qref)¶

Sets the reference q value and returns the intensity of each profile at the specified q value (or the closest such value in each profile).

Parameters:	qref (float) – The reference q to get the intensity at.
Returns:	intensity – The intensity of each profile at the given q value.
Return type:	numpy.array

__init__(file_list, sasm_list, frame_list, parameters, settings)¶

Constructor

Parameters:

file_list (list) – A list of strings corresponding to the filenames of each input sasm.
sasm_list (list) – A list of bioxtasraw.SASM.SASM objects, which are the individual scattering profiles that make up the series.
frame_list (list) – A list of the frame numbers of each item in the sasm_list. Usually just range(len(sasm_list))
parameters (dict) – A dictionary of metadata for the object. This should contain at least {‘filename’: filename_with_no_path}.
settings (bioxtasraw.RAWSettings.RawGuiSettings) – RAW settings. Used to try compute the time associated with each input profile.

acquireSemaphore()¶: Acquires a processing semaphore. Useful for multi-threading operations on the series.

append(filename_list, sasm_list, frame_list)¶

Appends new data to the series. Used when operating in an ‘online’ mode during active data collection.

Parameters:	filename_list (list) – A list of strings corresponding to the filenames of each input sasm. sasm_list (list) – A list of bioxtasraw.SASM.SASM objects, which are the individual scattering profiles that make up the series. frame_list (list) – A list of the frame numbers of each item in the sasm_list. Usually just range(len(sasm_list))

appendBCSubtractedSASMs(sub_sasm_list, use_sasm_list, window_size)¶

Appends new baseline corrected subtracted data to the series. Used when operating in an ‘online’ mode during active data collection.

Parameters:	sub_sasm_list (list) – A list of the baseline corrected subtracted profiles. use_sasm_list (list) – A list of bools indicating whether or not the baseline corrected subtracted profiles should be used when calculating parameters such as Rg. window_size (int) – The averaging window size used to calculate the parameters.

appendCalcValues(rg, rger, i0, i0er, vcmw, vcmwer, vpmw, first_frame, window_size)¶

Appends new calculated parameter data to the series. Used when operating in an ‘online’ mode during active data collection.

Parameters:

rg (np.array) – An array of the new Rg values.
rger (np.array) – An array of the new uncertainty in the Rg values.
i0 (np.array) – An array of the new I(0) values.
i0er (np.array) – An array of the new uncertainty in the I(0) values.
vcmw (np.array) – An array of the new volume of correlation M.W. values.
vcmwer (np.array) – An array of the new uncertainty in the Vc M.W. values.
vpmw (np.array) – An array of the new corrected Porod volume M.W. values.
first_frame (int) – The first frame index of the new data.
window_size (int) – The averaging window size used to calculate the parameters.

appendSubtractedSASMs(sub_sasm_list, use_sasm_list, window_size)¶

Appends new subtracted data to the series. Used when operating in an ‘online’ mode during active data collection.

Parameters:	sub_sasm_list (list) – A list of the subtracted profiles. use_sasm_list (list) – A list of bools indicating whether or not the subtracted profiles should be used when calculating parameters such as Rg. window_size (int) – The averaging window size used to calculate the parameters.

averageFrames(range_list, series_type, sim_test, sim_thresh, sim_cor, forced=False)¶

Creates an average profile from the frame ranges defined in the range_list.

Parameters:

range_list (list) – A list defining the input range to be averaged. The list is made up of a set of sub-ranges, each defined by an entry in the list. Each sub-range item should be a list or tuple where the first entry is the starting index of the range and the second entry is the ending index of the range. So a list like [[0, 10], [100, 110]] would define a buffer range consisting of two sub-ranges, the first from profiles 0-10 in the series and the second from profiles 100-110 in the series.
series_type ({'unsub', 'sub', 'baseline'} str, optional) – Determines which type of profile to average. Unsubtracted profiles - ‘unsub’, subtracted profiles - ‘sub’, baseline corrected profiles - ‘baseline’
sim_test ({'CorMap'} str, optional) – Sets the type of similarity test to be used. Currently only CorMap is supported as an option.
sim_thresh (float, optional) – Sets the p value threshold for the similarity test. A higher value is a more strict test (range from 0-1).
sim_cor ({'Bonferroni', 'None'} str, optional) – Sets the multiple testing correction to be used as part of the similarity test. Default is Bonferroni.
forced (bool, optional) – If True, RAW will attempt to average profiles even if the q vectors do not agree or the profiles are not similar. Defaults to False.

Returns:

average_profile (bioxtasraw.SASM.SASM) – The average profile. If averaging fails, returns None.
success (bool) – Whether the average succeeded.
error (tuple) – A tuple of strings. Both are empty if success. If the average failed, it contains either ‘sim’ or ‘q_vector’ to indicate the issue is either the profiles are not all similar or the q vectors do not all match. The second string is the names of the profiles where the check failed.

calc_qrange_I(qrange)¶

Sets the reference q range and returns the intensity of each profile in the specified q range (or the closest such q values in each profile).

Parameters:	qrange (tuple or list) – A tuple or list with two items. The first item is the starting index of the q vector to be used, the second item is the ending index of the q vector to be used, such that q[start:end] returns the desired q range.
Returns:	intensity – The total intensity of each profile in the given q range.
Return type:	numpy.array

extractAll()¶

Extracts all of the series data and returns it as a dict. Useful for pickling the series.

Returns:	all_data – A dictionary with all the series data.
Return type:	dict

getAllParameters()¶

Returns all of the metadata parameters associated with the series as a dictionary.

Returns:	parameters – The metadata associated with the series.
Return type:	dict

getAllSASMs(int_type='unsub')¶

Gets the all profiles in the series.

Parameters:	int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	profiles – A list of bioxtasraw.SASM.SASM profiles corresponding to the selected type.
Return type:	list

getBCSubQrange()¶

Returns the currently selected q range for each baseline corrected profile in the series as described in setBCSubQrange().

Returns:	q_range – A tuple with 2 indices, the start and end of the selected q range, such that q[start:end] returns the desired q range.
Return type:	tuple

getCalcLine()¶

Returns the plotted line for the calculated values of the series, such as Rg. Only used in the RAW GUI.

Returns:	line – The plotted line.
Return type:	matplotlib.lines.Line2D

getFrames()¶

Returns the list of frames suitable for plotting the series intensity. Note that this may be different from the input frame list.

Returns:	frame_list – An array that starts from 0 and runs to the length of the series.
Return type:	numpy.array

getI0()¶

Returns the I(0) and uncertainty in I(0) values for each profile in the series. If the I(0) value is not available for a given profile, then a -1 is returned.

Returns:	i0 (numpy.array) – The I(0) values for each profile in the series. i0er (numpy.array) – The uncertainty in the I(0) values for each profile in the series.

getIntI(int_type='unsub')¶

Returns the total integrated intensity of each profile in the series.

Parameters:	int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	intensity – The total integrated intensity of each profile for the selected profile type.
Return type:	numpy.array

getIofQ(int_type='unsub')¶

Returns the intensity of each profile at the specified q value (or the closest such value in each profile). Use this instead of I() if you don’t want to recalculate the intensity at the given reference q value.

Parameters:	int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	intensity – The intensity of each profile at the given q value for the selected profile type.
Return type:	numpy.array

getIofQRange(int_type='unsub')¶

Returns the intensity of each profile in the specified q range (or the closest such q values in each profile). Use this instead of calc_qrange_I() if you don’t want to recalculate the intensity for the given reference q range.

Parameters:	int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	intensity – The total intensity of each profile in the given q range for the selected profile type.
Return type:	numpy.array

getLine()¶

Returns the plotted line for the series. Only used in the RAW GUI.

Returns:	line – The plotted line.
Return type:	matplotlib.lines.Line2D

getMeanI(int_type='unsub')¶

Returns the mean intensity of each profile in the series.

Parameters:	int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	intensity – The mean intensity of each profile for the selected profile type.
Return type:	numpy.array

getOffset()¶

Returns the offset for the series.

Returns:	offset – The offset.
Return type:	float

getParameter(key)¶

Gets a particular metadata parameter based on the provided key.

Parameters:	key (str) – A string that is a key in the parameters metadata dictionary.
Returns:	The parameter associated with the specified key. If the key is not in the parameter dictionary, None is returned.
Return type:	parameter

getQrange()¶

Returns the currently selected q range for each profile in the series as described in setQrange().

Returns:	q_range – A tuple with 2 indices, the start and end of the selected q range, such that q[start:end] returns the desired q range.
Return type:	tuple

getRg()¶

Returns the Rg and uncertainty in Rg values for each profile in the series. If the Rg value is not available for a given profile, then a -1 is returned.

Returns:	rg (numpy.array) – The Rg values for each profile in the series. rger (numpy.array) – The uncertainty in the Rg values for each profile in the series.

getSASM(index=0, int_type='unsub')¶

Gets the profile at a given frame number.

Parameters:	index (int, optional.) – The index of the profile to return. Defaults to the first profile. int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	profile – A scattering profile.
Return type:	bioxtasraw.SASM.SASM

getSASMList(initial_frame, final_frame, int_type='unsub')¶

Gets the specified profiles of the series in a given frame range.

Parameters:	initial_frame (int) – The starting frame of profiles in the series to get. final_frame (int) – The final frame of profiles in the series to get. int_type ({'unsub', 'sub', 'baseline'} str, optional) – The type of profile to get. Either ‘unsub’ - unsubtracted, ‘sub’ - subtracted, or ‘baseline’ - baseline corrected.
Returns:	profiles – A list of bioxtasraw.SASM.SASM profiles corresponding to the selected type and frame range.
Return type:	list
Raises:	`SASExceptions.DataNotCompatible` – If the frame range is invalid or requesting a profile type not available in the series (such as asking for baseline corrected profiles when no baseline correction has been done).

getScale()¶

Returns the scale factor for the series.

Returns:	scale – The scale factor.
Return type:	float

getSubQrange()¶

Returns the currently selected q range for each subtracted profile in the series as described in setSubQrange().

Returns:	q_range – A tuple with 2 indices, the start and end of the selected q range, such that q[start:end] returns the desired q range.
Return type:	tuple

getTime()¶

Gets the time associated with each scattering profile, if available. Returns an arary of -1 if not available.

Returns:	time – A array of the collection time of each profile, relative to the first.
Return type:	numpy.array

getVcMW()¶

Returns the volume of correlation M.W. and uncertainty values for each profile in the series. If the M.W. value is not available for a given profile, then a -1 is returned.

Returns:	vcmw (numpy.array) – The Vc M.W. values for each profile in the series. vcmwer (numpy.array) – The uncertainty in the Vc M.W. values for each profile in the series.

getVpMW()¶

Returns the corrected Porod volume M.W. and uncertainty values for each profile in the series. If the M.W. value is not available for a given profile, then a -1 is returned. Currently uncertainty is not available, so an array of all -1 is returned.

Returns:	vcmw (numpy.array) – The Vp M.W. values for each profile in the series. vcmwer (numpy.array) – The uncertainty in the Vp M.W. values for each profile in the series. Currently all -1, as this value is not calculated.

offset(offset_value)¶

Applies an absolute offset to the profile intensity. For example, if the offset is 1, then all the the intensities in the profile are increased by 1. Offset supersedes the existing offset, so if the current offset is 1, and an offset_value of 2 is provided, the resulting offset is 2 (not 3).

Scale factors are applied to the individual profiles with the series, not to the overall intensity, so if the profiles are then retrieved from the series they will have the same scale factor as was applied to the series.

Parameters:	offset_value (float) – The offset to be applied to the profile intensity.

releaseSemaphore()¶: Releases a processing semaphore. Useful for multi-threading operations on the series.

reset()¶: Removes scale and offset values from the series.

scale(scale_factor)¶

Applies an absolute scale to the series intensity. The scale factor supersedes the existing scale factor. For example, suppose the scale factor is currently 2. If a scale of 4 is provided, the resulting scale factor is 4 (not 8). Scale factors are always positive.

Scale factors are applied to the individual profiles with the series, not to the overall intensity, so if the profiles are then retrieved from the series they will have the same scale factor as was applied to the series.

Parameters:	scale_factor (float) – The scale factor to be applied to the the profile intensity and uncertainty.

scaleRelative(relscale)¶

Applies a relative scale to the series intensity. If the scale factor is currently 1, then this is the same as scale(). Otherwise, this scales relative to the current scale factor. For example, suppose the scale factor is currently 2. If a relative scale of 2 is provided, the resulting scale factor if 4. Scale factors are always positive.

Scale factors are applied to the individual profiles with the series, not to the overall intensity, so if the profiles are then retrieved from the series they will have the same scale factor as was applied to the series.

Parameters:	relscale (float) – The relative scale factor to be applied to the the profile intensity and uncertainty.

setAllParameters(new_parameters)¶

Sets the parameters dictionary, which contains the series metadata, to the new input value.

Parameters:	new_parameters (dict) – A dictionary containing the new parameters.

setBCSubQrange(n_min, n_max)¶

Sets the q range used for each baseline corrected profile in the series. Useful for trimming leading or trailing values of the q profile that are not useful data.

Parameters:	n_min (int) – The starting index of the q vector to be used. n_max (int) – The ending index of the q vector to be used, such that q[start:end] returns the desired q range.

setBCSubtractedSASMs(sub_sasm_list, use_sub_sasm)¶

Sets the baseline corrected subtracted profiles for the series.

Parameters:	sub_sasm_list (list) – A list of the baseline corrected subtracted profiles. use_sub_sasm (list) – A list of bools indicating whether or not the profiles should be used when calculating parameters such as Rg.

setCalcValues(rg, rger, i0, i0er, vcmw, vcmwer, vpmw)¶

Sets the value of the calculated values for the series. If a value is not available for a given profile than a -1 value should be provided.

Parameters:

rg (np.array) – An array of the Rg values for each profile in the series.
rger (np.array) – An array of the uncertainty in the Rg values for each profile in the series.
i0 (np.array) – An array of the I(0) values for each profile in the series.
i0er (np.array) – An array of the uncertainty in the I(0) values for each profile in the series.
vcmw (np.array) – An array of the volume of correlation M.W. values for each profile in the series.
vcmwer (np.array) – An array of the uncertainty in the volume of correlation M.W. values for each profile in the series.
vpmw (np.array) – An array of the corrected Porod volume M.W. values for each profile in the series.

setParameter(key, value)¶

Sets a particular metadata parameter based on the provided key and value.

Parameters:	key (str) – The name of the new bit of metadata. value (object) – The value of the new bit of metadata. Could be anything that is an acceptable value for a dictionary.

setQrange(n_min, n_max)¶

Sets the q range used for each profile in the series. Useful for trimming leading or trailing values of the q profile that are not useful data.

Parameters:	n_min (int) – The starting index of the q vector to be used. n_max (int) – The ending index of the q vector to be used, such that q[start:end] returns the desired q range.

setScaleValues(scale_factor, offset_value, frame_scale_factor)¶

A convenience method that lets you set the scale offset, and frame scale values all at once.

Note: Frame scale factor is currently not used.

Parameters:	scale_factor (float) – The scale factor to be applied to the series intensity. offset_value (float) – The offset to be applied to the series intensity. frame_scale_factor (float) – The scale factor to be applied to the series frame values.

setSubQrange(n_min, n_max)¶

Sets the q range used for each subtracted profile in the series. Useful for trimming leading or trailing values of the q profile that are not useful data.

Parameters:	n_min (int) – The starting index of the q vector to be used. n_max (int) – The ending index of the q vector to be used, such that q[start:end] returns the desired q range.

setSubtractedSASMs(sub_sasm_list, use_sub_sasm)¶

Sets the subtracted profiles for the series.

Parameters:	sub_sasm_list (list) – A list of the subtracted profiles. use_sub_sasm (list) – A list of bools indicating whether or not the subtracted profiles should be used when calculating parameters such as Rg.

subtractAllSASMs(buffer_sasm, int_type, threshold, qref=None, qrange=None)¶

Subtracts the input buffer profile from all of the profiles in the series to generate subtracted profiles. Does not save the subtracted profiles to the series.

Parameters:

buffer_sasm (bioxtasraw.SASM.SASM) – The buffer profile to be subtracted.
int_type ({'total', 'mean', 'q_val', 'q_range'} str, optional) – The intensity type to use when setting the buffer range. Total integrated intensity - ‘total’, mean intensity - ‘mean’, intensity at a particular q value - ‘q_val’, intensity in a given q range - ‘q_range’. Use of q_val or q_range requires the corresponding parameter to be provided.
threshold (float) – If the ratio of the scattering profile intensity to the average buffer intensity is greater than this threshold, the use_subtracted_sasm flag for that profile will be set to true. This flag can later be used for calculating Rg, M.W., etc, to determine which profiles to attempt the calculation for.
q_val (float, optional) – If int_type is ‘q_val’, the q value used for the intensity is set by this parameter.
q_range (list, optional) – This should have two entries, both floats. The first is the minimum q value of the range, the second the maximum q value of the range. If int_type is ‘q_range’, the q range used for the intensity is set by this parameter.

Returns:

subtracted_sasms (list) – A list of the subtracted profiles (bioxtasraw.SASM.SASM).
use_subtracted_sasms (list) – A list of bool values corresponding to the subtracted profile. If True, the corresponding profile has a intensity ratio above the buffer greater than the threshold, and so should be used when calculating Rg, M.W., and other parameters.

static subtractSASMs(buffer_sasm, sasms, int_type, threshold, qref=None, qrange=None)¶

Subtracts the input buffer profile from the input profiles to generate subtracted profiles.

Parameters:

buffer_sasm (bioxtasraw.SASM.SASM) – The buffer profile to be subtracted.
sasms (list) – A list of profiles to subtract the buffer from.
int_type ({'total', 'mean', 'q_val', 'q_range'} str, optional) – The intensity type to use when setting the buffer range. Total integrated intensity - ‘total’, mean intensity - ‘mean’, intensity at a particular q value - ‘q_val’, intensity in a given q range - ‘q_range’. Use of q_val or q_range requires the corresponding parameter to be provided.
threshold (float) – If the ratio of the scattering profile intensity to the average buffer intensity is greater than this threshold, the use_subtracted_sasm flag for that profile will be set to true. This flag can later be used for calculating Rg, M.W., etc, to determine which profiles to attempt the calculation for.
q_val (float, optional) – If int_type is ‘q_val’, the q value used for the intensity is set by this parameter.
q_range (list, optional) – This should have two entries, both floats. The first is the minimum q value of the range, the second the maximum q value of the range. If int_type is ‘q_range’, the q range used for the intensity is set by this parameter.

Returns:

subtracted_sasms (list) – A list of the subtracted profiles (bioxtasraw.SASM.SASM).
use_subtracted_sasms (list) – A list of bool values corresponding to the subtracted profile. If True, the corresponding profile has a intensity ratio above the buffer greater than the threshold, and so should be used when calculating Rg, M.W., and other parameters.