# MR Spectroscopy Analysis Tools

## Documentation for package ‘spant’ version 1.3.0

- DESCRIPTION file.
- User guides, package vignettes and other documentation.

## Help Pages

A B C D E F G H I L M N O P Q R S T V W Z

spant-package | spant: spectroscopy analysis tools.

## -- A --

abfit_opts | Return a list of options for an ABfit analysis.
acquire | Simulate pulse sequence acquisition.
align | Align spectra to a reference frequency using a convolution based method.
apodise_xy | Apodise MRSI data in the x-y direction with a k-space hamming filter.
append_basis | Combine a pair of basis set objects.
append_coils | Append MRS data across the coil dimension, assumes they matched across the other dimensions.
append_dyns | Append MRS data across the dynamic dimension, assumes they matched across the other dimensions.
apply_axes | Apply a function over specified array axes.
apply_mrs | Apply a function across given dimensions of a MRS data object.
apply_pvc | Convert default LCM/TARQUIN concentration scaling to molal units with partial volume correction.
Arg.mrs_data | Apply Arg operator to an MRS dataset.
auto_phase | Perform zeroth-order phase correction based on the minimisation of the squared difference between the real and magnitude components of the spectrum.

## -- B --

back_extrap | Back extrapolate time-domain points using the Burg autoregressive model
basis2mrs_data | Convert a basis object to an mrs_data object - where basis signals are spread across the dynamic dimension.
bbase | Generate a spline basis, slightly adapted from : "Splines, knots, and penalties", Eilers 2010.
bc_als | Baseline correction using the ALS method.
bc_constant | Remove a constant baseline offset based on a reference spectral region.
beta2lw | Covert a beta value in the time-domain to an equivalent linewidth in Hz: x * exp(-i * t * t * beta).

## -- C --

calc_coil_noise_cor | Calculate the noise correlation between coil elements.
calc_coil_noise_sd | Calculate the noise standard deviation for each coil element.
calc_ed_from_lambda | Calculate the effective dimensions of a spline smoother from lambda.
calc_peak_info_vec | Calculate the FWHM of a peak from a vector of intensity values.
calc_sd_poly | Perform a polynomial fit, subtract and return the standard deviation of the residuals.
calc_spec_diff | Calculate the sum of squares differences between two mrs_data objects.
calc_spec_snr | Calculate the spectral SNR.
check_lcm | Check LCModel can be run
check_tqn | Check the TARQUIN binary can be run
collapse_to_dyns | Collapse MRS data by concatenating spectra along the dynamic dimension.
collapse_to_dyns.fit_result | Collapse MRS data by concatenating spectra along the dynamic dimension.
collapse_to_dyns.mrs_data | Collapse MRS data by concatenating spectra along the dynamic dimension.
comb_coils | Combine coil data based on the first data point of a reference signal.
comb_coils_fp_pc | Combine coil data following phase correction based on the first data point in the FID.
comb_csv_results | Combine the results from multiple csv format files into a table.
comb_fits | Combine a list of fit_result objects into a single fit object containing a dynamic series.
comb_metab_ref | Combine a reference and metabolite mrs_data object.
Conj.mrs_data | Apply Conj operator to an MRS dataset.
conv_mrs | Convolve two MRS data objects.
crop_spec | Crop 'mrs_data' object based on a frequency range.
crop_td_pts | Crop 'mrs_data' object data points in the time-domain.
crop_xy | Crop an MRSI dataset in the x-y direction

## -- D --

decimate_mrs | Downsample an MRS signal by a factor.
def_acq_paras | Return (and optionally modify using the input arguments) a list of the default acquisition parameters.
def_fs | Return the default sampling frequency in Hz.
def_ft | Return the default transmitter frequency in Hz.
def_N | Return the default number of data points in the spectral dimension.
def_ref | Return the default reference value for ppm scale.
diff_mrs | Apply the diff operator to an MRS dataset in the FID/spectral dimension.

## -- E --

ecc | Eddy current correction.
est_noise_sd | Estimate the standard deviation of the noise from a segment of an mrs_data object.

## -- F --

fd2td | Transform frequency-domain data to the time-domain.
fd_conv_filt | Frequency-domain convolution based filter.
fit_amps | Extract the fit amplitudes from an object of class 'fit_result'.
fit_diags | Calculate diagnostic information for object of class 'fit_result'.
fit_mrs | Perform a fit based analysis of MRS data.
fit_res2csv | Write fit results table to a csv file.
fp_phase | Return the phase of the first data point in the time-domain.
fp_phase_correct | Perform a zeroth order phase correction based on the phase of the first data point in the time-domain.
fs | Return the sampling frequency in Hz of an MRS dataset.
ft_shift | Perform a fft and ffshift on a vector.
ft_shift_mat | Perform a fft and fftshift on a matrix with each column replaced by its shifted fft.

