API#

x_epi sequence class module

class x_epi.seq.XSeq(*args: Any, **kwargs: Any)#

Sequence class for creating EPI sequences. Inherits from the Pypulseq sequence class.

Methods

`add_blck_lbl`(*args[, lbl])	Quick function to add events to block and add a label to list
`add_met`([name, size, pf_pe, pf_pe2, ...])	Add metabolite acquisition to sequence
`add_spec`([run_spec, spec_size, spec_bw, ...])	Add spectra acquisition to start and/or end of acquisition
`add_spec_events`()	Creates rf, adc, and slice gradient events for spectra
`create_param_dic`()	Create a dictionary for sequence parameters
`create_seq`([return_plot, no_reps])	Creates epi sequence
`create_ssrf_grad_ev`(met_idx)	Creates gradient event for SSRF pulse
`create_ssrf_rf_ev`(met_idx)	Creates RF event for SSRF pulse
`save_params`(out_path)	Saves input parameters that define sequence to json

__init__(fov=[240, 240, 240], rbw=50, n_avg=1, n_rep=1, tr=0, tv=0, ts=0, ro_off=0, pe_off=0, slc_off=0, slice_axis='Z', n_echo=1, delta_te=0, symm_ro=False, acq_3d=False, no_pe=False, grad_spoil=False, ramp_samp=False, no_slc=False, alt_read=False, alt_pha=False, alt_slc=False, ro_os=1.0, b0=3, nuc='13C', rf_dead_time=100, rf_ringdown_time=30, adc_dead_time=20, max_slew=200, max_grad=100, adc_raster_time=100, block_duration_raster=10, grad_raster_time=10, rf_raster_time=1, ori='Transverse', pe_dir='AP', **kwargs)#

Initialize X EPI sequence object, inherits from pypulseq Sequence object

Attributes:

fovarray_like: Contains FOV of each dimension (mm)
rbwfloat: Readout bandwidth (kHz)
n_avgint: Number of averages
n_repint: Number of repeats
trfloat: Minimum duration of each excitation block (ms)
tvfloat: Minimum duration of each 3D image (ms)
tsfloat: Minimum durartion of each metabolite set (ms)
ro_offfloat: Spatial offset in readout direction (mm)
pe_offfloat: Spatial offset in phase encoding direction (mm). Only for recon.
slc_off: float: Spatial offset in slice direction (mm)
slice_axisstr: Axis to play slic gradient on. Takes X, Y, Z
n_echoint: Number of echoes following each excitation
delta_tefloat: Minimum duration between each echo (ms) #Extract sequence options
symm_robool: Uses symmetric readout if True. Otherwise uses flyback.
acq_3dbool: Uses a 3D readout if True. Otherwise uses 2D.
no_pebool: Turns off phase encoding gradients is True.
grad_spoilbool: Turns on gradient spoilers if True
no_slcbool: Turns off slice gradients if True.
alt_readbool: Alternate polarity of readout every repetition
alt_phabool: Alternate polarity of phase encoding every repetition
alt_slcbool: Alternate polarity of second phase encoding every repetition
ro_osfloat: Readout oversampling factor
b0float: Main magnetic field strength (T)
nucstr: Nucleus to image
rf_dead_timefloat: Dead time for RF channel (us)
rf_ringdown_timefloat: Ringdown time for RF channel (us)
max_slewfloat: Maximum slew rate (T/m/s)
max_gradfloat: Maximum gradient strength (mT/m)
adc_raster_timefloat: Raster time for ADC (ns)
block_duration_rasterfloat: Raster time for Pulseq blocks (us)
grad_raster_timefloat: Raster time for gradients (us)
rf_raster_timefloat: Raster time for RF events (us)
oristr: Image orientation for reconstruction.
pe_dirstr: Phase encoding direction for reconstruction

Returns:

XSeq sequence object

add_blck_lbl(*args, lbl=None)#

Quick function to add events to block and add a label to list

Parameters:

argsSimpleNamespace: Block structure / items to be added to sequence
lblstr: Label to add to self.blck_lbls

add_met(name=None, size=(16, 16, 16), pf_pe=1, pf_pe2=1, sinc_frac=0.5, sinc_tbw=4, formula='1', use_sinc=False, grd_path='/home/docs/checkouts/readthedocs.org/user_builds/x-epi/checkouts/latest/x_epi/res/siemens_singleband_pyr_3T.GRD', rf_path='/home/docs/checkouts/readthedocs.org/user_builds/x-epi/checkouts/latest/x_epi/res/siemens_singleband_pyr_3T.RF', flip=90, freq_off=0, sinc_dur=4, z_centric=False, **kwargs)#

Add metabolite acquisition to sequence

Parameters:

namestr: Name for metabolite
sizearray_like: Grid size in x, y, and z
pf_pefloat: Partial Fourier fraction in y dimension
pf_pe2float: Partial Fourier fraction in z dimension
sinc_fracfloat: Center fraction of sinc pulse
sinc_tbwfloat: Time-bandwidth product of sinc pulse
grd_pathstr: Path to gradient file from Spectral-Spatial RF Toolbox
rf_pathstr: ‘Path to rf file from Spectral-Spatial RF Toolbox
formulastr: Formula for scaling SSRF gradient where x is slice thickness in mm
use_sincbool: Use a sinc pulse instead of an SSRF pulse
flipfloat: Flip angle (degrees)
freq_offfloat: Frequency offset (Hz) of pulse
sinc_durfloat: Duration of sinc pulse (ms)
z_centricbool: Use centric phase encoding in z direction

