narumii.dipolar

narumii.dipolar

Fid_single dataclass

Fid_single(filename, reference_idx=None, load_text_options=dict())

Template class for 1D intensity data with single-FID acquisition, such as CT-DRENAR.

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file.	required
reference_idx	int | None	Index representing the position of the reference point in the data array. Default is None.	None
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default {}.	dict()

Attributes:

Name	Type	Description
filename	str | Path | ArrayLike	See Parameters.
reference_idx	int	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, 1D array.
n_points	int	Number of points in the experiment.
modulated	ndarray	Modulated signal (S'), same as data for single-FID acquisition, 1D array.
reference	ndarray	Reference signal (S₀), 1D array.
difference	ndarray	Normalized difference (1 - S'/S₀), 1D array.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter. Default is None.
loop_counter_increment	int	Increment of loop counter. Default is None.
length_per_counter	float	Length of the real x-axis represented by each loop counter. Default is None.
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.
x_discrete	ndarray	Discrete x-axis values corresponding to the data points, 1D array.
x_continuous	ndarray	Continuous x-axis values for plotting the fitted curve, 1D array.

Methods:

Name	Description
set_x_axis	Create the x-axis corresponding to the data array.
calculate_difference	Calculate the relative difference between the data array and a reference.
plot_difference	Plot the relative difference (1 - S'/S₀).
fit	Fit data with an analytical function.
to_fid	Export the data array to an fid file.
to_txt	Export the data array to a txt file.

Examples:

>>> fid = Fid_single("sample.fid")
... fid.calculate_difference(reference_idx=5)
... print(fid.difference)
... fid.to_txt("output.txt")

set_x_axis

set_x_axis(x_initial_value, loop_counter_start, loop_counter_increment, length_per_counter, n_points, num_continuous=100)

Create the x-axis corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
length_per_counter	float	Length per loop counter.	required
n_points	int	Number of points in the experiment.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
self.x_discrete: np.ndarray	Discrete x-axis values for plotting experimental/simulated data.
self.x_continuous: np.ndarray	Artificial x-axis with (usually) more points used for trendlines.
self.loop_counters: np.ndarray	Loop counter array in case needed.

Examples:

>>> fid.set_x_axis(x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, length_per_counter=58.82, n_points=16)

calculate_difference

calculate_difference(reference_idx)

Calculate the reference and difference array from the data.

Parameters:

Name	Type	Description	Default
reference_idx	int	Index representing the position of the reference point in the data array.	required

Returns:

Type	Description
self.difference: np.ndarray	Array of the relative differences between data and reference.

Examples:

>>> fid.calculate_difference(reference_idx=5)

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀).

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments for plt.plot()	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

fit

fit(function, **kwargs)

Fit data with an analytical function.

Parameters:

Name	Type	Description	Default
function	Callable	The function to fit the data.	required
**kwargs		Additional keyword arguments for scipy.optimize.curve_fit().	{}

Returns:

Type	Description
None

plot_fit

plot_fit(**kwargs)

Plot the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plt.plot().	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_fit(show_legend=True)
>>> fig, ax = exp.plot_fit(xlim=(0, 10), ylim=(0, 0.3), color='red')

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, in the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid.to_fid("output.fid")
>>> fid.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str | list[str]	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid.to_txt("output.txt")
>>> fid.to_txt("output.fid", key='difference', fmt='%.2f')

Fid_pair dataclass

Fid_pair(filename, truncated_n_points=None, txt_use_first_point_as_reference=False, fid_use_first_point_as_reference=True, load_text_options=dict())

Template class for 1D intensity data with double-FID acquisition, such as REDOR, VT-DRENAR, DQ build-up. The input data should take the form of a 1D array, the first half of the array being the modulated data, and the second half of the data being the reference data.

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file. Could be either a .txt file, .fid file, or a 1D/2D array.	required
truncated_n_points	int | None	Truncate the data to first n points.	None
txt_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the second half of the data if False. Only used when the input file is .txt. Default is False.	False
fid_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the second half of the data if False. Only used when the input file is .fid. Default is True.	True
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default is {}.	dict()

Attributes:

Name	Type	Description
filename	str | Path | ArrayLike	See Parameters.
truncated_n_points	int	See Parameters.
txt_use_first_point_as_reference	bool	See Parameters.
fid_use_first_point_as_reference	bool	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, reshaped to (2, n_points) array.
n_points	int	Number of points in the experiment.
modulated	ndarray	Modulated signal (S', first FID), 1D array.
modulated_untruncated	ndarray	Modulated signal (S', first FID) without truncation, 1D array.
reference	ndarray	Reference signal (S₀, second FID), 1D array.
reference_untruncated	ndarray	Reference signal (S₀, second FID) without truncation, 1D array.
difference	ndarray	Normalized difference (1 - S'/S₀), 1D array.
spin_rate	float	MAS frequency, in Hz.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
rotor_cycles_per_loop	int	Number of rotor cycles per loop.
length_per_counter	float	Length of the real x-axis represented by each increment of the loop counter.
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.
x_discrete	ndarray	The x-axis values corresponding to the data points.
x_continuous	ndarray	Artificial x-axis values for plotting the fitted curve.
loop_counters	ndarray	Loop counter values.
popt	ndarray	Optimized parameters from curve fitting.
pconv	ndarray	Covariance matrix from curve fitting.
predict	ndarray	Fitted curve prediction values on time_continuous.

Methods:

Name	Description
apply_truncation	Truncate the data to first n points.
set_x_axis	Create the x-axis values corresponding to the data array.
plot_difference	Plot the relative difference (1 - S'/S₀).
fit	Fit data with an analytical function.
plot_fit	Plot the fitted curve together with the experimental data.
to_fid	Export the data array to an fid file, in the format of a SIMPSON output.
to_txt	Export the data array to a txt file.

Examples:

>>> fid_pair = Fid_pair("redor_data.txt")
... fid_pair.apply_truncation(8)
... print(fid_pair.difference)
... fid_pair.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)
... fid_pair.to_txt("output_difference.txt", key='difference')

apply_truncation

apply_truncation(truncated_n_points)

Truncate the data to first n points.

Parameters:

Name	Type	Description	Default
truncated_n_points		Number of points to keep after truncation.	required

Returns:

Type	Description
None

set_x_axis

set_x_axis(spin_rate, x_initial_value, loop_counter_start, loop_counter_increment, rotor_cycles_per_loop, num_continuous=100)

Create the x-axis values corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
spin_rate	float	MAS frequency, in Hz.	required
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
rotor_cycles_per_loop	int	Number of rotor cycles per loop.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> fid_pair.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀).

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments for plt.plot().	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

fit

fit(function, **kwargs)

Fit data with an analytical function.

Parameters:

Name	Type	Description	Default
function	Callable	The function to fit the data.	required
**kwargs		Additional keyword arguments for scipy.optimize.curve_fit().	{}

Returns:

Type	Description
None

plot_fit

plot_fit(**kwargs)

Plot the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plt.plot().	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_fit(show_legend=True)
>>> fig, ax = exp.plot_fit(xlim=(0, 10), ylim=(0, 0.3), color='red')

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, in the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid_pair.to_fid("output.fid")
>>> fid_pair.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid_pair.to_txt("output.txt")
>>> fid_pair.to_txt("output.fid", key='difference', fmt='%.2f')

Fid_triple dataclass

Fid_triple(filename, truncated_n_points=None, txt_use_first_point_as_reference=False, fid_use_first_point_as_reference=True, alpha=1, load_text_options=dict())

Template class for 1D intensity data with triple-FID acquisition, such as compensated REDOR. The compensated difference is calculated as uncompensated difference + alpha * difference between compensated and reference signal. The input data should take the form of a 1D array, the first 1/3 of the array being the modulated data, the second 1/3 being the additional compensated data, te last 1/3 being the reference data.

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file.	required
truncated_n_points	int | None	Truncate the data to first n points.	None
alpha	float	Compensation factor for triple-FID acquisition. Default is 1.	1
txt_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the last 1/3 of the data if False. Only used when the input file is .txt. Default is False.	False
fid_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the last 1/3 of the data if False. Only used when the input file is .fid. Default is True.	True
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default is {}.	dict()

Attributes:

Name	Type	Description
filename	str | Path | ArrayLike	See Parameters.
truncated_n_points	int	See Parameters.
alpha	float	See Parameters.
txt_use_first_point_as_reference	bool	See Parameters.
fid_use_first_point_as_reference	bool	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, reshaped to (3, n_points) array.
n_points	int	Number of points in the experiment.
modulated	ndarray	Modulated signal (S', first FID), 1D array.
modulated_untruncated	ndarray	Modulated signal (S', first FID) before truncation, 1D array
compensated	ndarray	Compensated signal (S*, second FID), 1D array.
compensated_untruncated	ndarray	Compensated signal (S*, second FID) before truncation, 1D array.
reference	ndarray	Reference signal (S₀, third FID), 1D array.
reference_untruncated	ndarray	Reference signal (S₀, third FID) before truncation, 1D array.
difference	ndarray	Normalized difference with compensation ((1 - S'/S₀) + alpha(1 - S/S₀)), 1D array.
difference_not_compensated	ndarray	Normalized difference without compensation (1 - S'/S₀), 1D array.
spin_rate	float	MAS frequency, in Hz.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
rotor_cycles_per_loop	int	Number of rotor cycles per loop.
length_per_counter	float	Length per loop counter.
num_continuous	int	Number of points for continuous x-axis. Default is 100.
x_discrete	ndarray	The x-axis values corresponding to the data points, 1D array.
x_continuous	ndarray	Artificial x-axis values for plotting the fitted curve, 1D array.
loop_counters	ndarray	Loop counter values, 1D array.
popt	ndarray	Optimized parameters from curve fitting.
pconv	ndarray	Covariance matrix from curve fitting.
predict	ndarray	Fitted curve prediction values on time_continuous.

Methods:

Name	Description
apply_truncation	Truncate the data to first n points.
set_x_axis	Create the x-axis corresponding to the data array.
calculate_difference	Calculate the relative difference between the data array and a reference.
plot_difference	Plot the relative difference (1 - S'/S₀) with compensation.
fit	Fit data with an analytical function.
plot_fit	Plot the fitted curve together with the experimental data.
to_fid	Export the data array to an fid file.
to_txt	Export the data array to a txt file.

Examples:

>>> fid_triple = Fid_triple("compensated_redor.txt", alpha=1.0)
... print(fid_triple.difference)
... fid_triple.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)
... fid_triple.to_txt("output_difference.txt", key='difference')

apply_truncation

apply_truncation(truncated_n_points)

Truncate the data.

set_x_axis

set_x_axis(spin_rate, x_initial_value, loop_counter_start, loop_counter_increment, rotor_cycles_per_loop, num_continuous=100)

Create the x-axis corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
spin_rate	float	MAS frequency, in Hz.	required
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
rotor_cycles_per_loop	int	Number of rotor cycles per loop.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> fid_triple.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)

calculate_difference

calculate_difference(modulated, compensated, reference)

Calculate the reference and difference array from the data.

Parameters:

Name	Type	Description	Default
modulated	ndarray	Modulated signal (S'), 1D array.	required
compensated	ndarray	Compensated signal (S*), 1D array.	required
reference	ndarray	Reference signal (S₀), 1D array.	required

Returns:

Type	Description
self.difference: np.ndarray	Array of the compensated differences.

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀) against the phase angle.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments for plt.plot()	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

fit

fit(function, **kwargs)

Fit data with an analytical function.

Parameters:

Name	Type	Description	Default
function	Callable	The function to fit the data.	required
**kwargs		Additional keyword arguments for scipy.optimize.curve_fit().	{}

Returns:

Type	Description
None

plot_fit

plot_fit(**kwargs)

Plot the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_fit(show_legend=True)
>>> fig, ax = exp.plot_fit(xlim=(0, 10), ylim=(0, 0.3), color='red')

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, following the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'compensated', 'difference_not_compensated', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid_triple.to_fid("output.fid")
>>> fid_triple.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file, following the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'compensated', 'difference_not_compensated', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid_triple.to_txt("output.txt")
>>> fid_triple.to_txt("output.fid", key='difference', fmt='%.2f')

CTDrenar dataclass

CTDrenar(filename, reference_idx=None, load_text_options=dict(), phase_range=None, phase_increment=None, l0=None, rotor_cycles_per_l0=16, spin_rate=None, num_continuous=100, verbose=False)

Bases: Fid_single

Class for handling CT-DRENAR data, a single-FID acquisition experiment with phase incrementation. The input data is a txt or SIMPSON fid file with a 1D data array.

References

Ren, J. & Eckert, H. (2015). Measurement of homonuclear magnetic dipole-dipole interactions in multiple 1/2-spin systems using constant-time DQ-DRENAR NMR. Journal of Magnetic Resonance, 260(1), 46-53. https://doi.org/10.1016/j.jmr.2015.08.022

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file.	required
reference_idx	int | None	Index representing the position of the reference point in the data array. Default is None.	None
phase_range	tuple[float, float] | None	Phase range (min_phase, max_phase) in degrees. Default is None.	None
phase_increment	float | None	Increment of phase in degrees. Default is None.	None
reference_idx	int | None	Index of the reference point in the data. Default is None (and the middle point of the data is taken if n_points is odd).	None
l0	int | None	Loop counter for the first point. Default is None.	None
rotor_cycles_per_l0	int	Number of rotor cycles in the looping block when l0 = 1. Default is 16 (two BaBa-xy16).	16
spin_rate	float | None	Spinning rate in kHz. Default is None.	None
num_continuous	int	Number of points for continuous x-axis. Default is 100.	100
verbose	bool	Whether to print detailed information during initialization. Default is False.	False
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default {}.	dict()

Attributes:

Name	Type	Description
filename	str | Path | ArrayLike	See Parameters.
reference_idx	int	See Parameters.
phase_range	tuple[float, float]	See Parameters.
phase_increment	float	See Parameters.
reference_idx	int	See Parameters.
l0	int	See Parameters.
spin_rate	float	See Parameters.
num_continuous	int	See Parameters.
verbose	bool	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, 1D array.
n_points	int	Number of points in the experiment.
modulated	ndarray	Modulated signal (S'), same as data for single-FID acquisition, 1D array.
reference	ndarray	Reference signal (S₀), 1D array.
difference	ndarray	Normalized DQ intensity (1 - S'/S₀), 1D array.
phase_discrete	ndarray	Discrete phase values in degrees, 1D array.
phase_continuous	ndarray	Continuous phase values for plotting the fitted curve, in degrees, 1D array.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter. Default is None.
loop_counter_increment	int	Increment of loop counter. Default is None.
length_per_counter	float	Length of the real x-axis represented by each loop counter. Default is None.
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.
x_discrete	ndarray	Discrete x-axis values corresponding to the data points, 1D array.
x_continuous	ndarray	Continuous x-axis values for plotting the fitted curve, 1D array.
recoupling_time	float	Recoupling time calculated from l0 and spin rate (if provided), in ms.
popt	ndarray	Optimized parameters from curve fitting.
pconv	ndarray	Covariance matrix from curve fitting.
z_opt	float	Optimized z-value from fitting, in ms².
beff_opt	float	Effective dipolar coupling constant from fitting, in kHz.
predict	ndarray	Fitted curve prediction values on phase_continuous.

Methods:

Name	Description
set_x_axis	Create the x-axis corresponding to the data array.
calculate_difference	Calculate the relative difference between the data array and a reference.
plot_difference	Plot the relative difference (1 - S'/S₀) against the phase angle.
fit	Fit CT-DRENAR data with the analytical function and calculate the effective dipolar coupling constant
plot_fit	Plot the fitted curve against the experimental data.
to_fid	Export the data array to an fid file.
to_txt	Export the data array to a txt file.

Examples:

>>> exp = CTDrenar("ct_drenar.txt", l0=2, spin_rate=17)
... print(exp.difference)
... fig, ax = exp.plot_difference()
... beff = exp.fit()
... fig, ax = exp.plot_fit(show_legend=True)

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀) against the phase angle.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments for plt.plot()	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

fit

fit(function=ctdrenar, **kwargs)

Fit CT-DRENAR data with the analytical function and calculate the effective dipolar coupling constant.

Parameters:

Name	Type	Description	Default
function	Callable	The function to fit the data. Default is functions.ctdrenar.	ctdrenar
**kwargs	Any	Additional keyword arguments for scipy.optimize.curve_fit().	{}

Returns:

Type	Description
None

plot_fit

plot_fit(**kwargs)

Plotting the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

set_x_axis

set_x_axis(x_initial_value, loop_counter_start, loop_counter_increment, length_per_counter, n_points, num_continuous=100)

Create the x-axis corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
length_per_counter	float	Length per loop counter.	required
n_points	int	Number of points in the experiment.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
self.x_discrete: np.ndarray	Discrete x-axis values for plotting experimental/simulated data.
self.x_continuous: np.ndarray	Artificial x-axis with (usually) more points used for trendlines.
self.loop_counters: np.ndarray	Loop counter array in case needed.

Examples:

>>> fid.set_x_axis(x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, length_per_counter=58.82, n_points=16)

calculate_difference

calculate_difference(reference_idx)

Calculate the reference and difference array from the data.

Parameters:

Name	Type	Description	Default
reference_idx	int	Index representing the position of the reference point in the data array.	required

Returns:

Type	Description
self.difference: np.ndarray	Array of the relative differences between data and reference.

Examples:

>>> fid.calculate_difference(reference_idx=5)

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, in the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid.to_fid("output.fid")
>>> fid.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str | list[str]	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid.to_txt("output.txt")
>>> fid.to_txt("output.fid", key='difference', fmt='%.2f')

Redor dataclass

Redor(filename, truncated_n_points=None, txt_use_first_point_as_reference=False, fid_use_first_point_as_reference=True, load_text_options=dict(), l0=None, l10=None, spin_rate=None, gamma_I=None, gamma_S=None, num_continuous=100, verbose=False)

Bases: Fid_pair

Class for handling REDOR data, a double-FID acquisition experiment with time incrementation.

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file. Could be either a .txt file, .fid file, or a 1D/2D array.	required
truncated_n_points	int | None	Truncate the data to first n points.	None
l0	int | None	Rotor cycles for the first point. Default is None.	None
l10	int | None	Increment constant defined in the pulse program. Default is None.	None
spin_rate	float | None	Spinning rate in kHz. Default is None.	None
gamma_I	float | None	Gyromagnetic ratio of the observed nucleus in MHz/T. Default is None.	None
gamma_S	float | None	Gyromagnetic ratio of the dephasing nucleus in MHz/T. Default is None.	None
truncated_n_points	int | None	Truncated number of points to use. Default is None.	None
num_continuous	int	Number of points for continuous x-axis. Default is 100.	100
txt_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the second half of the data if False. Only used when the input file is .txt. Default is False.	False
fid_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the second half of the data if False. Only used when the input file is .fid. Default is True.	True
verbose	bool	Whether to print detailed information during initialization. Default is False.	False
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default is {}.	dict()

Attributes:

Name	Type	Description
filename	str | Path | ArrayLike	See Parameters.
truncated_n_points	int	See Parameters.
l0	int	See Parameters.
l10	int	See Parameters.
spin_rate	float	See Parameters.
gamma_I	float	See Parameters.
gamma_S	float	See Parameters.
truncated_n_points	int	See Parameters.
num_continuous	int	See Parameters.
txt_use_first_point_as_reference	bool	See Parameters.
fid_use_first_point_as_reference	bool	See Parameters.
verbose	bool	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, reshaped to (2, n_points) array.
n_points	int	Number of data points in the experiment.
modulated	ndarray	Modulated signal (S', first FID), 1D array.
modulated_untruncated	ndarray	Modulated signal (S', first FID) without truncation, 1D array.
reference	ndarray	Reference signal (S₀, second FID), 1D array.
reference_untruncated	ndarray	Reference signal (S₀, second FID) without truncation, 1D array.
difference	ndarray	Normalized difference (1 - S'/S₀), 1D array.
spin_rate	float	MAS frequency, in Hz.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
rotor_cycles_per_loop	int	Number of rotor cycles per loop. Default is 1.
length_per_counter	float	Length of the real x-axis represented by each increment of the loop counter.
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.
time_discrete	ndarray	Discrete time values corresponding to data points, in ms, 1D array.
time_continuous	ndarray	Continuous time values for plotting the fitted curve, in ms, 1D array.
x_discrete	ndarray	The x-axis values corresponding to the data points.
x_continuous	ndarray	Artificial x-axis values for plotting the fitted curve.
loop_counters	ndarray	Loop counter values, 1D array.
popt	ndarray	Optimized parameters from curve fitting.
pconv	ndarray	Covariance matrix from curve fitting.
z_opt	float	Optimized z-value from fitting, in kHz².
b_opt	float	Optimized nuclear dipolar coupling constant (b) from fitting.
r_opt	float	Optimized distance from fitting, in Å.
predict	ndarray	Fitted curve prediction values on time_continuous.

Methods:

Name	Description
apply_truncation	Truncate the data to first n points.
set_time_axis	Create the time axis corresponding to the data array using rotor cycle parameters.
plot_difference	Plot the normalized difference (1 - S'/S₀) against the recoupling time.
fit	Fit REDOR data with the analytical function and calculate the effective dipolar coupling constant.
plot_fit	Plot the fitted curve together with the experimental data.
to_fid	Export the data array to an fid file, in the format of a SIMPSON output.
to_txt	Export the data array to a txt file.

Examples:

>>> exp = Redor("redor_data.txt", l0=1, l10=1, spin_rate=17.0, truncated_n_points=8)
>>> print(exp.difference)
>>> fig, ax = exp.plot_difference()
>>> exp.set_time_axis(l0, l10, spin_rate)
>>> exp.gamma_I, exp.gamma_S = gamma.C, gamma.P
>>> exp.fit()
... fig, ax = exp.plot_fit(show_legend=True)

set_time_axis

set_time_axis(spin_rate, l0, l10, rotor_cycles_per_loop, num_continuous=100)

Create the time axis corresponding to the data array. In the form of initial_value + (1/spin_rate)*[list of loop counter with defined start value (l0 + 1), increment (l10 * 2), and number of points].

Parameters:

Name	Type	Description	Default
l0	int	Rotor cycles for the first point.	required
l10	int	Increment constant defined in the pulse program.	required
spin_rate	float	Spinning rate in kHz.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> exp.set_time_axis(l0=1, l10=1, spin_rate=17.0)

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀) against the recoupling time.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_difference()
>>> fig, ax = exp.plot_difference(xlim=(0, 10), ylim=(0, 0.3))

fit

fit(function=redor_bessel(5), **kwargs)

Fit REDOR data with the analytical function and calculate the effective dipolar coupling constant.

Parameters:

Name	Type	Description	Default
function	Callable	The function to fit the data. Default is narumii.functions.redor_bessel(5).	redor_bessel(5)

Returns:

Type	Description
None

Examples:

>>> exp.fit()
... print(f'Effective coupling constant: {exp.b_opt:.3f} kHz, distance: {exp.r_opt:.3f} Å')

plot_fit

plot_fit(**kwargs)

Plot the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_fit(show_legend=True)
>>> fig, ax = exp.plot_fit(xlim=(0, 10), ylim=(0, 0.3), color='red')

apply_truncation

apply_truncation(truncated_n_points)

Truncate the data to first n points.

Parameters:

Name	Type	Description	Default
truncated_n_points		Number of points to keep after truncation.	required

Returns:

Type	Description
None

set_x_axis

set_x_axis(spin_rate, x_initial_value, loop_counter_start, loop_counter_increment, rotor_cycles_per_loop, num_continuous=100)

Create the x-axis values corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
spin_rate	float	MAS frequency, in Hz.	required
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
rotor_cycles_per_loop	int	Number of rotor cycles per loop.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> fid_pair.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, in the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid_pair.to_fid("output.fid")
>>> fid_pair.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid_pair.to_txt("output.txt")
>>> fid_pair.to_txt("output.fid", key='difference', fmt='%.2f')

Redor3 dataclass

Redor3(filename, truncated_n_points=None, txt_use_first_point_as_reference=False, fid_use_first_point_as_reference=True, alpha=1, load_text_options=dict(), l0=None, l10=None, spin_rate=None, gamma_I=None, gamma_S=None, num_continuous=100, verbose=False)

Bases: Fid_triple

Class for handling compensated REDOR data, a triple-FID acquisition experiment with time incrementation.

References

Gullion, T., & Schaefer, J. (2000). Eliminating artifacts from baseline distortion in rotational-echo double-resonance NMR. Journal of Magnetic Resonance, 144(1), 174-180. https://doi.org/10.1006/jmre.2000.2191

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file.	required
alpha	float	Compensation factor defined in the pulse program. Default is 1.	1
l0	int | None	Rotor cycles for the first point. Default is None.	None
l10	int | None	Increment constant defined in the pulse program. Default is None.	None
spin_rate	float | None	Spinning rate in kHz. Default is None.	None
gamma_I	float | None	Gyromagnetic ratio of the observed nucleus in MHz/T. Default is None.	None
gamma_S	float | None	Gyromagnetic ratio of the dephasing nucleus in MHz/T. Default is None.	None
truncated_n_points	int | None	Truncated number of points to use. Default is None.	None
num_continuous	int	Number of points for continuous x-axis. Default is 100.	100
verbose	bool	Whether to print detailed information during initialization. Default is False.	False
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default is {}.	dict()

Attributes:

Name	Type	Description
filename	str	See Parameters.
alpha	float	See Parameters.
l0	int	See Parameters.
l10	int	See Parameters.
spin_rate	float	See Parameters.
gamma_I	float	See Parameters.
gamma_S	float	See Parameters.
truncated_n_points	int	See Parameters.
num_continuous	int	See Parameters.
verbose	bool	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, reshaped to (3, n_points) array.
n_points	int	Number of data points in the experiment.
modulated	ndarray	Modulated signal (S', first FID), 1D array.
modulated_untruncated	ndarray	Modulated signal (S', first FID) before truncation, 1D array
compensated	ndarray	Compensated signal (S*, second FID), 1D array.
compensated_untruncated	ndarray	Compensated signal (S*, second FID) before truncation, 1D array.
reference	ndarray	Reference signal (S₀, third FID), 1D array.
reference_untruncated	ndarray	Reference signal (S₀, third FID) before truncation, 1D array.
difference	ndarray	Normalized difference with compensation ((1 - S'/S₀) + alpha(1 - S/S₀)), 1D array.
difference_not_compensated	ndarray	Normalized difference without compensation (1 - S'/S₀), 1D array.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
rotor_cycles_per_loop	int	Number of rotor cycles per loop. Default is 1.
length_per_counter	float	Length per loop counter.
time_discrete	ndarray	Discrete time values corresponding to data points, in ms, 1D array.
time_continuous	ndarray	Continuous time values for plotting the fitted curve, in ms, 1D array.
x_discrete	ndarray	The x-axis values corresponding to the data points, 1D array.
x_continuous	ndarray	Artificial x-axis values for plotting the fitted curve, 1D array.
loop_counters	ndarray	Loop counter values, 1D array.
popt	ndarray	Optimized parameters from curve fitting.
pconv	ndarray	Covariance matrix from curve fitting.
z_opt	float	Optimized z-value from fitting, in kHz².
b_opt	float	Effective dipolar coupling constant from fitting, in kHz.
r_opt	float	Optimized distance from fitting, in Å.
predict	ndarray	Fitted curve prediction values on time_continuous.

Methods:

Name	Description
set_time_axis	Create the time axis corresponding to the data array using rotor cycle parameters.

Examples:

>>> exp = Redor3("compensated_redor.txt", alpha=1.0, l0=1, l10=1, spin_rate=17.0)
>>> fig, ax = exp.plot_difference()
>>> exp.set_time_axis(0, l0 + 1, l10 * 2, 1/spin_rate, n_points)
>>> exp.gamma_I, exp.gamma_S = narumii.gamma.C, narumii.gamma.P
>>> exp.fit()
... fig, ax = exp.plot_fit(show_legend=True)

set_time_axis

set_time_axis(spin_rate, l0, l10, rotor_cycles_per_loop, num_continuous=100)

Create the time axis corresponding to the data array. In the form of initial_value + (1/spin_rate)*[list of loop counter with defined start value (l0 + 1), increment (l10 * 2), and number of points].

Parameters:

Name	Type	Description	Default
spin_rate	float	Spinning rate in kHz.	required
l0	int	Rotor cycles for the first point.	required
l10	int	Increment constant defined in the pulse program.	required
rotor_cycles_per_loop	int	Number of rotor cycles per loop.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> exp = Redor3("compensated_redor.txt", alpha=1.0)
... exp.set_time_axis(l0=1, l10=1, spin_rate=17.0)

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀) against the recoupling time.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_difference()
>>> fig, ax = exp.plot_difference(xlim=(0, 10), ylim=(0, 0.3))

fit

fit(function=redor_bessel(5), **kwargs)

Fit REDOR data with the analytical function and calculate the effective dipolar coupling constant.

Parameters:

Name	Type	Description	Default
function	Callable	The function to fit the data. Default is narumii.functions.redor_bessel(5).	redor_bessel(5)

Returns:

Type	Description
None

Examples:

>>> exp.fit()
... print(f'Effective coupling constant: {exp.b_opt:.3f} kHz, distance: {exp.r_opt:.3f} Å')

apply_truncation

apply_truncation(truncated_n_points)

Truncate the data.

set_x_axis

set_x_axis(spin_rate, x_initial_value, loop_counter_start, loop_counter_increment, rotor_cycles_per_loop, num_continuous=100)

Create the x-axis corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
spin_rate	float	MAS frequency, in Hz.	required
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
rotor_cycles_per_loop	int	Number of rotor cycles per loop.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> fid_triple.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)

calculate_difference

calculate_difference(modulated, compensated, reference)

Calculate the reference and difference array from the data.

Parameters:

Name	Type	Description	Default
modulated	ndarray	Modulated signal (S'), 1D array.	required
compensated	ndarray	Compensated signal (S*), 1D array.	required
reference	ndarray	Reference signal (S₀), 1D array.	required

Returns:

Type	Description
self.difference: np.ndarray	Array of the compensated differences.

plot_fit

plot_fit(**kwargs)

Plot the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_fit(show_legend=True)
>>> fig, ax = exp.plot_fit(xlim=(0, 10), ylim=(0, 0.3), color='red')

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, following the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'compensated', 'difference_not_compensated', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid_triple.to_fid("output.fid")
>>> fid_triple.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file, following the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'compensated', 'difference_not_compensated', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid_triple.to_txt("output.txt")
>>> fid_triple.to_txt("output.fid", key='difference', fmt='%.2f')

DoubleQuantum dataclass

DoubleQuantum(filename, truncated_n_points=None, txt_use_first_point_as_reference=False, fid_use_first_point_as_reference=True, load_text_options=dict(), l0=None, l10=None, spin_rate=None, num_continuous=100, verbose=False)

Bases: Fid_pair

Class for handling double quantum build-up data, a double-FID acquisition experiment with time incrementation.

Parameters:

Name	Type	Description	Default
filename	str | Path | ArrayLike	Input data file. Could be either a .txt file, .fid file, or a 1D/2D array.	required
l0	int | None	Rotor cycles for the first point. Default None.	None
l10	int | None	Increment constant defined in the pulse program. Default None.	None
spin_rate	float | None	Spinning rate in kHz. Default None.	None
truncated_n_points	int | None	Truncated number of points to use. Default None.	None
num_continuous	int	Number of points for continuous x-axis. Default 100.	100
txt_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the second half of the data if False. Only used when the input file is .txt. Default is False.	False
fid_use_first_point_as_reference	bool	Determines how the reference data is parsed. Use the first point of the data if True, use the second half of the data if False. Only used when the input file is .fid. Default is True.	True
verbose	bool	Whether to print detailed information during initialization. Default False.	False
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default {}.	dict()

Attributes:

Name	Type	Description
filename	str | Path | ArrayLike	See Parameters.
l0	int	See Parameters.
l10	int	See Parameters.
spin_rate	float	See Parameters.
truncated_n_points	int	See Parameters.
num_continuous	int	See Parameters.
txt_use_first_point_as_reference	bool	See Parameters.
fid_use_first_point_as_reference	bool	See Parameters.
verbose	bool	See Parameters.
load_text_options	dict	See Parameters.
data	ndarray	Raw data read from the file, reshaped to (2, n_points) array.
n_points	int	Number of data points in the experiment.
modulated	ndarray	Modulated signal (S', first FID), 1D array.
modulated_untruncated	ndarray	Modulated signal (S', first FID) without truncation, 1D array.
reference	ndarray	Reference signal (S₀, second FID), 1D array.
reference_untruncated	ndarray	Reference signal (S₀, second FID) without truncation, 1D array.
difference	ndarray	Normalized difference (1 - S'/S₀), 1D array.
x_initial_value	float	Initial value for x-axis. Default is 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
rotor_cycles_per_loop	int	Number of rotor cycles per loop.
length_per_counter	float	Length of the real x-axis represented by each increment of the loop counter.
time_discrete	ndarray	Discrete time values corresponding to data points, in ms, 1D array.
time_continuous	ndarray	Continuous time values for plotting the fitted curve, in ms, 1D array.
x_discrete	ndarray	The x-axis values corresponding to the data points.
x_continuous	ndarray	Artificial x-axis values for plotting the fitted curve.
loop_counters	ndarray	Loop counter values, 1D array.
popt	ndarray	Optimized parameters from curve fitting.
pconv	ndarray	Covariance matrix from curve fitting.
predict	ndarray	Fitted curve prediction values on time_continuous.

Methods:

Name	Description
apply_truncation	Truncate the data to first n points.
set_time_axis	Create the time axis corresponding to the data array using rotor cycle parameters.
plot_difference	Plot the normalized difference (1 - S'/S₀) against the recoupling time.
to_fid	Export the data array to an fid file, in the format of a SIMPSON output.
to_txt	Export the data array to a txt file.

Examples:

>>> exp = DoubleQuantum("dq_buildup.txt", l0=1, l10=1, spin_rate=10.0)
... fig, ax = exp.plot_difference()

set_time_axis

set_time_axis(spin_rate, l0, l10, rotor_cycles_per_loop, num_continuous=100)

Create the time axis corresponding to the data array. In the form of initial_value + (1/spin_rate)*[list of loop counter with defined start value (l0 + 1), increment (l10 * 2), and number of points].

Parameters:

Name	Type	Description	Default
l0	int	Rotor cycles for the first point.	required
l10	int	Increment constant defined in the pulse program.	required
spin_rate	float	Spinning rate in kHz. If not specified, the current attribute self.spin_rate will be used for calculation. Default is None.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> exp.set_time_axis(l0=1, l10=1, spin_rate=17.0)

plot_difference

plot_difference(**kwargs)

Plot the relative difference (1 - S'/S₀) against the recoupling time.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments for plotting.	{}

Returns:

Name	Type	Description
fig	Figure	The created figure object
ax	Axes	The created axes object

Examples:

>>> fig, ax = exp.plot_difference()
>>> fig, ax = exp.plot_difference(xlim=(0, 10), ylim=(0, 0.3))

apply_truncation

apply_truncation(truncated_n_points)

Truncate the data to first n points.

Parameters:

Name	Type	Description	Default
truncated_n_points		Number of points to keep after truncation.	required

Returns:

Type	Description
None

set_x_axis

set_x_axis(spin_rate, x_initial_value, loop_counter_start, loop_counter_increment, rotor_cycles_per_loop, num_continuous=100)

Create the x-axis values corresponding to the data array. In the form of x_initial_value + length_per_counter*[list of loop counter with defined start value, increment, and number of points].

Parameters:

Name	Type	Description	Default
spin_rate	float	MAS frequency, in Hz.	required
x_initial_value	float	Initial value for x-axis.	required
loop_counter_start	int	Starting value of loop counter.	required
loop_counter_increment	int	Increment of loop counter.	required
rotor_cycles_per_loop	int	Number of rotor cycles per loop.	required
num_continuous	int	How many points is generated for an artificial x-axis used for trendlines. Default is 100.	100

Returns:

Type	Description
None

Examples:

>>> fid_pair.set_x_axis(spin_rate=17.0, x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, rotor_cycles_per_loop=2)

to_fid

to_fid(filename, key='data')

Export the data array to an fid file, in the format of a SIMPSON output.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'

Returns:

Type	Description
None

Examples:

>>> fid_pair.to_fid("output.fid")
>>> fid_pair.to_fid("output.fid", key='difference')

to_txt

to_txt(filename, key='data', order='C', fmt='%.6f')

Export the data array to a txt file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the exported file.	required
key	Literal['data', 'modulated', 'reference', 'difference']	Attribute name of which data to export. Default is 'data'.	'data'
order	Literal['C', 'F']	Extra parameter for np.ndarray.reshape, defines whether the elements of the array are read in a C-like order (same row first) or in a Fortran-like order (same column first). Default is 'C'.	'C'
fmt	str	Extra parameter for np.savetxt, controls the format of the output. Check https://numpy.org/devdocs/reference/generated/numpy.savetxt.html for more. Default is '%.6f'.	'%.6f'

Returns:

Type	Description
None

Examples:

>>> fid_pair.to_txt("output.txt")
>>> fid_pair.to_txt("output.fid", key='difference', fmt='%.2f')