## -- G --

gen_F | Generate the F product operator.
gen_F_xy | Generate the Fxy product operator with a specified phase.
get_1h_brain_basis_paras | Return a list of 'mol_parameter' objects suitable for 1H brain MRS analyses.
get_1h_brain_basis_paras_v1 | Return a list of 'mol_parameter' objects suitable for 1H brain MRS analyses.
get_1h_brain_basis_paras_v2 | Return a list of 'mol_parameter' objects suitable for 1H brain MRS analyses.
get_2d_psf | Get the point spread function (PSF) for a 2D phase encoded MRSI scan.
get_acq_paras | Return acquisition parameters from a MRS data object.
get_dyns | Extract a subset of dynamic scans.
get_even_dyns | Return even numbered dynamic scans starting from 1 (2,4,6...).
get_fh_dyns | Return the first half of a dynamic series.
get_fit_map | Get a data array from a fit result.
get_fit_table | Combine all fitting data points into a single dataframe.
get_fp | Return the first time-domain data point.
get_guassian_pulse | Generate a gaussian pulse shape.
get_metab | Extract the metabolite component from an mrs_data object.
get_mol_names | Return a character array of names that may be used with the 'get_mol_paras' function.
get_mol_paras | Get a 'mol_parameters' object for a named molecule.
get_mrsi2d_seg | Calculate the partial volume estimates for each voxel in a 2D MRSI dataset.
get_mrsi_voi | Generate a MRSI VOI from an 'mrs_data' object.
get_mrsi_voxel | Generate a MRSI voxel from an 'mrs_data' object.
get_mrsi_voxel_xy_psf | Generate a MRSI voxel PSF from an 'mrs_data' object.
get_odd_dyns | Return odd numbered dynamic scans starting from 1 (1,3,5...).
get_ref | Extract the reference component from an mrs_data object.
get_seg_ind | Get the indices of data points lying between two values (end > x > start).
get_sh_dyns | Return the second half of a dynamic series.
get_slice | Return a single slice from a larger MRSI dataset.
get_subset | Extract a subset of MRS data.
get_svs_voi | Generate a SVS acquisition volume from an 'mrs_data' object.
get_td_amp | Return an array of amplitudes derived from fitting the initial points in the time domain and extrapolating back to t=0.
get_uncoupled_mol | Generate a 'mol_parameters' object for a simple spin system with one resonance.
get_voi_cog | Calculate the centre of gravity for an image containing 0 and 1's.
get_voi_seg | Return the white matter, gray matter and CSF composition of a volume.
get_voi_seg_psf | Return the white matter, gray matter and CSF composition of a volume.
get_voxel | Return a single voxel from a larger mrs dataset.
grid_shift_xy | Grid shift MRSI data in the x/y dimension.

## -- H --

hsvd_filt | HSVD based signal filter.
hz | Return the frequency scale of an MRS dataset in Hz.

## -- I --

ift_shift | Perform an iffshift and ifft on a vector.
ift_shift_mat | Perform an ifft and ifftshift on a matrix with each column replaced by its shifted ifft.
Im.mrs_data | Apply Im operator to an MRS dataset.
image.mrs_data | Image plot method for objects of class mrs_data.
interleave_dyns | Interleave the first and second half of a dynamic series.
int_spec | Integrate a spectral region.
inv_even_dyns | Invert even numbered dynamic scans starting from 1 (2,4,6...).
inv_odd_dyns | Invert odd numbered dynamic scans starting from 1 (1,3,5...).
is_fd | Check if the chemical shift dimension of an MRS data object is in the frequency domain.

## -- L --

l2_reg | Perform l2 regularisation artefact suppression using the method proposed by Bilgic et al. JMRI 40(1):181-91 2014.
lb | Apply line-broadening (apodisation) to MRS data or basis object.
lb.basis_set | Apply line-broadening (apodisation) to MRS data or basis object.
lb.mrs_data | Apply line-broadening (apodisation) to MRS data or basis object.
lw2alpha | Covert a linewidth in Hz to an equivalent alpha value in the time-domain ie: x * exp(-t * alpha).
lw2beta | Covert a linewidth in Hz to an equivalent beta value in the time-domain ie: x * exp(-t * t * beta).

## -- M --

