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	Input data file.	required
reference_idx	int | None	Index representing the position of the reference point in the data array. Default None.	None
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default {}.	dict()

Attributes:

Name	Type	Description
filename	str	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 0.
loop_counter_start	int	Starting value of loop counter. Default None.
loop_counter_increment	int	Increment of loop counter. Default None.
length_per_counter	float	Length of the real x-axis represented by each loop counter. Default 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.
loop_counters	ndarray	Loop counter values, 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.
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)

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', '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, 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', '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, 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	Input data file.	required
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default {}.	dict()

Attributes:

Name	Type	Description
filename	str	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.
reference	ndarray	Reference signal (S₀, second FID), 1D array.
difference	ndarray	Normalized difference (1 - S'/S₀), 1D array.
x_initial_value	float	Initial value for x-axis. Default 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
length_per_counter	float	Length of the real x-axis represented by each loop counter. Default 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.
loop_counters	ndarray	Loop counter values, 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.
to_fid	Export the data array to an fid file.
to_txt	Export the data array to a txt file.

Examples:

>>> fid_pair = Fid_pair("redor_data.txt")
>>> print(fid_pair.difference)
>>> fid_pair.set_x_axis(x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, length_per_counter=58.82, n_points=16)
>>> fid_pair.to_txt("output_difference.txt", key='difference')

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 of the real x-axis represented by each 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_pair.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(modulated, reference)

Calculate the reference and difference array from the data.

Parameters:

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

Returns:

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

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', '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, 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', '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, 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	Input data file.	required
alpha	float	Compensation factor for triple-FID acquisition. Default 1.	1
load_text_options	dict[str, Any]	Additional keyword arguments for np.loadtxt(). Default {}.	dict()

Attributes:

Name	Type	Description
filename	str	See Parameters.
alpha	float	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.
compensated	ndarray	Compensated signal (S*, second FID), 1D array.
reference	ndarray	Reference signal (S₀, third FID), 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 0.
loop_counter_start	int	Starting value of loop counter.
loop_counter_increment	int	Increment of loop counter.
length_per_counter	float	Length per loop counter.
num_continuous	int	Number of points for continuous x-axis. Default 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.
loop_counters	ndarray	Loop counter values, 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.
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(x_initial_value=0, loop_counter_start=1, loop_counter_increment=1, length_per_counter=58.82, n_points=16)
>>> fid_triple.to_txt("output_difference.txt", key='difference')

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 of the real x-axis represented by each 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_triple.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(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.

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, 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	Input data file.	required
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	Rotor cycles for the first point. Default is None.	None
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	See Parameters.
load_text_options	dict	See Parameters.
verbose	bool	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.
data	ndarray	Raw data read from the file corresponding to the modulated signal (S'), 1D array.
reference	ndarray	Reference signal (S₀), 1D array.
difference	ndarray	Normalized DQ intensity (1 - S'/S₀), 1D array.
n_points	(int, optional)	Number of points in the experiment.
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.
dephasing_time	float	Dephasing 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
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.

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(xlim=None, ylim=None, figure_size=(4, 4), show_legend=False, **kwargs)

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

Parameters:

Name	Type	Description	Default
xlim	tuple[float, float] | None	Limits for x-axis	None
ylim	tuple[float, float] | None	Limits for y-axis	None
figure_size	tuple[float, float]	Size of the figure (width, height)	(4, 4)
show_legend	bool	Whether to show legend	False
**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)

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: ctdrenar)	ctdrenar

Returns:

Name	Type	Description
beff_opt	float	Effective dipolar coupling constant calculated from the optimized z-value, in kHz, if the dephasing time is provided.
z_opt	float	Optimized z-value from the fitting, in ms^2, if dephasing time is not provided.

plot_fit

plot_fit(xlim=None, ylim=None, figure_size=(4, 4), color='#0092c8', show_legend=False)

Plotting the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
xlim	tuple[float, float] | None	Limits for x-axis. Default is None.	None
ylim	tuple[float, float] | None	Limits for y-axis. Default is None.	None
figure_size	tuple[float, float]	Size of the figure (width, height). Default is (4, 4).	(4, 4)
color		Color for both experimental data and fitted curve. Default is '#0092c8'.	'#0092c8'
show_legend	bool	Whether to show legend. Default is False.	False

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, 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', '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, 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', '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, load_text_options=dict(), l0=None, l10=None, spin_rate=None, gamma_I=None, gamma_S=None, truncated_n_points=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	Input data file.	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
gamma_I	float | None	Gyromagnetic ratio of the observed nucleus in MHz/T. Default None.	None
gamma_S	float | None	Gyromagnetic ratio of the dephasing nucleus in MHz/T. 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
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	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 (2, n_points) array.
n_points	int	Number of data points in the experiment.
dephasing	ndarray	Dephasing signal (S'), 1D array.
reference	ndarray	Reference signal (S₀), 1D array.
difference	ndarray	Normalized difference (1 - S'/S₀), 1D array.
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.
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².
d_opt	float	Optimized d-value from fitting.
beff_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.
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.

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
>>> beff, r = exp.fit()
>>> fig, ax = exp.plot_fit(show_legend=True)

set_time_axis

set_time_axis(l0, l10, spin_rate, 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
self.time_discrete: np.ndarray	Discrete time values for plotting experimental/simulated data, in ms.
self.time_continuous: np.ndarray	Artificial time axis with (usually) more points used for trendlines, in ms.
self.loop_counters: np.ndarray	Loop counter array in case needed.

Examples:

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

plot_difference

plot_difference(xlim=None, ylim=None, figure_size=(4, 4), show_legend=False, **kwargs)

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

Parameters:

Name	Type	Description	Default
xlim	tuple[float, float] | None	Limits for x-axis. Default is None.	None
ylim	tuple[float, float] | None	Limits for y-axis. Default is None.	None
figure_size	tuple[float, float]	Size of the figure (width, height). Default is (4, 4).	(4, 4)
show_legend	bool	Whether to show legend. Default is False.	False
**kwargs	Any	Additional 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_difference()
>>> fig, ax = exp.plot_difference(xlim=(0, 10), ylim=(0, 0.3))

fit

fit(function=redor_bessel(5))

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:

Name	Type	Description
beff_opt	float	Effective dipolar coupling constant calculated from the optimized parameter, in kHz.
r_opt	float or None	Optimized distance from the fitting, in Å, if gamma_I and gamma_S are provided. Otherwise None.

Examples:

>>> beff, r = exp.fit()
>>> print(f'Effective coupling: {beff:.3f} kHz, Distance: {r:.3f} Å')

plot_fit

plot_fit(xlim=None, ylim=None, figure_size=(4, 4), color='#0092c8', show_legend=False)

Plot the fitted curve together with the experimental data.

Parameters:

Name	Type	Description	Default
xlim	tuple[float, float] | None	Limits for x-axis. Default is None.	None
ylim	tuple[float, float] | None	Limits for y-axis. Default is None.	None
figure_size	tuple[float, float]	Size of the figure (width, height). Default is (4, 4).	(4, 4)
color		Color for both experimental data and fitted curve. Default is '#0092c8'.	'#0092c8'
show_legend	bool	Whether to show legend. Default is False.	False

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

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 of the real x-axis represented by each 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_pair.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(modulated, reference)

Calculate the reference and difference array from the data.

Parameters:

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

Returns:

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

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', '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, 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', '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, alpha=1, load_text_options=dict(), l0=None, l10=None, spin_rate=None, gamma_I=None, gamma_S=None, truncated_n_points=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	Input data file.	required
alpha	float	Compensation factor defined in the pulse program. Default 1.	1
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
gamma_I	float | None	Gyromagnetic ratio of the observed nucleus in MHz/T. Default None.	None
gamma_S	float | None	Gyromagnetic ratio of the dephasing nucleus in MHz/T. 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
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	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.
dephasing	ndarray	Dephasing signal (S'), 1D array.
compensation	ndarray	Compensation signal (S*), 1D array.
reference	ndarray	Reference signal (S₀), 1D array.
difference	ndarray	Compensated difference (1 - S'/S₀ + α(1 - S*/S₀)), 1D array.
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.
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².
d_opt	float	Optimized d-value from fitting.
beff_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
>>> beff, r = exp.fit()
>>> fig, ax = exp.plot_fit(show_legend=True)

set_time_axis

set_time_axis(l0, l10, spin_rate, 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
self.time_discrete: np.ndarray	Discrete time values for plotting experimental/simulated data, in ms.
self.time_continuous: np.ndarray	Artificial time axis with (usually) more points used for trendlines, in ms.
self.loop_counters: np.ndarray	Loop counter array in case needed.

Examples:

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

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 of the real x-axis represented by each 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_triple.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(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.

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, load_text_options=dict(), l0=None, l10=None, spin_rate=None, 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	Input data file.	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
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	See Parameters.
l0	int	See Parameters.
l10	int	See Parameters.
spin_rate	float	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.
modulated	ndarray	Modulated DQ signal (first FID), 1D array.
reference	ndarray	Reference signal (second FID), 1D array.
difference	ndarray	Normalized DQ build-up (1 - S/S₀), 1D array.
num_continuous	int	Number of points for continuous x-axis. Default 100.
time_discrete	ndarray	Discrete time values corresponding to data points, in ms, 1D array. Only present if l0, l10, and spin_rate are provided.
time_continuous	ndarray	Continuous time values for plotting the fitted curve, in ms, 1D array. Only present if l0, l10, and spin_rate are provided.
loop_counters	ndarray	Loop counter values, 1D array. Only present if l0, l10, and spin_rate are provided.

Examples:

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

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 of the real x-axis represented by each 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_pair.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(modulated, reference)

Calculate the reference and difference array from the data.

Parameters:

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

Returns:

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

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', '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, 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', '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')