add_spec(run_spec='END', spec_size=2048, spec_bw=25, spec_flip=2.5, spec_tr=1000, n_spec=1, **kwargs)#

Add spectra acquisition to start and/or end of acquisition

Parameters:

run_specstr: When to run spectra. Takes START, END, or BOTH
spec_sizen: Number of spectra to acquire
spec_bwfloat: Spectral bandwidth (kHz)
spec_flipfloat: Flip angle for sinc pulse (degrees)
spec_trfloat: Minimum duration of each excitation block (ms)
n_specint: Number of spectra acquistions (seperated by at least spec_tr)

add_spec_events()#: Creates rf, adc, and slice gradient events for spectra

create_param_dic()#

Create a dictionary for sequence parameters

Returns:

param_dicdic: Dictionary of sequence parameters

create_seq(return_plot=False, no_reps=False)#

Creates epi sequence

Parameters:

return_plotbool: If True, returns a sequence object with no repetitions or averages. Useful for plotting sequence
no_repsbool: If True, turns off replications/averages

Returns:

plot_seqX EPI object: Sequence object with no repetitions or aveages

create_ssrf_grad_ev(met_idx)#

Creates gradient event for SSRF pulse

Parameters:

met_idxint: Index of metabolite in self.mets

create_ssrf_rf_ev(met_idx)#

Creates RF event for SSRF pulse

Parameters:

met_idxint: Index of metabolite in self.mets

save_params(out_path)#

Saves input parameters that define sequence to json

Parameters:

out_pathstr: Path to write json data to

Returns:

out_dicjson: Json file containing parameters

Utility functions for XSeq

x_epi.utils.compute_k_space(seq)#

Computes rf, gradient, and k-space waveforms of current sequence

Parameters:

seqXSeq object: Sequence object containing waveforms

Returns:

g_listlist: Gradient waveforms in X, Y, and Z dimensions for each metabolite
rf_listlist: Complex rf waveforms for each metabolite
k_listlist: 3D k-space waveforms for each metabolite. Returned if k_3d is True
adc_listlist: Timings for 3D k-space waveforms for each metabolite. Returned if k_3d is True
k_2d_listlist: 2D k-space waveforms for each metabolite. Returned if k_2d is True
adc_2d_listlist: Timings for 2D k-space waveforms for each metabolite. Returned if k_2d is True

x_epi.utils.interp_waveform(sig, delta_t, delta_ti, ti_end=None)#

Interpolates signal waveform

Parameters:

signdarray: Array containing waveform data
delta_tfloat: Sampling time for data in sig
delta_tifloat: Sampling time to interpolate to
ti_endfloat: Time to end interpolation at

Returns:

sig_indarray: Array containing interpolated data

x_epi.utils.knot_loc(x, n_k, bounds=None)#

Calculates location for knots based on sample quantiles

Parameters:

xarray: A array of length n containing the x-values
n_k: interger: Number of knots
bounds: array: A 2 x 1 array containing percentile bounds. If not set then function uses method described below.

Returns:

knotsarray: A set of knot locations

Notes

Uses the same basic algorithm as Hmisc package in R:: For 3 knots -> outer percentiles are 10 and 90% For 4-6 knots -> outer percentiels are 5% and 95% For >6 knots -> outer percentiles are 2.5% and 97.5% All other knots are linearly spaced between outer percentiles

x_epi.utils.load_ssrf_grad(grd_path)#

Load in SSRF gradient

Parameters:

grd_pathstr: Path to SSRF gradient file

Returns:

grd_datandarray: Numpy array containing gradient data
grd_maxfloat: Maximum gradient value (G/cm)
grd_deltafloat: Sampling time (s)

x_epi.utils.load_ssrf_rf(rf_path)#

Load in SSRF rf

Parameters:

rf_pathstr: Path to SSRF RF file

Returns:

rf_magndarray: Numpy array containing rf magnitude
rf_phandarray: Numpy array containing rf phase
b1_maxfloat: Maximum B1 (G)
rf_deltafloat: Sampling time (s)

x_epi.utils.nuc_to_gamma(nuc)#

Returns gyromagnetic ratio given nucleus

Parameters:

nucstr: Nucleus string (e.g., 13C, 1H, etc)

Returns:

gammafloat: Gyromangetic ratio in Hz/T

x_epi.utils.r_spline_basis(x, knots, norm=False)#

Calculates a restricted cubic spline basis for X given a set of knots

Parameters:

xarray: A array of length n containing the x-values for cubic spline basis
knots: array: An array of length p containing knot locations
norm: logical: If true normalizes spline (see rcspline.eval norm=2 in R)

Returns:

basismatrix: an n xp basis for a restricted cubic spine

x_epi.utils.save_k_space(seq, out)#

Parameters:

seqXSeq sequence object: Sequence object to compute k-space data
outstr: Root for output files

Returns:

k_spacelist of ndarrays: List containing k_space data for each metabolite