mask_xy | Mask an MRSI dataset in the x-y direction
mask_xy_mat | Mask a 2D MRSI dataset in the x-y dimension.
mat2mrs_data | Convert a matrix (with spectral points in the row dimension and dynamics in the column dimensions) into a mrs_data object.
max_mrs | Apply the max operator to an MRS dataset.
max_mrs_interp | Apply the max operator to an interpolated MRS dataset.
mean.mrs_data | Calculate the mean spectrum from an mrs_data object.
mean_dyns | Calculate the mean dynamic data.
mean_dyn_blocks | Calculate the mean of adjacent dynamic scans.
mean_dyn_pairs | Calculate the pairwise means across a dynamic data set.
median_dyns | Calculate the median dynamic data.
Mod.mrs_data | Apply Mod operator to an MRS dataset.
mrsi2d_img2kspace | Transform 2D MRSI data to k-space in the x-y direction.
mrsi2d_kspace2img | Transform 2D MRSI data from k-space to image space in the x-y direction.
mrs_data2basis | Convert an mrs_data object to basis object - where basis signals are spread across the dynamic dimension in the MRS data.
mrs_data2mat | Convert mrs_data object to a matrix, with spectral points in the column dimension and dynamics in the row dimension.
mrs_data2vec | Convert mrs_data object to a vector.
mvfftshift | Perform a fftshift on a matrix, with each column replaced by its shifted result.
mvifftshift | Perform an ifftshift on a matrix, with each column replaced by its shifted result.

## -- N --

n2coord | Print fit coordinates from a single index.
Ncoils | Return the total number of coil elements in an MRS dataset.
Ndyns | Return the total number of dynamic scans in an MRS dataset.
nifti_flip_lr | Flip the x data dimension order of a nifti image. This corresponds to flipping MRI data in the left-right direction, assuming the data in save in neurological format (can check with fslorient program).
norm_mrs | Normalise mrs_data to a spectral region.
Npts | Return the number of data points in an MRS dataset.
Nspec | Return the total number of spectra in an MRS dataset.
Nx | Return the total number of x locations in an MRS dataset.
Ny | Return the total number of y locations in an MRS dataset.
Nz | Return the total number of z locations in an MRS dataset.

## -- O --

ortho3 | Display an orthographic projection plot of a nifti object.
ortho3_int | Display an interactive orthographic projection plot of a nifti object.

## -- P --

peak_info | Search for the highest peak in a spectral region and return the frequency, height and FWHM.
phase | Apply phasing parameters to MRS data.
plot.fit_result | Plot the fitting results of an object of class 'fit_result'.
plot.mrs_data | Plotting method for objects of class mrs_data.
plot_bc | Convenience function to plot a baseline estimate with the original data.
plot_slice_fit | Plot a 2D slice from an MRSI fit result object.
plot_slice_fit_inter | Plot a 2D slice from an MRSI fit result object.
plot_slice_map | Plot a slice from a 7 dimensional array.
plot_slice_map_inter | Plot an interactive slice map from a data array where voxels can be selected to display a corresponding spectrum.
plot_voi_overlay | Plot a volume as an image overlay.
plot_voi_overlay_seg | Plot a volume as an overlay on a segmented brain volume.
ppm | Return the ppm scale of an MRS dataset or fit result.
ppm.fit_result | Return the ppm scale of an MRS dataset or fit result.
ppm.mrs_data | Return the ppm scale of an MRS dataset or fit result.
print.fit_result | Print a summary of an object of class 'fit_result'.
print.mrs_data | Print a summary of mrs_data parameters.

## -- Q --

qn_states | Get the quantum coherence matrix for a spin system.

## -- R --

rats | Robust Alignment to a Target Spectrum (RATS).
Re.mrs_data | Apply Re operator to an MRS dataset.
read_basis | Read a basis file in LCModel .basis format.
read_ima_coil_dir | Read a directory containing Siemens MRS IMA files and combine along the coil dimension. Note that the coil ID is inferred from the sorted file name and should be checked when consistency is required between two directories.
read_ima_dyn_dir | Read a directory containing Siemens MRS IMA files and combine along the dynamic dimension. Note that the coil ID is inferred from the sorted file name and should be checked when consistency is required.
read_lcm_coord | Read an LCModel formatted coord file containing fit information.
read_mrs | Read MRS data from a file.
read_mrs_dpt | Read MRS data stored in dangerplot (dpt) v3 format.
read_mrs_tqn | Read MRS data using the TARQUIN software package.
read_siemens_txt_hdr | Read the text format header found in Siemens IMA and TWIW data files.
read_tqn_fit | Reader for csv fit results generated by TARQUIN.
read_tqn_result | Reader for csv results generated by TARQUIN.
rep_array_dim | Repeat an array over a given dimension.
rep_dyn | Replicate a scan in the dynamic dimension.
rep_mrs | Replicate a scan over a given dimension.
resample_img | Resample an image to match a target image space.
resample_voi | Resample a VOI to match a target image space using nearest-neighbour interpolation.
reslice_to_mrs | Reslice a nifti object to match the orientation of mrs data.
re_weighting | Apply a weighting to the FID to enhance spectral resolution.
rm_dyns | Remove a subset of dynamic scans.

## -- S --

scale_amp_molal_pvc | Apply partial volume correction to a fitting result object.
scale_amp_molar | Apply water reference scaling to a fitting results object to yield metabolite quantities in millimolar (mM) units (mol/litre).
scale_amp_ratio | Scale fitted amplitudes to a ratio of signal amplitude.
scale_amp_water_ratio | Scale metabolite amplitudes as a ratio to the unsuppressed water amplitude.
sd | Standard Deviation
sd.mrs_data | Calculate the standard deviation spectrum from an mrs_data object.
seconds | Return a time scale vector to match the FID of an MRS data object.
seq_cpmg_ideal | CPMG style sequence with ideal pulses.
seq_mega_press_ideal | MEGA-PRESS sequence with ideal localisation pulses and Gaussian shaped editing pulse.
seq_press_ideal | PRESS sequence with ideal pulses.
seq_pulse_acquire | Simple pulse and acquire sequence with ideal pulses.
seq_pulse_acquire_31p | Simple pulse and acquire sequence with ideal pulses.
seq_slaser_ideal | sLASER sequence with ideal pulses.
seq_spin_echo_ideal | Spin echo sequence with ideal pulses.
seq_spin_echo_ideal_31p | Spin echo sequence with ideal pulses.
seq_steam_ideal | STEAM sequence with ideal pulses.
set_def_acq_paras | Set the default acquisition parameters.
set_lcm_cmd | Set the command to run the LCModel command-line program.
set_lw | Apply line-broadening to an mrs_data object to achieve a specified linewidth.
set_ref | Set the ppm reference value (eg ppm value at 0Hz).
set_td_pts | Set the number of time-domain data points, truncating or zero-filling as appropriate.
set_tqn_cmd | Set the command to run the TARQUIN command-line program.
shift | Apply a frequency shift to MRS data.
sim_basis | Simulate a basis set object.
sim_basis_1h_brain | Simulate a basis-set suitable for 1H brain MRS analysis acquired with a PRESS sequence. Note, ideal pulses are assumed.
sim_basis_1h_brain_press | Simulate a basis-set suitable for 1H brain MRS analysis acquired with a PRESS sequence. Note, ideal pulses are assumed.
sim_basis_tqn | Simulate a basis file using TARQUIN.
sim_brain_1h | Simulate MRS data with a similar appearance to normal brain (by default).
sim_mol | Simulate a 'mol_parameter' object.
sim_noise | Simulate a time-domain mrs_data object containing simulated Gaussian noise.
sim_resonances | Simulate a MRS data object containing a set of simulated resonances.
spant | spant: spectroscopy analysis tools.
spant_mpress_drift | Example MEGA-PRESS data with significant B0 drift.
spin_sys | Create a spin system object for pulse sequence simulation.
spm_pve2categorical | Convert SPM style segmentation files to a single categorical image where the numerical values map as: 0) Other, 1) CSF, 2) GM and 3) WM.
stackplot | Produce a plot with multiple traces.
stackplot.fit_result | Plot the fitting results of an object of class 'fit_result' with individual basis set components shown.
stackplot.mrs_data | Stackplot plotting method for objects of class mrs_data.
sum_coils | Calculate the sum across receiver coil elements.
sum_dyns | Calculate the sum of data dynamics.

## -- T --

td2fd | Transform time-domain data to the frequency-domain.
tdsr | Time-domain spectral registration.
td_conv_filt | Time-domain convolution based filter.

## -- V --

varpro_3_para_opts | Return a list of options for VARPRO based fitting with 3 free parameters: • zero'th order phase correction • global damping • global frequency shift.
varpro_opts | Return a list of options for VARPRO based fitting.
vec2mrs_data | Convert a vector into a mrs_data object.

## -- W --

write_basis | Write a basis object to an LCModel .basis formatted file.
write_basis_tqn | Generate a basis file using TARQUIN.
write_mrs_dpt_v2 | Write MRS data object to file in dangerplot (dpt) v2 format.
write_mrs_lcm_raw | Write MRS data object to file in a RAW format compatible with LCModel.

## -- Z --

zero_nzoc | Zero all non-zero-order coherences.
zf | Zero-fill MRS data in the time domain.
zf.basis_set | Zero-fill MRS data in the time domain.
zf.mrs_data | Zero-fill MRS data in the time domain.
zf_xy | Zero-fill MRSI data in the k-space x-y direction.