Package 'spant'

Title: MR Spectroscopy Analysis Tools
Description: Tools for reading, visualising and processing Magnetic Resonance Spectroscopy data. The package includes methods for spectral fitting: Wilson (2021) <DOI:10.1002/mrm.28385> and spectral alignment: Wilson (2018) <DOI:10.1002/mrm.27605>.
Authors: Martin Wilson [cre, aut] , Yong Wang [ctb], John Muschelli [ctb]
Maintainer: Martin Wilson <[email protected]>
License: GPL-3
Version: 3.2.0
Built: 2025-02-14 16:25:25 UTC
Source: https://github.com/martin3141/spant

Help Index


spant: spectroscopy analysis tools.

Description

spant provides a set of tools for reading, visualising and processing Magnetic Resonance Spectroscopy (MRS) data.

Details

To get started with spant, take a look at the introduction vignette:

vignette("spant-intro", package="spant")

Full list of vignettes:

browseVignettes(package = "spant")

Full list of functions:

help(package = spant, help_type = "html")

An online version of the documentation is available from:

https://martin3141.github.io/spant/

Author(s)

Maintainer: Martin Wilson [email protected] (ORCID)

Other contributors:

  • Yong Wang [contributor]

  • John Muschelli [contributor]

See Also

Useful links:


Return a list of options for an ABfit analysis.

Description

Return a list of options for an ABfit analysis.

Usage

abfit_opts(
  init_damping = 5,
  maxiters = 1024,
  max_shift_pre = 0.078,
  max_shift_fine = NULL,
  max_damping = 15,
  max_phase = 360,
  lambda = NULL,
  ppm_left = 4,
  ppm_right = 0.2,
  zp = TRUE,
  bl_ed_pppm = 2,
  auto_bl_flex = TRUE,
  bl_comps_pppm = 15,
  adaptive_bl_comps_pppm = FALSE,
  export_sp_fit = FALSE,
  max_asym = 0.25,
  max_basis_shift = 0.0078,
  max_basis_damping = 2,
  maxiters_pre = 1000,
  algo_pre = "NLOPT_LN_NELDERMEAD",
  min_bl_ed_pppm = NULL,
  max_bl_ed_pppm = 7,
  auto_bl_flex_n = 20,
  pre_fit_bl_ed_pppm = 1,
  remove_lip_mm_prefit = FALSE,
  pre_align = TRUE,
  max_pre_align_shift = 0.1,
  pre_align_ref_freqs = c(2.01, 3.03, 3.22),
  noise_region = c(-0.5, -2.5),
  optimal_smooth_criterion = "maic",
  aic_smoothing_factor = 5,
  anal_jac = TRUE,
  pre_fit_ppm_left = 4,
  pre_fit_ppm_right = 1.8,
  phi1_optim = FALSE,
  phi1_init = 0,
  max_dphi1 = 0.2,
  max_basis_shift_broad = NULL,
  max_basis_damping_broad = NULL,
  ahat_calc_method = "lh_pnnls",
  prefit_phase_search = TRUE,
  freq_reg = NULL,
  freq_reg_naa = NULL,
  lb_reg = NULL,
  asym_reg = NULL,
  output_all_paras = FALSE,
  output_all_paras_raw = FALSE,
  input_paras_raw = NULL,
  optim_lw_only = FALSE,
  optim_lw_only_limit = 20,
  lb_init = 0.001,
  lb_init_approx_fit = FALSE,
  zf_offset = NULL
)

Arguments

init_damping

initial value of the Gaussian global damping parameter (Hz). Very poorly shimmed or high field data may benefit from a larger value.

maxiters

The maximum number of iterations to run for the detailed fit.

max_shift_pre

The maximum allowable global shift to be applied in the approximate (pre-fit) phases of analysis (ppm).

max_shift_fine

The maximum allowable global shift to be applied in the detailed fit phase of analysis (ppm).

max_damping

maximum permitted value of the global damping parameter (Hz).

max_phase

the maximum absolute permitted value of the global zero-order phase term (degrees). Note, the prefit_phase_search option is not constrained by this term.

lambda

manually set the the baseline smoothness parameter.

ppm_left

downfield frequency limit for the fitting range (ppm).

ppm_right

upfield frequency limit for the fitting range (ppm).

zp

zero pad the data to twice the original length before fitting.

bl_ed_pppm

manually set the the baseline smoothness parameter (ED per ppm).

auto_bl_flex

automatically determine the level of baseline smoothness.

bl_comps_pppm

spline basis density (signals per ppm).

adaptive_bl_comps_pppm

adjust the spline basis density in the detailed fit phase, based on the required level of smoothness, to reduce computation time.

export_sp_fit

add the fitted spline functions to the fit result.

max_asym

maximum allowable value of the asymmetry parameter.

max_basis_shift

maximum allowable frequency shift for individual basis signals (ppm).

max_basis_damping

maximum allowable Lorentzian damping factor for individual basis signals (Hz).

maxiters_pre

maximum iterations for the coarse (pre-)fit.

algo_pre

optimisation method for the coarse (pre-)fit.

min_bl_ed_pppm

minimum value for the candidate baseline flexibility analyses (ED per ppm).

max_bl_ed_pppm

minimum value for the candidate baseline flexibility analyses (ED per ppm).

auto_bl_flex_n

number of candidate baseline analyses to perform.

pre_fit_bl_ed_pppm

level of baseline flexibility to use in the coarse fitting stage of the algorithm (ED per ppm).

remove_lip_mm_prefit

remove broad signals in the coarse fitting stage of the algorithm.

pre_align

perform a pre-alignment step before coarse fitting.

max_pre_align_shift

maximum allowable shift in the pre-alignment step (ppm).

pre_align_ref_freqs

a vector of prominent spectral frequencies used in the pre-alignment step (ppm).

noise_region

spectral region to estimate the noise level (ppm).

optimal_smooth_criterion

method to determine the optimal smoothness.

aic_smoothing_factor

modification factor for the AIC calculation. Larger values result in less flexible baselines.

anal_jac

use a analytical approximation to the jacobian in the detailed fitting stage.

pre_fit_ppm_left

downfield frequency limit for the fitting range in the coarse fitting stage of the algorithm (ppm).

pre_fit_ppm_right

upfield frequency limit for the fitting range in the coarse fitting stage of the algorithm (ppm).

phi1_optim

apply and optimise a frequency dependant phase term.

phi1_init

initial value for the frequency dependant phase term (ms).

max_dphi1

maximum allowable change from the initial frequency dependant phase term (ms).

max_basis_shift_broad

maximum allowable shift for broad signals in the basis (ppm). Determined based on their name beginning with Lip or MM. The default value is set to max_basis_shift.

max_basis_damping_broad

maximum allowable Lorentzian damping for broad signals in the basis (Hz). Determined based on their name beginning with Lip or MM. The default value is set to max_basis_damping.

ahat_calc_method

method to calculate the metabolite amplitudes. May be one of: "lh_pnnls" or "ls".

prefit_phase_search

perform a 1D search for the optimal phase in the prefit stage of the algorithm.

freq_reg

frequency shift parameter.

freq_reg_naa

frequency shift parameter for NAA and NAAG.

lb_reg

individual line broadening parameter.

asym_reg

lineshape asymmetry parameter.

output_all_paras

include more fitting parameters in the fit table, e.g. individual shift and damping factors for each basis set element.

output_all_paras_raw

include raw fitting parameters in the fit table. For advanced diagnostic use only.

input_paras_raw

input raw fitting parameters. For advanced diagnostic use only.

optim_lw_only

optimize the global line-broadening term only.

optim_lw_only_limit

limits for the line-breading term as a percentage of the starting value when optim_lw_only is TRUE.

lb_init

initial Lorentzian line broadening value (in Hz) for the individual basis signals. Setting to 0 will clash with the minimum allowable value (eg hard constraint) during the detailed fit.

lb_init_approx_fit

apply lb_init to the basis during the approximate iterative fit.

zf_offset

offset in number of data points from the end of the FID to zero-fill. Default is NULL and will automatically set this to 50 points when the FID distortion flag is set for the mrs_data.

Value

full list of options.

Examples

opts <- abfit_opts(ppm_left = 4.2, noise_region = c(-1, -3))

Return a list of options for an ABfit analysis to maintain comparability with analyses performed with version 1.9.0 (and earlier) of spant.

Description

Return a list of options for an ABfit analysis to maintain comparability with analyses performed with version 1.9.0 (and earlier) of spant.

Usage

abfit_opts_v1_9_0(...)

Arguments

...

arguments passed to abfit_opts.

Value

full list of options.


Return a list of options for an ABfit analysis with regularision.

Description

Return a list of options for an ABfit analysis with regularision.

Usage

abfit_reg_opts(
  init_damping = 5,
  maxiters = 128,
  max_shift_pre = 0.078,
  max_shift_fine = 0.05,
  max_damping = 15,
  max_phase = 360,
  lambda = NULL,
  ppm_left = 4,
  ppm_right = 0.2,
  zp = TRUE,
  bl_ed_pppm = 2,
  auto_bl_flex = TRUE,
  bl_comps_pppm = 15,
  adaptive_bl_comps_pppm = TRUE,
  export_sp_fit = FALSE,
  max_asym = Inf,
  max_basis_shift = Inf,
  max_basis_damping = Inf,
  maxiters_pre = 1000,
  algo_pre = "NLOPT_LN_NELDERMEAD",
  min_bl_ed_pppm = NULL,
  max_bl_ed_pppm = 7,
  auto_bl_flex_n = 20,
  pre_fit_bl_ed_pppm = 1,
  remove_lip_mm_prefit = FALSE,
  pre_align = TRUE,
  max_pre_align_shift = 0.1,
  pre_align_ref_freqs = c(2.01, 3.03, 3.22),
  noise_region = c(-0.5, -2.5),
  optimal_smooth_criterion = "maic",
  aic_smoothing_factor = 5,
  anal_jac = TRUE,
  pre_fit_ppm_left = 4,
  pre_fit_ppm_right = 1.8,
  phi1_optim = FALSE,
  phi1_init = 0,
  max_dphi1 = 0.2,
  max_basis_shift_broad = NULL,
  max_basis_damping_broad = NULL,
  ahat_calc_method = "lh_pnnls",
  prefit_phase_search = TRUE,
  freq_reg = 0.004,
  freq_reg_naa = NULL,
  lb_reg = "lcm_compat",
  asym_reg = 0.1,
  output_all_paras = FALSE,
  output_all_paras_raw = FALSE,
  input_paras_raw = NULL,
  optim_lw_only = FALSE,
  optim_lw_only_limit = 20,
  lb_init = "lcm_compat",
  lb_init_approx_fit = FALSE,
  zf_offset = NULL
)

Arguments

init_damping

initial value of the Gaussian global damping parameter (Hz). Very poorly shimmed or high field data may benefit from a larger value.

maxiters

The maximum number of iterations to run for the detailed fit.

max_shift_pre

The maximum allowable global shift to be applied in the approximate (pre-fit) phases of analysis (ppm).

max_shift_fine

The maximum allowable global shift to be applied in the detailed fit phase of analysis (ppm).

max_damping

maximum permitted value of the global damping parameter (Hz).

max_phase

the maximum absolute permitted value of the global zero-order phase term (degrees). Note, the prefit_phase_search option is not constrained by this term.

lambda

manually set the the baseline smoothness parameter.

ppm_left

downfield frequency limit for the fitting range (ppm).

ppm_right

upfield frequency limit for the fitting range (ppm).

zp

zero pad the data to twice the original length before fitting.

bl_ed_pppm

manually set the the baseline smoothness parameter (ED per ppm).

auto_bl_flex

automatically determine the level of baseline smoothness.

bl_comps_pppm

spline basis density (signals per ppm).

adaptive_bl_comps_pppm

adjust the spline basis density in the detailed fit phase, based on the required level of smoothness, to reduce computation time.

export_sp_fit

add the fitted spline functions to the fit result.

max_asym

maximum allowable value of the asymmetry parameter.

max_basis_shift

maximum allowable frequency shift for individual basis signals (ppm).

max_basis_damping

maximum allowable Lorentzian damping factor for individual basis signals (Hz).

maxiters_pre

maximum iterations for the coarse (pre-)fit.

algo_pre

optimisation method for the coarse (pre-)fit.

min_bl_ed_pppm

minimum value for the candidate baseline flexibility analyses (ED per ppm).

max_bl_ed_pppm

minimum value for the candidate baseline flexibility analyses (ED per ppm).

auto_bl_flex_n

number of candidate baseline analyses to perform.

pre_fit_bl_ed_pppm

level of baseline flexibility to use in the coarse fitting stage of the algorithm (ED per ppm).

remove_lip_mm_prefit

remove broad signals in the coarse fitting stage of the algorithm.

pre_align

perform a pre-alignment step before coarse fitting.

max_pre_align_shift

maximum allowable shift in the pre-alignment step (ppm).

pre_align_ref_freqs

a vector of prominent spectral frequencies used in the pre-alignment step (ppm).

noise_region

spectral region to estimate the noise level (ppm).

optimal_smooth_criterion

method to determine the optimal smoothness.

aic_smoothing_factor

modification factor for the AIC calculation. Larger values result in less flexible baselines.

anal_jac

use a analytical approximation to the jacobian in the detailed fitting stage.

pre_fit_ppm_left

downfield frequency limit for the fitting range in the coarse fitting stage of the algorithm (ppm).

pre_fit_ppm_right

upfield frequency limit for the fitting range in the coarse fitting stage of the algorithm (ppm).

phi1_optim

apply and optimise a frequency dependant phase term.

phi1_init

initial value for the frequency dependant phase term (ms).

max_dphi1

maximum allowable change from the initial frequency dependant phase term (ms).

max_basis_shift_broad

maximum allowable shift for broad signals in the basis (ppm). Determined based on their name beginning with Lip or MM. The default value is set to max_basis_shift.

max_basis_damping_broad

maximum allowable Lorentzian damping for broad signals in the basis (Hz). Determined based on their name beginning with Lip or MM. The default value is set to max_basis_damping.

ahat_calc_method

method to calculate the metabolite amplitudes. May be one of: "lh_pnnls" or "ls".

prefit_phase_search

perform a 1D search for the optimal phase in the prefit stage of the algorithm.

freq_reg

frequency shift parameter.

freq_reg_naa

frequency shift parameter for NAA and NAAG.

lb_reg

individual line broadening parameter.

asym_reg

lineshape asymmetry parameter.

output_all_paras

include more fitting parameters in the fit table, e.g. individual shift and damping factors for each basis set element.

output_all_paras_raw

include raw fitting parameters in the fit table. For advanced diagnostic use only.

input_paras_raw

input raw fitting parameters. For advanced diagnostic use only.

optim_lw_only

optimize the global line-broadening term only.

optim_lw_only_limit

limits for the line-breading term as a percentage of the starting value when optim_lw_only is TRUE.

lb_init

initial Lorentzian line broadening value (in Hz) for the individual basis signals. Setting to 0 will clash with the minimum allowable value (eg hard constraint) during the detailed fit.

lb_init_approx_fit

apply lb_init to the basis during the approximate iterative fit.

zf_offset

offset in number of data points from the end of the FID to zero-fill. Default is NULL and will automatically set this to 50 points when the FID distortion flag is set for the mrs_data.

Value

full list of options.

Examples

opts <- abfit_reg_opts(ppm_left = 4.2, noise_region = c(-1, -3))

Simulate pulse sequence acquisition.

Description

Simulate pulse sequence acquisition.

Usage

acquire(sys, rec_phase = 0, tol = 1e-04, detect = NULL, amp_scale = 1)

Arguments

sys

spin system object.

rec_phase

receiver phase in degrees.

tol

ignore resonance amplitudes below this threshold.

detect

detection nuclei.

amp_scale

scaling factor for the output amplitudes.

Value

a list of resonance amplitudes and frequencies.


Add noise to an mrs_data object.

Description

Add noise to an mrs_data object.

Usage

add_noise(mrs_data, sd = 0.1, fd = TRUE)

Arguments

mrs_data

data to add noise to.

sd

standard deviation of the noise.

fd

generate the noise samples in the frequency-domain (TRUE) or time-domain (FALSE). This is required since the absolute value of the standard deviation of noise samples changes when data is Fourier transformed.

Value

mrs_data object with additive normally distributed noise.


Add noise to an mrs_data object to match a given SNR.

Description

Add noise to an mrs_data object to match a given SNR.

Usage

add_noise_spec_snr(
  mrs_data,
  target_snr,
  sig_region = c(4, 0.5),
  ref_data = NULL
)

Arguments

mrs_data

data to add noise to.

target_snr

desired spectral SNR, note this assumes the input data is noise-free, eg simulated data. Note the SNR is estimated from the first scan in the dataset and the same noise level is added to all spectra.

sig_region

spectral limits to search for the strongest spectral data point.

ref_data

measure the signal from the first scan in this reference data and apply the same target noise level to mrs_data.

Value

mrs_data object with additive normally distributed noise.


Align spectra to a reference frequency using a convolution based method.

Description

Align spectra to a reference frequency using a convolution based method.

Usage

align(
  mrs_data,
  ref_freq = 4.65,
  ref_amp = 1,
  zf_factor = 2,
  lb = 2,
  max_shift = 20,
  ret_df = FALSE,
  mean_dyns = FALSE
)

Arguments

mrs_data

data to be aligned.

ref_freq

reference frequency in ppm units. More than one frequency may be specified.

ref_amp

amplitude value for the reference signal. More than one value may be specified to match the number of ref_freq signals.

zf_factor

zero filling factor to increase alignment resolution.

lb

line broadening to apply to the reference signal.

max_shift

maximum allowable shift in Hz.

ret_df

return frequency shifts in addition to aligned data (logical).

mean_dyns

align the mean spectrum and apply the same shift to each dynamic.

Value

aligned data object.


Apodise MRSI data in the x-y direction with a k-space filter.

Description

Apodise MRSI data in the x-y direction with a k-space filter.

Usage

apodise_xy(mrs_data, func = "hamming", w = 2.5)

Arguments

mrs_data

MRSI data.

func

must be "hamming", "hanning" or "gaussian".

w

the reciprocal of the standard deviation for the Gaussian function.

Value

apodised data.


Combine a pair of basis set objects.

Description

Combine a pair of basis set objects.

Usage

append_basis(basis_a, basis_b)

Arguments

basis_a

first basis.

basis_b

second basis.

Value

combined basis set object.


Append MRS data across the coil dimension, assumes they matched across the other dimensions.

Description

Append MRS data across the coil dimension, assumes they matched across the other dimensions.

Usage

append_coils(...)

Arguments

...

MRS data objects as arguments, or a list of MRS data objects.

Value

a single MRS data object with the input objects concatenated together.


Append MRS data across the dynamic dimension, assumes they matched across the other dimensions.

Description

Append MRS data across the dynamic dimension, assumes they matched across the other dimensions.

Usage

append_dyns(...)

Arguments

...

MRS data objects as arguments, or a list of MRS data objects.

Value

a single MRS data object with the input objects concatenated together.


Append multiple regressor data frames into a single data frame.

Description

Append multiple regressor data frames into a single data frame.

Usage

append_regs(...)

Arguments

...

input regressor data frames.

Value

output regressor data frame.


Apply a function over specified array axes.

Description

Apply a function over specified array axes.

Usage

apply_axes(x, axes, fun, ...)

Arguments

x

an array.

axes

a vector of axes to apply fun over.

fun

function to be applied.

...

optional arguments to fun.

Value

array.

Examples

z <- array(1:1000, dim = c(10, 10, 10))
a <- apply_axes(z, 3, fft)
a[1,1,] == fft(z[1,1,])
a <- apply_axes(z, 3, sum)
a[1,1,] == sum(z[1,1,])

Apply a function across given dimensions of a MRS data object.

Description

Apply a function across given dimensions of a MRS data object.

Usage

apply_mrs(mrs_data, dims, fun, ..., data_only = FALSE)

Arguments

mrs_data

MRS data.

dims

dimensions to apply the function.

fun

name of the function.

...

arguments to the function.

data_only

return an array rather than an MRS data object.


Simulate an RF pulse on a single spin.

Description

Simulate an RF pulse on a single spin.

Usage

apply_pulse(sys, rho, spin_n, angle, nuc, xy)

Arguments

sys

spin system object.

rho

density matrix.

spin_n

spin index.

angle

RF flip angle in degrees.

nuc

nucleus influenced by the pulse.

xy

x or y pulse.

Value

density matrix.


Apply Arg operator to an MRS dataset.

Description

Apply Arg operator to an MRS dataset.

Usage

## S3 method for class 'mrs_data'
Arg(z)

Arguments

z

MRS data.

Value

MRS data following Arg operator.


Convert a 7 dimensional array in into a mrs_data object. The array dimensions should be ordered as : dummy, X, Y, Z, dynamic, coil, FID.

Description

Convert a 7 dimensional array in into a mrs_data object. The array dimensions should be ordered as : dummy, X, Y, Z, dynamic, coil, FID.

Usage

array2mrs_data(
  data_array,
  mrs_data = NULL,
  fs = NULL,
  ft = NULL,
  ref = NULL,
  nuc = NULL,
  fd = FALSE
)

Arguments

data_array

7d data array.

mrs_data

example data to copy acquisition parameters from.

fs

sampling frequency in Hz.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

nuc

nucleus that is resonant at the transmitter frequency.

fd

flag to indicate if the matrix is in the frequency domain (logical).

Value

mrs_data object.


Perform zeroth-order phase correction based on the minimisation of the squared difference between the real and magnitude components of the spectrum.

Description

Perform zeroth-order phase correction based on the minimisation of the squared difference between the real and magnitude components of the spectrum.

Usage

auto_phase(mrs_data, xlim = c(4, 1.8), smo_ppm_sd = 0.05, ret_phase = FALSE)

Arguments

mrs_data

an object of class mrs_data.

xlim

frequency range (default units of PPM) to including in the phase.

smo_ppm_sd

Gaussian smoother sd in ppm units.

ret_phase

return phase values (logical).

Value

MRS data object and phase values (optional).


Back extrapolate time-domain data points using an autoregressive model.

Description

Back extrapolate time-domain data points using an autoregressive model.

Usage

back_extrap_ar(
  mrs_data,
  extrap_pts,
  pred_pts = NULL,
  method = "burg",
  rem_add = TRUE,
  ...
)

Arguments

mrs_data

mrs_data object.

extrap_pts

number of points to extrapolate.

pred_pts

number of points to base the extrapolation on.

method

character string specifying the method to fit the model. Must be one of the strings in the default argument (the first few characters are sufficient). Defaults to "burg".

rem_add

remove additional points from the end of the FID to maintain the original length of the dataset. Default to TRUE.

...

additional arguments to specific methods, see ?ar.

Value

back extrapolated data.


Convert a basis object to a dynamic mrs_data object.

Description

Convert a basis object to a dynamic mrs_data object.

Usage

basis2dyn_mrs_data(basis, amps, tr)

Arguments

basis

basis set object.

amps

a data frame with each column corresponding to a basis element and each row corresponding to each dynamic scan.

tr

the dataset repetition time in seconds.

Value

a dynamic mrs_data object.


Convert a basis object to an mrs_data object - where basis signals are spread across the dynamic dimension.

Description

Convert a basis object to an mrs_data object - where basis signals are spread across the dynamic dimension.

Usage

basis2mrs_data(
  basis,
  sum_elements = FALSE,
  amps = NULL,
  shifts = NULL,
  lbs = NULL
)

Arguments

basis

basis set object.

sum_elements

return the sum of basis elements (logical)

amps

a vector of scaling factors to apply to each basis element.

shifts

a vector of frequency shifts (in ppm) to apply to each basis element.

lbs

a vector of Lorentzian line broadening terms (in Hz) to apply to each basis element.

Value

an mrs_data object with basis signals spread across the dynamic dimension or summed.


Generate a spline basis, slightly adapted from : "Splines, knots, and penalties", Eilers 2010.

Description

Generate a spline basis, slightly adapted from : "Splines, knots, and penalties", Eilers 2010.

Usage

bbase(N, number, deg = 3)

Arguments

N

number of data points.

number

number of spline functions.

deg

spline degree : deg = 1 linear, deg = 2 quadratic, deg = 3 cubic.

Value

spline basis as a matrix.


Baseline correction using the ALS method.

Description

Eilers P. H. C. and Boelens H. F. M. (2005) Baseline correction with asymmetric least squares smoothing. Leiden Univ. Medical Centre Report.

Usage

bc_als(mrs_data, lambda = 10000, p = 0.001, ret_bc_only = TRUE)

Arguments

mrs_data

mrs_data object.

lambda

controls the baseline flexibility.

p

controls the penalty for negative data points.

ret_bc_only

return the baseline corrected data only. When FALSE the baseline estimate and input data will be returned.

Value

baseline corrected data.


Remove a constant baseline offset based on a reference spectral region.

Description

Remove a constant baseline offset based on a reference spectral region.

Usage

bc_constant(mrs_data, xlim)

Arguments

mrs_data

MRS data.

xlim

spectral range containing a flat baseline region to measure the offset.

Value

baseline corrected data.


Apply and subtract a Gaussian smoother in the spectral domain.

Description

Apply and subtract a Gaussian smoother in the spectral domain.

Usage

bc_gauss(mrs_data, smo_ppm_sd)

Arguments

mrs_data

mrs_data object.

smo_ppm_sd

Gaussian smoother sd in ppm units.

Value

smoother subtracted data.


Fit and subtract a polynomial to each spectrum in a dataset.

Description

Fit and subtract a polynomial to each spectrum in a dataset.

Usage

bc_poly(mrs_data, p_deg = 1)

Arguments

mrs_data

mrs_data object.

p_deg

polynomial degree.

Value

polynomial subtracted data.


Fit and subtract a smoothing spline to each spectrum in a dataset.

Description

Fit and subtract a smoothing spline to each spectrum in a dataset.

Usage

bc_spline(mrs_data, spar = 0.5, nknots = 100)

Arguments

mrs_data

mrs_data object.

spar

smoothing parameter typically between 0 and 1.

nknots

number of spline knots.

Value

smoothing spline subtracted data.


Covert a beta value in the time-domain to an equivalent linewidth in Hz: x * exp(-i * t * t * beta).

Description

Covert a beta value in the time-domain to an equivalent linewidth in Hz: x * exp(-i * t * t * beta).

Usage

beta2lw(beta)

Arguments

beta

beta damping value.

Value

linewidth value in Hz.


Bin equally spaced spectral regions.

Description

Bin equally spaced spectral regions.

Usage

bin_spec(mrs_data, width = 0.05, unit = "ppm")

Arguments

mrs_data

data to be "binned".

width

bin width.

unit

bin width unit, can be "ppm" (default) or "pts".

Value

binned mrs_data object.


Estimate the correlation matrix for a basis set.

Description

Estimate the correlation matrix for a basis set.

Usage

calc_basis_corr_mat(basis, xlim = c(4, 0.2), zf = TRUE)

Arguments

basis

basis_set object.

xlim

spectral range to use in ppm.

zf

zero-fill the basis set.

Value

correlation matrix.


Estimate the CRLB for each element in a basis set.

Description

Estimate the CRLB for each element in a basis set.

Usage

calc_basis_crlbs(
  basis,
  xlim = c(4, 0.2),
  zf = TRUE,
  sd = 1,
  bl_comp_pppm = NULL
)

Arguments

basis

basis_set object.

xlim

spectral range to use in ppm.

zf

zero-fill the basis set.

sd

standard deviation of the noise.

bl_comp_pppm

number spline baseline components to append per-ppm.

Value

a vector of predicted errors.


Calculate the noise correlation between coil elements.

Description

Calculate the noise correlation between coil elements.

Usage

calc_coil_noise_cor(noise_data)

Arguments

noise_data

mrs_data object with one FID for each coil element.

Value

correlation matrix.


Calculate the noise standard deviation for each coil element.

Description

Calculate the noise standard deviation for each coil element.

Usage

calc_coil_noise_sd(noise_data)

Arguments

noise_data

mrs_data object with one FID for each coil element.

Value

array of standard deviations.


Calculate the efficiency of a regressor data frame.

Description

Calculate the efficiency of a regressor data frame.

Usage

calc_design_efficiency(regressor_df, contrasts)

Arguments

regressor_df

input regressor data frame.

contrasts

a vector of contrast values.


Calculate the effective dimensions of a spline smoother from lambda.

Description

Calculate the effective dimensions of a spline smoother from lambda.

Usage

calc_ed_from_lambda(spline_basis, deriv_mat, lambda)

Arguments

spline_basis

spline basis.

deriv_mat

derivative matrix.

lambda

smoothing parameter.

Value

the effective dimension value.


Calculate the FWHM of a peak from a vector of intensity values.

Description

Calculate the FWHM of a peak from a vector of intensity values.

Usage

calc_peak_info_vec(data_pts, interp_f)

Arguments

data_pts

input vector.

interp_f

interpolation factor to improve the FWHM estimate.

Value

a vector of: x position of the highest data point, maximum peak value in the y axis, FWHM in the units of data points.


Perform a polynomial fit, subtract and return the standard deviation of the residuals.

Description

Perform a polynomial fit, subtract and return the standard deviation of the residuals.

Usage

calc_sd_poly(y, degree = 1)

Arguments

y

array.

degree

polynomial degree.

Value

standard deviation of the fit residuals.


Calculate the sum of squares differences between two mrs_data objects.

Description

Calculate the sum of squares differences between two mrs_data objects.

Usage

calc_spec_diff(mrs_data, ref = NULL, xlim = c(4, 0.5))

Arguments

mrs_data

mrs_data object.

ref

reference mrs_data object to calculate differences.

xlim

spectral limits to perform calculation.

Value

an array of the sum of squared difference values.


Calculate the spectral SNR.

Description

SNR is defined as the maximum signal value divided by the standard deviation of the noise.

Usage

calc_spec_snr(
  mrs_data,
  sig_region = c(4, 0.5),
  noise_region = c(-0.5, -2.5),
  p_order = 2,
  interp_f = 4,
  full_output = FALSE
)

Arguments

mrs_data

an object of class mrs_data.

sig_region

a ppm region to define where the maximum signal value should be estimated.

noise_region

a ppm region to defined where the noise level should be estimated.

p_order

polynomial order to fit to the noise region before estimating the standard deviation.

interp_f

interpolation factor to improve detection of the highest signal value.

full_output

output signal, noise and SNR values separately.

Details

The mean noise value is subtracted from the maximum signal value to reduce DC offset bias. A polynomial detrending fit (second order by default) is applied to the noise region before the noise standard deviation is estimated.

Value

an array of SNR values.


Check LCModel can be run

Description

Check LCModel can be run

Usage

check_lcm()

Check the TARQUIN binary can be run

Description

Check the TARQUIN binary can be run

Usage

check_tqn()

Create a logical circular mask spanning the full extent of an n x n matrix.

Description

Create a logical circular mask spanning the full extent of an n x n matrix.

Usage

circ_mask(d, n, offset = 1)

Arguments

d

diameter of the mask.

n

number of matrix rows and columns.

offset

offset the mask centre in matrix dimension units.

Value

logical n x n mask matrix.


Zero all coherence orders other than the one supplied as an argument.

Description

Zero all coherence orders other than the one supplied as an argument.

Usage

coherence_filter(sys, rho, order = 0)

Arguments

sys

spin system object.

rho

density matrix.

order

coherence order to keep (default is 0).

Value

density matrix.


Collapse MRS data by concatenating spectra along the dynamic dimension.

Description

Collapse MRS data by concatenating spectra along the dynamic dimension.

Usage

collapse_to_dyns(x, rm_masked = FALSE)

## S3 method for class 'mrs_data'
collapse_to_dyns(x, rm_masked = FALSE)

## S3 method for class 'fit_result'
collapse_to_dyns(x, rm_masked = FALSE)

Arguments

x

data object to be collapsed (mrs_data or fit_result object).

rm_masked

remove masked dynamics from the output.

Value

collapsed data with spectra or fits concatenated along the dynamic dimension.


Combine coil data based on the first data point of a reference signal.

Description

By default, elements are phased and scaled prior to summation. Where a reference signal is not given, the mean dynamic signal will be used instead.

Usage

comb_coils(
  metab,
  ref = NULL,
  noise = NULL,
  scale = TRUE,
  scale_method = "sig_noise_sq",
  sum_coils = TRUE,
  noise_region = c(-0.5, -2.5),
  average_ref_dyns = TRUE,
  ref_pt_index = 1,
  ret_metab_only = FALSE
)

Arguments

metab

MRS data containing metabolite data.

ref

MRS data containing reference data (optional).

noise

MRS data from a noise scan (optional).

scale

option to rescale coil elements based on the first data point (logical).

scale_method

one of "sig_noise_sq", "sig_noise" or "sig".

sum_coils

sum the coil elements as a final step (logical).

noise_region

the spectral region (in ppm) to estimate the noise.

average_ref_dyns

take the mean of the reference scans in the dynamic dimension before use.

ref_pt_index

time-domain point to use for estimating phase and scaling values.

ret_metab_only

return the metabolite data only, even if reference data has been specified.

Value

MRS data.


Combine MRSI coil data using the GLS method presented by An et al JMRI 37:1445-1450 (2013).

Description

Combine MRSI coil data using the GLS method presented by An et al JMRI 37:1445-1450 (2013).

Usage

comb_coils_mrsi_gls(metab, noise_pts = 30, noise_mrs = NULL)

Arguments

metab

MRSI data containing metabolite data.

noise_pts

number of points from the end of the FIDs to use for noise covariance estimation.

noise_mrs

MRS data containing noise information for each coil.

Value

coil combined MRSI data.


Combine SVS coil data using the GLS method presented by An et al JMRI 37:1445-1450 (2013).

Description

Combine SVS coil data using the GLS method presented by An et al JMRI 37:1445-1450 (2013).

Usage

comb_coils_svs_gls(
  metab,
  ref = NULL,
  noise_pts = 256,
  noise_mrs = NULL,
  use_mean_sens = TRUE
)

Arguments

metab

MRS data containing metabolite data.

ref

MRS data containing reference data (optional).

noise_pts

number of points from the end of the FIDs to use for noise covariance estimation.

noise_mrs

MRS data containing noise information for each coil.

use_mean_sens

use the dynamic mean to estimate coil sensitivities.

Value

coil combined MRS data.


Combine all fitting data points from a list of fits into a single data frame.

Description

Combine all fitting data points from a list of fits into a single data frame.

Usage

comb_fit_list_fit_tables(
  fit_list,
  add_extra = TRUE,
  harmonise_ppm = TRUE,
  inc_basis_sigs = FALSE,
  inc_indices = TRUE,
  add_res_id = TRUE
)

Arguments

fit_list

list of fit_result objects.

add_extra

add variables in the extra data frame to the output (TRUE).

harmonise_ppm

ensure the ppm scale for each fit is identical to the first.

inc_basis_sigs

include the individual fitting basis signals in the output table, defaults to FALSE.

inc_indices

include indices such as X, Y and coil in the output, defaults to TRUE. These are generally not useful for SVS analysis.

add_res_id

add a res_id column to the output to distinguish between datasets.

Value

a data frame containing the fit data points.


Combine the fit result tables from a list of fit results.

Description

Combine the fit result tables from a list of fit results.

Usage

comb_fit_list_result_tables(fit_list, add_extra = TRUE, add_res_id = TRUE)

Arguments

fit_list

a list of fit_result objects.

add_extra

add variables in the extra data frame to the output (TRUE).

add_res_id

add a res_id column to the output to distinguish between datasets.

Value

a data frame combine all fit result tables with an additional id column to differentiate between data sets. Any variables in the extra data frame may be optionally added to the result.


Combine all fitting data points into a single data frame.

Description

Combine all fitting data points into a single data frame.

Usage

comb_fit_tables(fit_res, inc_basis_sigs = FALSE, inc_indices = TRUE)

Arguments

fit_res

a single fit_result object.

inc_basis_sigs

include the individual fitting basis signals in the output table, defaults to FALSE.

inc_indices

include indices such as X, Y and coil in the output, defaults to TRUE. These are generally not useful for SVS analysis.

Value

a data frame containing the fit data points.


Combine a reference and metabolite mrs_data object.

Description

Combine a reference and metabolite mrs_data object.

Usage

comb_metab_ref(metab, ref)

Arguments

metab

metabolite mrs_data object.

ref

reference mrs_data object.

Value

combined metabolite and reference mrs_data object.


Apply Conj operator to an MRS dataset.

Description

Apply Conj operator to an MRS dataset.

Usage

## S3 method for class 'mrs_data'
Conj(z)

Arguments

z

MRS data.

Value

MRS data following Conj operator.


Convolve two MRS data objects.

Description

Convolve two MRS data objects.

Usage

conv_mrs(mrs_data, conv)

Arguments

mrs_data

MRS data to be convolved.

conv

convolution data stored as an mrs_data object.

Value

convolved data.


Crop basis_set object based on a frequency range.

Description

Crop basis_set object based on a frequency range.

Usage

crop_basis(basis, xlim = c(4, 0.2), scale = "ppm")

Arguments

basis

basis_set object to be cropped in the spectral dimension.

xlim

range of values to crop in the spectral dimension eg xlim = c(4, 0.2).

scale

the units to use for the frequency scale, can be one of: "ppm", "hz" or "points".

Value

cropped mrs_data object.


Crop mrs_data object based on a frequency range.

Description

Crop mrs_data object based on a frequency range.

Usage

crop_spec(mrs_data, xlim = c(4, 0.2), scale = "ppm")

Arguments

mrs_data

MRS data.

xlim

range of values to crop in the spectral dimension eg xlim = c(4, 0.2).

scale

the units to use for the frequency scale, can be one of: "ppm", "hz" or "points".

Value

cropped mrs_data object.


Crop mrs_data object data points in the time-domain.

Description

Crop mrs_data object data points in the time-domain.

Usage

crop_td_pts(mrs_data, start = NULL, end = NULL)

Arguments

mrs_data

MRS data.

start

starting data point (defaults to 1).

end

ending data point (defaults to the last saved point).

Value

cropped mrs_data object.


Crop mrs_data object data points at the end of the FID.

Description

Crop mrs_data object data points at the end of the FID.

Usage

crop_td_pts_end(mrs_data, pts)

Arguments

mrs_data

MRS data.

pts

number of points to remove from the end of the FID.

Value

cropped mrs_data object.


Crop mrs_data object data points in the time-domain rounding down to the next smallest power of two (pot). Data that already has a pot length will not be changed.

Description

Crop mrs_data object data points in the time-domain rounding down to the next smallest power of two (pot). Data that already has a pot length will not be changed.

Usage

crop_td_pts_pot(mrs_data)

Arguments

mrs_data

MRS data.

Value

cropped mrs_data object.


Crop an MRSI dataset in the x-y direction

Description

Crop an MRSI dataset in the x-y direction

Usage

crop_xy(mrs_data, x_dim, y_dim)

Arguments

mrs_data

MRS data object.

x_dim

x dimension output length.

y_dim

y dimension output length.

Value

selected subset of MRS data.


Compute the vector cross product between vectors x and y. Adapted from http://stackoverflow.com/questions/15162741/what-is-rs-crossproduct-function

Description

Compute the vector cross product between vectors x and y. Adapted from http://stackoverflow.com/questions/15162741/what-is-rs-crossproduct-function

Usage

crossprod_3d(x, y)

Arguments

x

vector of length 3.

y

vector of length 3.

Value

vector cross product of x and y.


Decimate an MRS signal to half the original sampling frequency by filtering in the frequency domain before down sampling.

Description

Decimate an MRS signal to half the original sampling frequency by filtering in the frequency domain before down sampling.

Usage

decimate_mrs_fd(mrs_data)

Arguments

mrs_data

MRS data object.

Value

decimated data at half the original sampling frequency.


Decimate an MRS signal by filtering in the time domain before downsampling.

Description

Decimate an MRS signal by filtering in the time domain before downsampling.

Usage

decimate_mrs_td(mrs_data, q = 2, n = 4, ftype = "iir")

Arguments

mrs_data

MRS data object.

q

integer factor to downsample by (default = 2).

n

filter order used in the downsampling.

ftype

filter type, "iir" or "fir".

Value

decimated data.


Deconvolve two MRS data objects.

Description

Deconvolve two MRS data objects.

Usage

deconv_mrs(mrs_data_a, mrs_data_b)

Arguments

mrs_data_a

MRS data to be deconvolved.

mrs_data_b

MRS data to be deconvolved.

Value

deconvolved data.


Return (and optionally modify using the input arguments) a list of the default acquisition parameters.

Description

Return (and optionally modify using the input arguments) a list of the default acquisition parameters.

Usage

def_acq_paras(
  ft = getOption("spant.def_ft"),
  fs = getOption("spant.def_fs"),
  N = getOption("spant.def_N"),
  ref = getOption("spant.def_ref"),
  nuc = getOption("spant.def_nuc")
)

Arguments

ft

specify the transmitter frequency in Hz.

fs

specify the sampling frequency in Hz.

N

specify the number of data points in the spectral dimension.

ref

specify the reference value for ppm scale.

nuc

specify the resonant nucleus.

Value

A list containing the following elements:

  • ft transmitter frequency in Hz.

  • fs sampling frequency in Hz.

  • N number of data points in the spectral dimension.

  • ref reference value for ppm scale.

  • nuc resonant nucleus.


Return the default sampling frequency in Hz.

Description

Return the default sampling frequency in Hz.

Usage

def_fs()

Value

sampling frequency in Hz.


Return the default transmitter frequency in Hz.

Description

Return the default transmitter frequency in Hz.

Usage

def_ft()

Value

transmitter frequency in Hz.


Return the default number of data points in the spectral dimension.

Description

Return the default number of data points in the spectral dimension.

Usage

def_N()

Value

number of data points in the spectral dimension.


Return the default nucleus.

Description

Return the default nucleus.

Usage

def_nuc()

Value

number of data points in the spectral dimension.


Return the default reference value for ppm scale.

Description

Return the default reference value for ppm scale.

Usage

def_ref()

Value

reference value for ppm scale.


A very simple DICOM reader.

Description

Note this reader is very basic and does not use a DICOM dictionary or try to convert the data to the correct datatype. For a more robust and sophisticated reader use the oro.dicom package.

Usage

dicom_reader(
  input,
  tags = list(sop_class_uid = "0008,0016"),
  endian = "little",
  debug = FALSE
)

Arguments

input

either a file path or raw binary object.

tags

a named list of tags to be extracted from the file. eg tags <- list(spec_data = "7FE1,1010", pat_name = "0010,0010")

endian

can be "little" or "big".

debug

print out some debugging information, can be "little" or "big".

Value

a list with the same structure as the input, but with tag codes replaced with the corresponding data in a raw format.


Apply the diff operator to an MRS dataset in the FID/spectral dimension.

Description

Apply the diff operator to an MRS dataset in the FID/spectral dimension.

Usage

diff_mrs(mrs_data, ...)

Arguments

mrs_data

MRS data.

...

additional arguments to the diff function.

Value

MRS data following diff operator.


Downsample an MRS signal by a factor of 2 using an FFT "brick-wall" filter.

Description

Downsample an MRS signal by a factor of 2 using an FFT "brick-wall" filter.

Usage

downsample_mrs_fd(mrs_data)

Arguments

mrs_data

MRS data object.

Value

downsampled data.


Downsample an MRS signal by a factor of 2 by removing every other data point in the time-domain. Note, signals outside the new sampling frequency will be aliased.

Description

Downsample an MRS signal by a factor of 2 by removing every other data point in the time-domain. Note, signals outside the new sampling frequency will be aliased.

Usage

downsample_mrs_td(mrs_data)

Arguments

mrs_data

MRS data object.

Value

downsampled data.


Return a time scale vector of acquisition times for a dynamic MRS scan. The first temporal scan is assigned a value of 0.

Description

Return a time scale vector of acquisition times for a dynamic MRS scan. The first temporal scan is assigned a value of 0.

Usage

dyn_acq_times(mrs_data = NULL, tr = NULL, Ndyns = NULL, Ntrans = NULL)

Arguments

mrs_data

MRS data.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

Value

time scale vector in units of seconds.


Eddy current correction.

Description

Apply eddy current correction using the Klose method.

Usage

ecc(metab, ref, rev = FALSE)

Arguments

metab

MRS data to be corrected.

ref

reference dataset.

rev

reverse the correction.

Details

In vivo proton spectroscopy in presence of eddy currents. Klose U. Magn Reson Med. 1990 Apr;14(1):26-30.

Value

corrected data in the time domain.


Create an elliptical mask stored as a matrix of logical values.

Description

Create an elliptical mask stored as a matrix of logical values.

Usage

elliptical_mask(xN, yN, x0, y0, xr, yr, angle)

Arguments

xN

number of pixels in the x dimension.

yN

number of pixels in the y dimension.

x0

centre of ellipse in the x direction in units of pixels.

y0

centre of ellipse in the y direction in units of pixels.

xr

radius in the x direction in units of pixels.

yr

radius in the y direction in units of pixels.

angle

angle of rotation in degrees.

Value

logical mask matrix with dimensions fov_yN x fov_xN.


Estimate the standard deviation of the noise from a segment of an mrs_data object.

Description

Estimate the standard deviation of the noise from a segment of an mrs_data object.

Usage

est_noise_sd(mrs_data, n = 100, offset = 100, p_order = 2)

Arguments

mrs_data

MRS data object.

n

number of data points (taken from the end of array) to use in the estimation.

offset

number of final points to exclude from the calculation.

p_order

polynomial order to fit to the data before estimating the standard deviation.

Value

standard deviation array.


Frequency-domain convolution based filter.

Description

Frequency-domain convolution based filter.

Usage

fd_conv_filt(mrs_data, K = 25, ext = 1)

Arguments

mrs_data

MRS data to be filtered.

K

window width in data points.

ext

point separation for linear extrapolation.


Apply a Gaussian smoother in the spectral domain.

Description

Apply a Gaussian smoother in the spectral domain.

Usage

fd_gauss_smo(mrs_data, smo_ppm_sd)

Arguments

mrs_data

mrs_data object.

smo_ppm_sd

Gaussian smoother sd in ppm units.

Value

spectrally smoothed data.


Transform frequency-domain data to the time-domain.

Description

Transform frequency-domain data to the time-domain.

Usage

fd2td(mrs_data)

Arguments

mrs_data

MRS data in frequency-domain representation.

Value

MRS data in time-domain representation.


Search for MRS data files in a BIDS filesystem structure.

Description

Search for MRS data files in a BIDS filesystem structure.

Usage

find_bids_mrs(path, output_full_path = FALSE)

Arguments

path

path to the directory containing the BIDS structure.

output_full_path

output the full normalised data paths.

Value

data frame containing full paths and information on each MRS file.


Find valid MRS data files recursively from a directory path.

Description

Find valid MRS data files recursively from a directory path.

Usage

find_mrs_files(dir)

Arguments

dir

a directory path.

Value

a vector of valid MRS data files.


Extract the fit amplitudes from an object of class fit_result.

Description

Extract the fit amplitudes from an object of class fit_result.

Usage

fit_amps(
  x,
  inc_index = FALSE,
  sort_names = FALSE,
  append_common_1h_comb = TRUE
)

Arguments

x

fit_result object.

inc_index

include columns for the voxel index.

sort_names

sort the basis set names alphabetically.

append_common_1h_comb

append commonly used 1H metabolite combinations eg tNAA = NAA + NAAG.

Value

a dataframe of amplitudes.


Calculate diagnostic information for object of class fit_result.

Description

Calculate diagnostic information for object of class fit_result.

Usage

fit_diags(x, amps = NULL)

Arguments

x

fit_result object.

amps

known metabolite amplitudes.

Value

a dataframe of diagnostic information.


Perform a fit based analysis of MRS data.

Description

Note that TARQUIN and LCModel require these packages to be installed, and the functions set_tqn_cmd and set_lcm_cmd (respectively) need to be used to specify the location of these software packages.

Usage

fit_mrs(
  metab,
  basis = NULL,
  method = "ABFIT",
  w_ref = NULL,
  opts = NULL,
  parallel = FALSE,
  cl = NULL,
  time = TRUE,
  progress = "text",
  extra = NULL
)

Arguments

metab

metabolite data.

basis

basis class object or character vector to basis file in LCModel .basis format.

method

'ABFIT' (default), 'VARPRO', 'VARPRO_3P', 'TARQUIN' or 'LCMODEL'.

w_ref

water reference data for concentration scaling (optional).

opts

options to pass to the analysis method.

parallel

perform analyses in parallel (TRUE or FALSE).

cl

a parallel socket cluster required to run analyses in parallel. Eg, cl <- parallel::makeCluster(4).

time

measure the time taken for the analysis to complete (TRUE or FALSE).

progress

option is passed to plyr::alply function to display a progress bar during fitting. Default value is "text", set to "none" to disable.

extra

an optional data frame to provide additional variables for use in subsequent analysis steps, eg id or grouping variables.

Details

Fitting approaches described in the following references: ABfit Wilson, M. Adaptive baseline fitting for 1H MR spectroscopy analysis. Magn Reson Med 2012;85:13-29.

VARPRO van der Veen JW, de Beer R, Luyten PR, van Ormondt D. Accurate quantification of in vivo 31P NMR signals using the variable projection method and prior knowledge. Magn Reson Med 1988;6:92-98.

TARQUIN Wilson, M., Reynolds, G., Kauppinen, R. A., Arvanitis, T. N. & Peet, A. C. A constrained least-squares approach to the automated quantitation of in vivo 1H magnetic resonance spectroscopy data. Magn Reson Med 2011;65:1-12.

LCModel Provencher SW. Estimation of metabolite concentrations from localized in vivo proton NMR spectra. Magn Reson Med 1993;30:672-679.

Value

MRS analysis object.

Examples

fname <- system.file("extdata", "philips_spar_sdat_WS.SDAT", package =
"spant")
svs <- read_mrs(fname)
## Not run: 
basis <- sim_basis_1h_brain_press(svs)
fit_result <- fit_mrs(svs, basis)

## End(Not run)

Write fit results table to a csv file.

Description

Write fit results table to a csv file.

Usage

fit_res2csv(fit_res, fname, unscaled = FALSE)

Arguments

fit_res

fit result object.

fname

filename of csv file.

unscaled

output the unscaled result table (default = FALSE).


Standard SVS 1H brain analysis pipeline.

Description

Note this function is still under development and liable to changes.

Usage

fit_svs(
  input,
  w_ref = NULL,
  output_dir = NULL,
  external_basis = NULL,
  p_vols = NULL,
  format = NULL,
  pul_seq = NULL,
  TE = NULL,
  TR = NULL,
  TE1 = NULL,
  TE2 = NULL,
  TE3 = NULL,
  TM = NULL,
  append_basis = NULL,
  remove_basis = NULL,
  pre_align = TRUE,
  dfp_corr = TRUE,
  output_ratio = NULL,
  ecc = FALSE,
  hsvd_width = NULL,
  fit_method = NULL,
  fit_opts = NULL,
  fit_subset = NULL,
  legacy_ws = FALSE,
  w_att = 0.7,
  w_conc = 35880,
  use_basis_cache = "auto",
  summary_measures = NULL,
  dyn_av_block_size = NULL,
  dyn_av_scheme = NULL,
  dyn_av_scheme_file = NULL,
  lcm_bin_path = NULL,
  plot_ppm_xlim = NULL,
  verbose = FALSE
)

Arguments

input

path or mrs_data object containing MRS data.

w_ref

path or mrs_data object containing MRS water reference data.

output_dir

directory path to output fitting results.

external_basis

precompiled basis set object to use for analysis.

p_vols

a numeric vector of partial volumes expressed as percentages. Defaults to 100% white matter. A voxel containing 100% gray matter tissue would use : p_vols = c(WM = 0, GM = 100, CSF = 0).

format

Override automatic data format detection. See format argument in read_mrs() for permitted values.

pul_seq

Pulse sequence to use for basis simulation. Can be one of the following values : "press", "press_ideal", "press_shaped", "steam" or "slaser". If "press" then "press_ideal" will be assumed unless the magnetic field is stronger that 2.8 Tesla, "press_shaped" will be assumed for 2.9 Tesla and above.

TE

metabolite mrs data echo time in seconds. If not supplied this will be guessed from the metab data file.

TR

metabolite mrs data repetition time in seconds. If not supplied this will be guessed from the metab data file.

TE1

PRESS or sLASER sequence timing parameter in seconds.

TE2

PRESS or sLASER sequence timing parameter in seconds.

TE3

sLASER sequence timing parameter in seconds.

TM

STEAM mixing time parameter in seconds.

append_basis

names of extra signals to add to the default basis. Eg append_basis = c("peth", "cit"). Cannot be used with precompiled basis sets.

remove_basis

grep expression to match names of signals to remove from the basis. For example: use "*" to remove all signals, "^mm|^lip" to remove all macromolecular and lipid signals, "^lac" to remove lactate. This operation is performed before signals are added with append_basis. Cannot be used with precompiled basis sets.

pre_align

perform simple frequency alignment to known reference peaks.

dfp_corr

perform dynamic frequency and phase correction using the RATS method.

output_ratio

optional string to specify a metabolite ratio to output. Defaults to "tCr". Multiple metabolites may be specified for multiple outputs. Set to NA to omit.

ecc

option to perform water reference based eddy current correction, defaults to FALSE.

hsvd_width

set the width of the HSVD filter in Hz. Note the applied width is between -width and +width Hz, with 0 Hz being defined at the centre of the spectral width. Default is disabled (set to NULL), 30 Hz is a reasonable value.

fit_method

can be "ABFIT-REG" or "LCMODEL. Defaults to "ABFIT-REG".

fit_opts

options to pass to the fitting method.

fit_subset

specify a subset of dynamics to analyse, for example 1:16 would only fit the first 16 dynamic scans.

legacy_ws

perform and output legacy water scaling compatible with default LCModel and TARQUIN behaviour. See w_att and w_conc arguments to change the default assumptions. Default value is FALSE.

w_att

water attenuation factor (default = 0.7) for legacy water scaling. Assumes water T2 of 80ms and a TE = 30 ms. exp(-30ms / 80ms) ~ 0.7.

w_conc

assumed water concentration (default = 35880) for legacy water scaling. Default value corresponds to typical white matter. Set to 43300 for gray matter, and 55556 for phantom measurements.

use_basis_cache

Pre-cache basis sets to reduce analysis speed. Can be one of the following : "auto", "all" or "none". The default value of "auto" will only use the cache for 3T PRESS - which generally requires more detailed simulation due to high CSD.

summary_measures

output an additional table with a subset of metabolite levels, eg c("tNAA", "tNAA/tCr", "tNAA/tCho", "Lac/tNAA").

dyn_av_block_size

perform temporal averaging with the specified block size. Defaults to NULL, eg average across all dynamic scans.

dyn_av_scheme

a numeric vector of sequential integers (starting at 1), with the same length as the number of dynamic scans in the metabolite data. For example: c(1, 1, 2, 1, 1, 3, 1, 1).

dyn_av_scheme_file

a file path containing a single column of sequential integers (starting at 1) with the same length as the number of dynamic scans in the metabolite data. File may be formatted as .xlsx, .xls, text or csv format.

lcm_bin_path

set the path to LCModel binary.

plot_ppm_xlim

plotting ppm axis limits in the html results. results.

verbose

output potentially useful information.

Examples

metab <- system.file("extdata", "philips_spar_sdat_WS.SDAT",
                     package = "spant")
w_ref <- system.file("extdata", "philips_spar_sdat_W.SDAT",
                     package = "spant")
out_dir <- file.path("~", "fit_svs_result")
## Not run: 
fit_result <- fit_svs(metab, w_ref, out_dir)

## End(Not run)

GUI interface for the standard SVS 1H brain analysis pipeline, this is a work in progress, and not ready for serious use.

Description

GUI interface for the standard SVS 1H brain analysis pipeline, this is a work in progress, and not ready for serious use.

Usage

fit_svs_gui()

Fit a T1 recovery curve, from multiple TIs, to a set of amplitudes.

Description

Fit a T1 recovery curve, from multiple TIs, to a set of amplitudes.

Usage

fit_t1_ti_array(
  ti_vec,
  amp_vec,
  lower = 0,
  upper = 10,
  output_fit_res = 0.01,
  ret_full = TRUE
)

Arguments

ti_vec

vector of TI values in seconds.

amp_vec

vector of amplitudes.

lower

minimum allowable T1 value.

upper

maximum allowable T1 value.

output_fit_res

temporal resolution (seconds) of the ideal output relaxation curve.

ret_full

return full fitting information including ideal relaxation curve.

Value

a list containing relaxation parameters and an ideal curve for fit evaluation.


Fit a T1 recovery curve, from multiple TRs, to a set of amplitudes.

Description

Fit a T1 recovery curve, from multiple TRs, to a set of amplitudes.

Usage

fit_t1_tr_array(
  tr_vec,
  amp_vec,
  lower = 0,
  upper = 10,
  output_fit_res = 0.01,
  ret_full = TRUE
)

Arguments

tr_vec

vector of TR values in seconds.

amp_vec

vector of amplitudes.

lower

minimum allowable T1 value.

upper

maximum allowable T1 value.

output_fit_res

temporal resolution (seconds) of the ideal output relaxation curve.

ret_full

return full fitting information including ideal relaxation curve.

Value

a list containing relaxation parameters and an ideal curve for fit evaluation.


Fit a T2 relaxation curve, from multiple TEs, to a set of amplitudes.

Description

Fit a T2 relaxation curve, from multiple TEs, to a set of amplitudes.

Usage

fit_t2_te_array(
  te_vec,
  amp_vec,
  lower = 0,
  upper = 10,
  output_fit_res = 0.01,
  ret_full = TRUE
)

Arguments

te_vec

vector of TE values in seconds.

amp_vec

vector of amplitudes.

lower

minimum allowable T2 value.

upper

maximum allowable T2 value.

output_fit_res

temporal resolution (seconds) of the ideal output relaxation curve.

ret_full

return full fitting information including ideal relaxation curve.

Value

a list containing relaxation parameters and an ideal curve for fit evaluation.


Return the phase of the first data point in the time-domain.

Description

Return the phase of the first data point in the time-domain.

Usage

fp_phase(mrs_data)

Arguments

mrs_data

MRS data.

Value

phase values in degrees.


Perform a zeroth order phase correction based on the phase of the first data point in the time-domain.

Description

Perform a zeroth order phase correction based on the phase of the first data point in the time-domain.

Usage

fp_phase_correct(mrs_data, ret_phase = FALSE)

Arguments

mrs_data

MRS data to be corrected.

ret_phase

return phase values (logical).

Value

corrected data or a list with corrected data and optional phase values.


Scale the first time-domain data point in an mrs_data object.

Description

Scale the first time-domain data point in an mrs_data object.

Usage

fp_scale(mrs_data, scale = 0.5)

Arguments

mrs_data

MRS data.

scale

scaling value, defaults to 0.5.

Value

scaled mrs_data object.


Return the sampling frequency in Hz of an MRS dataset.

Description

Return the sampling frequency in Hz of an MRS dataset.

Usage

fs(mrs_data)

Arguments

mrs_data

MRS data.

Value

sampling frequency in Hz.


Apply the Fourier transform over the dynamic dimension.

Description

Apply the Fourier transform over the dynamic dimension.

Usage

ft_dyns(mrs_data, ft_shift = FALSE, ret_mod = FALSE, fd = TRUE)

Arguments

mrs_data

MRS data where the dynamic dimension is in the time-domain.

ft_shift

apply FT shift to the output, default is FALSE.

ret_mod

return the modulus out the transform, default is FALSE.

fd

transform the chemical shift axis to the frequency domain first, default is TRUE.

Value

transformed MRS data.


Perform a fft and ffshift on a vector.

Description

Perform a fft and ffshift on a vector.

Usage

ft_shift(vec_in)

Arguments

vec_in

vector input.

Value

output vector.


Perform a fft and fftshift on a matrix with each column replaced by its shifted fft.

Description

Perform a fft and fftshift on a matrix with each column replaced by its shifted fft.

Usage

ft_shift_mat(mat_in)

Arguments

mat_in

matrix input.

Value

output matrix.


Create a two dimensional Gaussian window function stored as a matrix.

Description

Create a two dimensional Gaussian window function stored as a matrix.

Usage

gausswin_2d(xN, yN, x0, y0, xw, yw)

Arguments

xN

number of pixels in the x dimension.

yN

number of pixels in the y dimension.

x0

centre of window function in the x direction in units of pixels. Note, only integer values are applied.

y0

centre of window function in the y direction in units of pixels. Note, only integer values are applied.

xw

the reciprocal of the standard deviation of the Gaussian window in x direction.

yw

the reciprocal of the standard deviation of the Gaussian window in y direction.

Value

matrix with dimensions fov_yN x fov_xN.


Generate baseline regressor.

Description

Generate baseline regressor.

Usage

gen_baseline_reg(mrs_data = NULL, tr = NULL, Ndyns = NULL, Ntrans = NULL)

Arguments

mrs_data

mrs_data object for timing information.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

Value

a single baseline regressor with value of 1.


Generate BOLD regressors.

Description

Generate BOLD regressors.

Usage

gen_bold_reg(
  onset,
  duration = NULL,
  trial_type = NULL,
  mrs_data = NULL,
  tr = NULL,
  Ndyns = NULL,
  Ntrans = NULL,
  match_tr = TRUE,
  dt = 0.1,
  normalise = FALSE
)

Arguments

onset

stimulus onset in seconds.

duration

stimulus duration in seconds.

trial_type

string label for the stimulus.

mrs_data

mrs_data object for timing information.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

match_tr

match the output to the input mrs_data.

dt

timing resolution for internal calculations.

normalise

normalise the response function to have a maximum value of one.

Value

BOLD regressor data frame.


Generate regressors by convolving a specified response function with a stimulus.

Description

Generate regressors by convolving a specified response function with a stimulus.

Usage

gen_conv_reg(
  onset,
  duration = NULL,
  trial_type = NULL,
  mrs_data = NULL,
  tr = NULL,
  Ndyns = NULL,
  Ntrans = NULL,
  resp_fn,
  match_tr = TRUE,
  normalise = FALSE
)

Arguments

onset

stimulus onset in seconds.

duration

stimulus duration in seconds.

trial_type

string label for the stimulus.

mrs_data

mrs_data object for timing information.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

resp_fn

a data frame specifying the response function to be convolved.

match_tr

match the output to the input mrs_data.

normalise

normalise the response function to have a maximum value of one.

Value

BOLD regressor data frame.


Generate the F product operator.

Description

Generate the F product operator.

Usage

gen_F(sys, op, detect = NULL)

Arguments

sys

spin system object.

op

operator, one of "x", "y", "z", "p", "m".

detect

detection nuclei.

Value

F product operator matrix.


Generate the Fxy product operator with a specified phase.

Description

Generate the Fxy product operator with a specified phase.

Usage

gen_F_xy(sys, phase, detect = NULL)

Arguments

sys

spin system object.

phase

phase angle in degrees.

detect

detection nuclei.

Value

product operator matrix.


Expand a regressor matrix for a group analysis.

Description

Expand a regressor matrix for a group analysis.

Usage

gen_group_reg(regressor_df, n)

Arguments

regressor_df

input regressor data frame.

n

number of datasets n the group.


Generate the I product operator for a single spin.

Description

Generate the I product operator for a single spin.

Usage

gen_I(n, spin_num, op)

Arguments

n

spin index number for the required operator.

spin_num

vector of spin numbers in the system.

op

operator, one of "x", "y", "z", "p", "m".

Value

I product operator matrix.


Generate impulse regressors.

Description

Generate impulse regressors.

Usage

gen_impulse_reg(
  onset,
  trial_type = NULL,
  mrs_data = NULL,
  tr = NULL,
  Ndyns = NULL,
  Ntrans = NULL
)

Arguments

onset

stimulus onset in seconds.

trial_type

string label for the stimulus.

mrs_data

mrs_data object for timing information.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

Value

impulse regressors data frame.


Generate polynomial regressors.

Description

Generate polynomial regressors.

Usage

gen_poly_reg(degree, mrs_data = NULL, tr = NULL, Ndyns = NULL, Ntrans = NULL)

Arguments

degree

the degree of the polynomial.

mrs_data

mrs_data object for timing information.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

Value

polynomial regressors.


Generate trapezoidal regressors.

Description

Generate trapezoidal regressors.

Usage

gen_trap_reg(
  onset,
  duration,
  trial_type = NULL,
  mrs_data = NULL,
  tr = NULL,
  Ndyns = NULL,
  Ntrans = NULL,
  rise_t = 0,
  fall_t = 0,
  exp_fall = FALSE,
  exp_fall_power = 1,
  smo_sigma = NULL,
  match_tr = TRUE,
  dt = 0.01,
  normalise = FALSE
)

Arguments

onset

stimulus onset in seconds.

duration

stimulus duration in seconds.

trial_type

string label for the stimulus.

mrs_data

mrs_data object for timing information.

tr

repetition time.

Ndyns

number of dynamic scans stored, potentially less than Ntrans if block averaging has been performed.

Ntrans

number of dynamic scans acquired.

rise_t

time to reach a plateau from baseline in seconds.

fall_t

time to fall from plateau level back to baseline in seconds.

exp_fall

model an exponential fall instead of linear.

exp_fall_power

exponential fall power.

smo_sigma

standard deviation of Gaussian smoothing kernel in seconds. Set to NULL to disable (default behavior).

match_tr

match the output to the input mrs_data.

dt

timing resolution for internal calculations.

normalise

normalise the response function to have a maximum value of one.

Value

trapezoidal regressor data frame.


Return a character vector of common 1H molecules found in healthy human brain.

Description

Note, this is a basic set and it may be appropriate to also include Asc, Gly and PEth for high quality MRS data.

Usage

get_1h_brain_basis_names(add = NULL, remove = NULL, inc_lip_mm = TRUE)

Arguments

add

optional character vector of additional molecular names. Eg c("asc", "gly", "peth").

remove

optional character vector of molecular names to remove from the set. Eg c("m_cr_ch2").

inc_lip_mm

include Lipid and MM basis signals.

Value

a character vector of molecule names.


Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Description

Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Usage

get_1h_brain_basis_paras(ft, metab_lw = NULL, lcm_compat = FALSE)

Arguments

ft

transmitter frequency in Hz.

metab_lw

linewidth of metabolite signals (Hz).

lcm_compat

when TRUE, lipid, MM and -CrCH molecules will be excluded from the output.

Value

list of mol_parameter objects.


Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Description

Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Usage

get_1h_brain_basis_paras_v1(ft, metab_lw = NULL, lcm_compat = FALSE)

Arguments

ft

transmitter frequency in Hz.

metab_lw

linewidth of metabolite signals (Hz).

lcm_compat

when TRUE, lipid, MM and -CrCH molecules will be excluded from the output.

Value

list of mol_parameter objects.


Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Description

Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Usage

get_1h_brain_basis_paras_v2(ft, metab_lw = NULL, lcm_compat = FALSE)

Arguments

ft

transmitter frequency in Hz.

metab_lw

linewidth of metabolite signals (Hz).

lcm_compat

when TRUE, lipid, MM and -CrCH molecules will be excluded from the output.

Value

list of mol_parameter objects.


Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Description

Return a list of mol_parameter objects suitable for 1H brain MRS analyses.

Usage

get_1h_brain_basis_paras_v3(ft, metab_lw = NULL, lcm_compat = FALSE)

Arguments

ft

transmitter frequency in Hz.

metab_lw

linewidth of metabolite signals (Hz).

lcm_compat

when TRUE, lipid, MM and -CrCH molecules will be excluded from the output.

Value

list of mol_parameter objects.


Return a character vector of molecules included in the GE BRAINO phantom.

Description

Return a character vector of molecules included in the GE BRAINO phantom.

Usage

get_1h_braino_basis_names()

Value

a character vector of molecule names.


Return a character vector of molecules included in the Gold Star Phantoms SPECTRE phantom.

Description

Return a character vector of molecules included in the Gold Star Phantoms SPECTRE phantom.

Usage

get_1h_spectre_basis_names()

Value

a character vector of molecule names.


Get the point spread function (PSF) for a 2D phase encoded MRSI scan.

Description

Get the point spread function (PSF) for a 2D phase encoded MRSI scan.

Usage

get_2d_psf(
  FOV = 160,
  mat_size = 16,
  sampling = "circ",
  hamming = FALSE,
  ensure_odd = TRUE
)

Arguments

FOV

field of view in mm.

mat_size

acquisition matrix size (not interpolated).

sampling

can be either "circ" for circular or "rect" for rectangular.

hamming

should Hamming k-space weighting be applied (default FALSE).

ensure_odd

add 1mm to the FOV when required to ensure the output pdf has odd dimensions. Required when using get_mrsi2d_seg.

Value

A matrix of the PSF with 1mm resolution.


Return acquisition parameters from a MRS data object.

Description

Return acquisition parameters from a MRS data object.

Usage

get_acq_paras(mrs_data)

Arguments

mrs_data

MRS data.

Value

list of acquisition parameters.


Return a subset of the input basis.

Description

Return a subset of the input basis.

Usage

get_basis_subset(basis, names, invert = FALSE)

Arguments

basis

input basis.

names

basis set elements to keep in the returned object.

invert

set to true to return all basis elements except those given in the names argument.

Value

a subset of the input basis.


Extract a subset of dynamic scans.

Description

Extract a subset of dynamic scans.

Usage

get_dyns(mrs_data, subset)

Arguments

mrs_data

dynamic MRS data.

subset

vector containing indices to the dynamic scans to be returned.

Value

MRS data containing the subset of requested dynamics.


Return even numbered dynamic scans starting from 1 (2,4,6...).

Description

Return even numbered dynamic scans starting from 1 (2,4,6...).

Usage

get_even_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

dynamic MRS data containing even numbered scans.


Return the first half of a dynamic series.

Description

Return the first half of a dynamic series.

Usage

get_fh_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

first half of the dynamic series.


Get a data array from a fit result.

Description

Get a data array from a fit result.

Usage

get_fit_map(fit_res, name)

Arguments

fit_res

fit_result object.

name

name of the quantity to plot, eg "tNAA".


Return the first time-domain data point.

Description

Return the first time-domain data point.

Usage

get_fp(mrs_data)

Arguments

mrs_data

MRS data.

Value

first time-domain data point.


Generate a gaussian pulse shape.

Description

Generate a gaussian pulse shape.

Usage

get_guassian_pulse(angle, n, trunc = 1)

Arguments

angle

pulse angle in degrees.

n

number of points to generate.

trunc

percentage truncation factor.


Return the first scans of a dynamic series.

Description

Return the first scans of a dynamic series.

Usage

get_head_dyns(mrs_data, n = 1)

Arguments

mrs_data

dynamic MRS data.

n

the number of dynamic scans to return.

Value

first scans of a dynamic series.


Generate a double gamma model of the HRF as used in SPM.

Description

Generate a double gamma model of the HRF as used in SPM.

Usage

get_hrf(end_t = 30, res_t = 0.01)

Arguments

end_t

last time point to generate in seconds.

res_t

temporal resolution in seconds, defaults to 10ms.

Value

a data.frame of time and HRF vectors.


Print the command to run the LCModel command-line program.

Description

Print the command to run the LCModel command-line program.

Usage

get_lcm_cmd()

Extract the metabolite component from an mrs_data object.

Description

Extract the metabolite component from an mrs_data object.

Usage

get_metab(mrs_data)

Arguments

mrs_data

MRS data.

Value

metabolite component.


Return a character array of names that may be used with the get_mol_paras function.

Description

Return a character array of names that may be used with the get_mol_paras function.

Usage

get_mol_names()

Value

a character array of names.


Get a mol_parameters object for a named molecule.

Description

Get a mol_parameters object for a named molecule.

Usage

get_mol_paras(name, ...)

Arguments

name

the name of the molecule.

...

arguments to pass to molecule definition function.


Generate an affine for nifti generation.

Description

Generate an affine for nifti generation.

Usage

get_mrs_affine(mrs_data, x_pos = 1, y_pos = 1, z_pos = 1)

Arguments

mrs_data

input data.

x_pos

x_position coordinate.

y_pos

y_position coordinate.

z_pos

z_position coordinate.

Value

affine matrix.


Generate a MRSI VOI from an mrs_data object.

Description

Generate a MRSI VOI from an mrs_data object.

Usage

get_mrsi_voi(mrs_data, target_mri = NULL, map = NULL, ker = mmand::boxKernel())

Arguments

mrs_data

MRS data.

target_mri

optional image data to match the intended volume space.

map

optional voi intensity map.

ker

kernel to rescale the map data to the target_mri. Default value is mmand::boxKernel(), use mmand::mnKernel() for a smoothed map.

Value

volume data as a nifti object.


Generate a MRSI voxel from an mrs_data object.

Description

Generate a MRSI voxel from an mrs_data object.

Usage

get_mrsi_voxel(mrs_data, target_mri, x_pos, y_pos, z_pos)

Arguments

mrs_data

MRS data.

target_mri

optional image data to match the intended volume space.

x_pos

x voxel coordinate.

y_pos

y voxel coordinate.

z_pos

z voxel coordinate.

Value

volume data as a nifti object.


Generate a MRSI voxel PSF from an mrs_data object.

Description

Generate a MRSI voxel PSF from an mrs_data object.

Usage

get_mrsi_voxel_xy_psf(mrs_data, target_mri, x_pos, y_pos, z_pos)

Arguments

mrs_data

MRS data.

target_mri

optional image data to match the intended volume space.

x_pos

x voxel coordinate.

y_pos

y voxel coordinate.

z_pos

z voxel coordinate.

Value

volume data as a nifti object.


Calculate the partial volume estimates for each voxel in a 2D MRSI dataset.

Description

Localisation is assumed to be perfect in the z direction and determined by the ker input in the x-y direction.

Usage

get_mrsi2d_seg(mrs_data, mri_seg, ker)

Arguments

mrs_data

2D MRSI data with multiple voxels in the x-y dimension.

mri_seg

MRI data with values corresponding to the segmentation class. Must be 1mm isotropic resolution.

ker

MRSI PSF kernel in the x-y direction compatible with the mmand package, eg: mmand::shapeKernel(c(10, 10), type = "box").

Value

a data frame of partial volume estimates and individual segmentation maps.


Return odd numbered dynamic scans starting from 1 (1,3,5...).

Description

Return odd numbered dynamic scans starting from 1 (1,3,5...).

Usage

get_odd_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

dynamic MRS data containing odd numbered scans.


Extract the reference component from an mrs_data object.

Description

Extract the reference component from an mrs_data object.

Usage

get_ref(mrs_data)

Arguments

mrs_data

MRS data.

Value

reference component.


Get the indices of data points lying between two values (end > x > start).

Description

Get the indices of data points lying between two values (end > x > start).

Usage

get_seg_ind(scale, start, end)

Arguments

scale

full list of values.

start

smallest value in the subset.

end

largest value in the subset.

Value

set of indices.


Return the second half of a dynamic series.

Description

Return the second half of a dynamic series.

Usage

get_sh_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

second half of the dynamic series.


Return a single slice from a larger MRSI dataset.

Description

Return a single slice from a larger MRSI dataset.

Usage

get_slice(mrs_data, z_pos)

Arguments

mrs_data

MRSI data.

z_pos

the z index to extract.

Value

MRS data.


Return the spin number for a given nucleus.

Description

Return the spin number for a given nucleus.

Usage

get_spin_num(nucleus)

Arguments

nucleus

nucleus name, eg "1H".

Value

spin number.


Extract a subset of MRS data.

Description

Extract a subset of MRS data.

Usage

get_subset(
  mrs_data,
  x_set = NULL,
  y_set = NULL,
  z_set = NULL,
  dyn_set = NULL,
  coil_set = NULL,
  fd_set = NULL,
  td_set = NULL
)

Arguments

mrs_data

MRS data object.

x_set

x indices to include in the output (default all).

y_set

y indices to include in the output (default all).

z_set

z indices to include in the output (default all).

dyn_set

dynamic indices to include in the output (default all).

coil_set

coil indices to include in the output (default all).

fd_set

frequency domain data indices to include in the output (default all).

td_set

time-domain indices to include in the output (default all).

Value

selected subset of MRS data.


Generate a SVS acquisition volume from an mrs_data object.

Description

Generate a SVS acquisition volume from an mrs_data object.

Usage

get_svs_voi(mrs_data, target_mri)

Arguments

mrs_data

MRS data.

target_mri

optional image data to match the intended volume space.

Value

volume data as a nifti object.


Return the last scans of a dynamic series.

Description

Return the last scans of a dynamic series.

Usage

get_tail_dyns(mrs_data, n = 1)

Arguments

mrs_data

dynamic MRS data.

n

the number of dynamic scans to return.

Value

last scans of a dynamic series.


Return an array of amplitudes derived from fitting the initial points in the time domain and extrapolating back to t=0.

Description

Return an array of amplitudes derived from fitting the initial points in the time domain and extrapolating back to t=0.

Usage

get_td_amp(mrs_data, nstart = 10, nend = 50, method = "poly")

Arguments

mrs_data

MRS data.

nstart

first data point to fit.

nend

last data point to fit.

method

method for measuring the amplitude, one of "poly", spline" or exp".

Value

array of amplitudes.


Print the command to run the TARQUIN command-line program.

Description

Print the command to run the TARQUIN command-line program.

Usage

get_tqn_cmd()

Generate a mol_parameters object for a simple spin system with one resonance.

Description

Generate a mol_parameters object for a simple spin system with one resonance.

Usage

get_uncoupled_mol(
  name,
  chem_shift,
  nucleus,
  scale_factor,
  lw,
  lg,
  full_name = NULL
)

Arguments

name

abbreviated name of the molecule.

chem_shift

chemical shift of the resonance (PPM).

nucleus

nucleus (1H, 31P...).

scale_factor

multiplicative scaling factor. Note, this value can be made complex to adjust the phase of the resonance.

lw

linewidth in Hz.

lg

Lorentz-Gauss lineshape parameter (between 0 and 1).

full_name

long name of the molecule (optional).

Value

mol_parameters object.


Calculate the centre of gravity for an image containing 0 and 1's.

Description

Calculate the centre of gravity for an image containing 0 and 1's.

Usage

get_voi_cog(voi)

Arguments

voi

nifti object.

Value

triplet of x,y,z coordinates.


Return the white matter, gray matter and CSF composition of a volume.

Description

Return the white matter, gray matter and CSF composition of a volume.

Usage

get_voi_seg(voi, mri_seg)

Arguments

voi

volume data as a nifti object.

mri_seg

segmented brain volume as a nifti object.

Value

a vector of partial volumes expressed as percentages.


Return the white matter, gray matter and CSF composition of a volume.

Description

Return the white matter, gray matter and CSF composition of a volume.

Usage

get_voi_seg_psf(psf, mri_seg)

Arguments

psf

volume data as a nifti object.

mri_seg

segmented brain volume as a nifti object.

Value

a vector of partial volumes expressed as percentages.


Return a single voxel from a larger mrs dataset.

Description

Return a single voxel from a larger mrs dataset.

Usage

get_voxel(mrs_data, x_pos = 1, y_pos = 1, z_pos = 1, dyn = 1, coil = 1)

Arguments

mrs_data

MRS data.

x_pos

the x index to plot.

y_pos

the y index to plot.

z_pos

the z index to plot.

dyn

the dynamic index to plot.

coil

the coil element number to plot.

Value

MRS data.


Perform a GLM analysis of dynamic MRS data in the spectral domain.

Description

Perform a GLM analysis of dynamic MRS data in the spectral domain.

Usage

glm_spec(mrs_data, regressor_df, full_output = FALSE)

Arguments

mrs_data

single-voxel dynamics MRS data.

regressor_df

a data frame containing temporal regressors to be applied to each spectral datapoint.

full_output

append mrs_data and regressor_df to the output list.

Value

list of statistical results.


Perform first-level spectral GLM analysis of an fMRS dataset.

Description

Perform first-level spectral GLM analysis of an fMRS dataset.

Usage

glm_spec_fmrs_fl(
  regressor_df,
  analysis_dir = "spant_analysis",
  exclude_labels = NULL,
  labels = NULL,
  xlim = c(4, 0.2),
  vline = c(1.35, 1.28, 2.35, 2.29),
  return_results = FALSE
)

Arguments

regressor_df

a data frame containing temporal regressors to be applied to each spectral datapoint.

analysis_dir

directory containing preprocessed data generated by the preproc_svs_dataset function.

exclude_labels

vector of labels of scans to exclude, eg poor quality data.

labels

labels to describe each data set.

xlim

spectral range to include in the analysis.

vline

vertical lines to add to the plot.

return_results

function will return key outputs, defaults to FALSE.


Perform group-level spectral GLM analysis of an fMRS dataset.

Description

Perform group-level spectral GLM analysis of an fMRS dataset.

Usage

glm_spec_fmrs_group(
  regressor_df,
  analysis_dir = "spant_analysis",
  exclude_labels = NULL,
  labels = NULL
)

Arguments

regressor_df

a data frame containing temporal regressors to be applied to each spectral datapoint.

analysis_dir

directory containing preprocessed data generated by the preproc_svs_dataset function.

exclude_labels

vector of labels of scans to exclude, eg poor quality data.

labels

labels to describe each data set.


Test a group-level spectral GLM linear hypothesis.

Description

Test a group-level spectral GLM linear hypothesis.

Usage

glm_spec_group_linhyp(hmat, analysis_dir = "spant_analysis")

Arguments

hmat

linear hypothesis matrix.

analysis_dir

directory containing preprocessed data generated by the preproc_svs_dataset function.


Grid shift MRSI data in the x/y dimension.

Description

Grid shift MRSI data in the x/y dimension.

Usage

grid_shift_xy(mrs_data, x_shift, y_shift)

Arguments

mrs_data

MRSI data in the spatial domain.

x_shift

shift to apply in the x-direction in units of voxels.

y_shift

shift to apply in the y-direction in units of voxels.

Value

shifted data.


Arrange spectral plots in a grid.

Description

Arrange spectral plots in a grid.

Usage

gridplot(x, ...)

Arguments

x

object for plotting.

...

arguments to be passed to methods.


Arrange spectral plots in a grid.

Description

Arrange spectral plots in a grid.

Usage

## S3 method for class 'mrs_data'
gridplot(
  x,
  rows = NA,
  cols = NA,
  mar = c(0, 0, 0, 0),
  oma = c(3.5, 1, 1, 1),
  bty = "o",
  restore_def_par = TRUE,
  ...
)

Arguments

x

object of class mrs_data.

rows

number of grid rows.

cols

number of grid columns.

mar

option to adjust the plot margins. See ?par.

oma

outer margin area.

bty

option to draw a box around the plot. See ?par.

restore_def_par

restore default plotting par values after the plot has been made.

...

other arguments to pass to the plot method.


HSVD of an mrs_data object.

Description

HSVD method as described in: Barkhuijsen H, de Beer R, van Ormondt D. Improved algorithm for noniterative and timedomain model fitting to exponentially damped magnetic resonance signals. J Magn Reson 1987;73:553-557.

Usage

hsvd(mrs_data, comps = 40, irlba = TRUE, max_damp = 10)

Arguments

mrs_data

mrs_data object to be decomposed.

comps

number of Lorentzian components to use for modelling.

irlba

option to use irlba SVD (logical).

max_damp

maximum allowable damping factor.

Value

basis matrix and signal table.


HSVD based signal filter.

Description

HSVD based signal filter described in: Barkhuijsen H, de Beer R, van Ormondt D. Improved algorithm for noniterative and timedomain model fitting to exponentially damped magnetic resonance signals. J Magn Reson 1987;73:553-557.

Usage

hsvd_filt(
  mrs_data,
  xlim = c(-30, 30),
  comps = 40,
  irlba = TRUE,
  max_damp = 10,
  scale = "hz",
  return_model = FALSE
)

Arguments

mrs_data

MRS data to be filtered.

xlim

frequency range to filter, default units are Hz which can be changed to ppm using the "scale" argument.

comps

number of Lorentzian components to use for modelling.

irlba

option to use irlba SVD (logical).

max_damp

maximum allowable damping factor.

scale

either "hz" or "ppm" to set the frequency units of xlim.

return_model

by default the filtered spectrum is returned. Set return_model to TRUE to return the HSVD model of the data.

Value

filtered data or model depending on the return_model argument.


HSVD of a complex vector.

Description

HSVD method as described in: Barkhuijsen H, de Beer R, van Ormondt D. Improved algorithm for noniterative and timedomain model fitting to exponentially damped magnetic resonance signals. J Magn Reson 1987;73:553-557.

Usage

hsvd_vec(y, fs, comps = 40, irlba = TRUE, max_damp = 0)

Arguments

y

time domain signal to be filtered as a vector.

fs

sampling frequency of y.

comps

number of Lorentzian components to use for modelling.

irlba

option to use irlba SVD (logical).

max_damp

maximum allowable damping factor. Default value of 0 ensures resultant model is damped.

Value

basis matrix and signal table.


Return the frequency scale of an MRS dataset in Hz.

Description

Return the frequency scale of an MRS dataset in Hz.

Usage

hz(mrs_data, fs = NULL, N = NULL)

Arguments

mrs_data

MRS data.

fs

sampling frequency in Hz.

N

number of data points in the spectral dimension.

Value

frequency scale.


Perform an iffshift and ifft on a vector.

Description

Perform an iffshift and ifft on a vector.

Usage

ift_shift(vec_in)

Arguments

vec_in

vector input.

Value

output vector.


Perform an ifft and ifftshift on a matrix with each column replaced by its shifted ifft.

Description

Perform an ifft and ifftshift on a matrix with each column replaced by its shifted ifft.

Usage

ift_shift_mat(mat_in)

Arguments

mat_in

matrix input.

Value

output matrix.


Apply Im operator to an MRS dataset.

Description

Apply Im operator to an MRS dataset.

Usage

## S3 method for class 'mrs_data'
Im(z)

Arguments

z

MRS data.

Value

MRS data following Im operator.


Image plot method for objects of class mrs_data.

Description

Image plot method for objects of class mrs_data.

Usage

## S3 method for class 'mrs_data'
image(
  x,
  xlim = NULL,
  mode = "re",
  col = NULL,
  plot_dim = NULL,
  x_pos = NULL,
  y_pos = NULL,
  z_pos = NULL,
  dyn = 1,
  coil = 1,
  restore_def_par = TRUE,
  y_ticks = NULL,
  hline = NULL,
  hline_lty = 2,
  hline_col = "white",
  vline = NULL,
  vline_lty = 2,
  vline_col = "white",
  legend = FALSE,
  ...
)

Arguments

x

object of class mrs_data.

xlim

the range of values to display on the x-axis, eg xlim = c(4,1).

mode

representation of the complex numbers to be plotted, can be one of: "re", "im", "mod" or "arg".

col

Colour map to use, defaults to viridis.

plot_dim

the dimension to display on the y-axis, can be one of: "dyn", "time_sec", x", "y", "z", "coil" or NULL. If NULL (the default) all spectra are collapsed into the dynamic dimension and displayed.

x_pos

the x index to plot.

y_pos

the y index to plot.

z_pos

the z index to plot.

dyn

the dynamic index to plot.

coil

the coil element number to plot.

restore_def_par

restore default plotting par values after the plot has been made.

y_ticks

a vector of indices specifying where to place additional red tick marks.

hline

add a horizontal line at the specified value.

hline_lty

linetype for the horizontal line.

hline_col

colour for the horizontal line.

vline

add a vertical line at the specified value.

vline_lty

linetype for the vertical line.

vline_col

colour for the vertical line.

legend

add a colour bar to the plot using the imagePlot function from the fields package.

...

other arguments to pass to the plot method.


Transform 2D MRSI data to k-space in the x-y direction.

Description

Transform 2D MRSI data to k-space in the x-y direction.

Usage

img2kspace_xy(mrs_data)

Arguments

mrs_data

2D MRSI data.

Value

k-space data.


Complex rounding function taken from complexplus package to reduce the number of spant dependencies.

Description

Complex rounding function taken from complexplus package to reduce the number of spant dependencies.

Usage

Imzap(x, tol = 1e-06)

Arguments

x

a scalar or vector, real or complex.

tol

a tolerance, 10^-6 by default. Prevents possible numerical problems. Can be set to 0 if desired.


Install the spant command-line interface scripts to a system path.

Description

Install the spant command-line interface scripts to a system path.

Usage

install_cli(path = NULL)

Arguments

path

optional path to install the scripts. Defaults to : "/usr/local/bin".


Integrate a spectral region.

Description

See spec_op function for a more complete set of spectral operations.

Usage

int_spec(mrs_data, xlim = NULL, freq_scale = "ppm", mode = "re")

Arguments

mrs_data

MRS data.

xlim

spectral range to be integrated (defaults to full range).

freq_scale

units of xlim, can be : "ppm", "hz" or "points".

mode

spectral mode, can be : "re", "im", "mod" or "cplx".

Value

an array of integral values.


Interleave the first and second half of a dynamic series.

Description

Interleave the first and second half of a dynamic series.

Usage

interleave_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

interleaved data.


Invert even numbered dynamic scans starting from 1 (2,4,6...).

Description

Invert even numbered dynamic scans starting from 1 (2,4,6...).

Usage

inv_even_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

dynamic MRS data with inverted even numbered scans.


Invert odd numbered dynamic scans starting from 1 (1,3,5...).

Description

Invert odd numbered dynamic scans starting from 1 (1,3,5...).

Usage

inv_odd_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

dynamic MRS data with inverted odd numbered scans.


Check if the chemical shift dimension of an MRS data object is in the frequency domain.

Description

Check if the chemical shift dimension of an MRS data object is in the frequency domain.

Usage

is_fd(mrs_data)

Arguments

mrs_data

MRS data.

Value

logical value.


Check if an object is defined, which is the same as being not NULL.

Description

Check if an object is defined, which is the same as being not NULL.

Usage

is.def(x)

Arguments

x

object to test for being NULL.

Value

logical value.


Transform 2D MRSI data from k-space to image space in the x-y direction.

Description

Transform 2D MRSI data from k-space to image space in the x-y direction.

Usage

kspace2img_xy(mrs_data)

Arguments

mrs_data

2D MRSI data.

Value

MRSI data in image space.


Perform l2 regularisation artefact suppression.

Description

Perform l2 regularisation artefact suppression using the method proposed by Bilgic et al. JMRI 40(1):181-91 2014.

Usage

l2_reg(
  mrs_data,
  thresh = 0.05,
  b = 1e-11,
  A = NA,
  xlim = NA,
  thresh_xlim = NULL,
  A_append = NULL,
  ret_norms = FALSE
)

Arguments

mrs_data

input data for artefact suppression.

thresh

threshold parameter to extract lipid signals from mrs_data based on the spectral integration of the thresh_xlim region in magnitude mode.

b

regularisation parameter.

A

set of spectra containing the artefact basis signals. The thresh parameter is ignored when A is specified.

xlim

spectral limits in ppm to restrict the reconstruction range. Defaults to the full spectral width.

thresh_xlim

spectral limits in ppm to integrate for the threshold map.

A_append

additional spectra to append to the A basis.

ret_norms

return the residual norm and solution norms.

Value

l2 reconstructed mrs_data object.


Apply line-broadening (apodisation) to MRS data or basis object.

Description

Apply line-broadening (apodisation) to MRS data or basis object.

Usage

lb(x, lb, lg = 1)

## S3 method for class 'list'
lb(x, lb, lg = 1)

## S3 method for class 'mrs_data'
lb(x, lb, lg = 1)

## S3 method for class 'basis_set'
lb(x, lb, lg = 1)

Arguments

x

input mrs_data or basis_set object.

lb

amount of line-broadening in Hz.

lg

Lorentz-Gauss lineshape parameter (between 0 and 1).

Value

line-broadened data.


Correct linear frequency drift.

Description

Correct linear frequency drift.

Usage

lofdc(
  mrs_data,
  max_hz_s = 0.1,
  tr = NULL,
  ret_corr_only = TRUE,
  outlier_thresh = 3,
  xlim = c(4, 0.5),
  order = 1
)

Arguments

mrs_data

MRS data to be corrected.

max_hz_s

the maximum drift rate to search over.

tr

mrs_data repetition time.

ret_corr_only

return the corrected mrs_data object only.

outlier_thresh

threshold to remove outliers.

xlim

spectral width (in ppm) to evaluate outliers.

order

correction order.

Value

drift corrected mrs_data object.


Covert a linewidth in Hz to an equivalent alpha value in the time-domain ie: x * exp(-t * alpha).

Description

Covert a linewidth in Hz to an equivalent alpha value in the time-domain ie: x * exp(-t * alpha).

Usage

lw2alpha(lw)

Arguments

lw

linewidth in Hz.

Value

beta damping value.


Covert a linewidth in Hz to an equivalent beta value in the time-domain ie: x * exp(-t * t * beta).

Description

Covert a linewidth in Hz to an equivalent beta value in the time-domain ie: x * exp(-t * t * beta).

Usage

lw2beta(lw)

Arguments

lw

linewidth in Hz.

Value

beta damping value.


Make a basis-set object from a directory containing LCModel formatted RAW files.

Description

Make a basis-set object from a directory containing LCModel formatted RAW files.

Usage

make_basis_from_raw(dir_path, ft, fs, ref)

Arguments

dir_path

path to the directory containing LCModel RAW files. One file per signal.

ft

transmitter frequency in Hz.

fs

sampling frequency in Hz.

ref

reference value for ppm scale.

Value

a basis-set object.


Mask an MRS dataset in the dynamic dimension.

Description

Mask an MRS dataset in the dynamic dimension.

Usage

mask_dyns(mrs_data, mask)

Arguments

mrs_data

MRS data object.

mask

vector of boolean values specifying the dynamics to mask, where a value of TRUE indicates the spectrum should be removed.

Value

masked dataset.


Mask fit result spectra depending on a vector of bool values.

Description

Mask fit result spectra depending on a vector of bool values.

Usage

mask_fit_res(fit_result, mask_vec, amps_only = FALSE)

Arguments

fit_result

fit result object to be masked.

mask_vec

a Boolean vector with the same number of rows as there are rows in the results table.

amps_only

only mask the amplitude and associated error estimate columns.

Value

a masked fit result object.


Mask an MRSI dataset in the x-y direction

Description

Mask an MRSI dataset in the x-y direction

Usage

mask_xy(mrs_data, x_dim, y_dim)

Arguments

mrs_data

MRS data object.

x_dim

x dimension output length.

y_dim

y dimension output length.

Value

masked MRS data.


Mask the four corners of an MRSI dataset in the x-y plane.

Description

Mask the four corners of an MRSI dataset in the x-y plane.

Usage

mask_xy_corners(mrs_data)

Arguments

mrs_data

MRS data object.

Value

masked MRS data.


Mask the voxels outside an elliptical region spanning the MRSI dataset in the x-y plane.

Description

Mask the voxels outside an elliptical region spanning the MRSI dataset in the x-y plane.

Usage

mask_xy_ellipse(mrs_data)

Arguments

mrs_data

MRS data object.

Value

masked MRS data.


Mask a 2D MRSI dataset in the x-y dimension.

Description

Mask a 2D MRSI dataset in the x-y dimension.

Usage

mask_xy_mat(mrs_data, mask, value = NA)

Arguments

mrs_data

MRS data object.

mask

matrix of boolean values specifying the voxels to mask, where a value of TRUE indicates the voxel should be removed.

value

the value to set masked data to (usually NA or 0).

Value

masked dataset.


Convert a matrix (with spectral points in the column dimension and dynamics in the row dimensions) into a mrs_data object.

Description

Convert a matrix (with spectral points in the column dimension and dynamics in the row dimensions) into a mrs_data object.

Usage

mat2mrs_data(
  mat,
  mrs_data = NULL,
  fs = NULL,
  ft = NULL,
  ref = NULL,
  nuc = NULL,
  fd = FALSE
)

Arguments

mat

data matrix.

mrs_data

example data to copy acquisition parameters from.

fs

sampling frequency in Hz.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

nuc

resonant nucleus.

fd

flag to indicate if the matrix is in the frequency domain (logical).

Value

mrs_data object.


Matrix exponential function taken from complexplus package to reduce the number of spant dependencies.

Description

Matrix exponential function taken from complexplus package to reduce the number of spant dependencies.

Usage

matexp(x)

Arguments

x

a square complex matrix.

Value

the matrix exponential of x.


Apply the max operator to an MRS dataset.

Description

Apply the max operator to an MRS dataset.

Usage

max_mrs(mrs_data)

Arguments

mrs_data

MRS data.

Value

MRS data following max operator.


Apply the max operator to an interpolated MRS dataset.

Description

Apply the max operator to an interpolated MRS dataset.

Usage

max_mrs_interp(mrs_data, interp_f = 4)

Arguments

mrs_data

MRS data.

interp_f

interpolation factor.

Value

Array of maximum values (real only).


Calculate the mean of adjacent dynamic scans.

Description

Calculate the mean of adjacent dynamic scans.

Usage

mean_dyn_blocks(mrs_data, block_size)

Arguments

mrs_data

dynamic MRS data.

block_size

number of adjacent dynamics scans to average over.

Value

dynamic data averaged in blocks.


Calculate the pairwise means across a dynamic data set.

Description

Calculate the pairwise means across a dynamic data set.

Usage

mean_dyn_pairs(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

mean dynamic data of adjacent dynamic pairs.


Calculate the mean dynamic data.

Description

Calculate the mean dynamic data.

Usage

mean_dyns(mrs_data, subset = NULL)

Arguments

mrs_data

dynamic MRS data.

subset

vector containing indices to the dynamic scans to be averaged.

Value

mean dynamic data.


Return the mean of a list of mrs_data objects.

Description

Return the mean of a list of mrs_data objects.

Usage

mean_mrs_list(mrs_list)

Arguments

mrs_list

list of mrs_data objects.

Value

mean mrs_data object.


Calculate the mean of adjacent blocks in a vector.

Description

Calculate the mean of adjacent blocks in a vector.

Usage

mean_vec_blocks(x, block_size)

Arguments

x

input vector.

block_size

number of adjacent elements to average over.

Value

vector data averaged in blocks.


Calculate the mean spectrum from an mrs_data object.

Description

Calculate the mean spectrum from an mrs_data object.

Usage

## S3 method for class 'list'
mean(x, ...)

Arguments

x

object of class mrs_data.

...

other arguments to pass to the colMeans function.

Value

mean mrs_data object.


Calculate the mean spectrum from an mrs_data object.

Description

Calculate the mean spectrum from an mrs_data object.

Usage

## S3 method for class 'mrs_data'
mean(x, ...)

Arguments

x

object of class mrs_data.

...

other arguments to pass to the colMeans function.

Value

mean mrs_data object.


Calculate the median dynamic data.

Description

Calculate the median dynamic data.

Usage

median_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

median dynamic data.


Apply the Modulus operator to the time-domain MRS signal.

Description

Apply the Modulus operator to the time-domain MRS signal.

Usage

mod_td(mrs_data)

Arguments

mrs_data

MRS data input.

Value

time-domain modulus of input.


Apply Mod operator to an MRS dataset.

Description

Apply Mod operator to an MRS dataset.

Usage

## S3 method for class 'mrs_data'
Mod(z)

Arguments

z

MRS data.

Value

MRS data following Mod operator.


Convert an mrs_data object to basis object - where basis signals are spread across the dynamic dimension in the MRS data.

Description

Convert an mrs_data object to basis object - where basis signals are spread across the dynamic dimension in the MRS data.

Usage

mrs_data2basis(mrs_data, names)

Arguments

mrs_data

mrs_data object with basis signals spread across the dynamic dimension.

names

list of names corresponding to basis signals.

Value

basis set object.


Create a BIDS file structure from a vector of MRS data paths or list of mrs_data objects.

Description

Create a BIDS file structure from a vector of MRS data paths or list of mrs_data objects.

Usage

mrs_data2bids(
  mrs_data,
  output_dir,
  suffix = NULL,
  sub = NULL,
  ses = NULL,
  task = NULL,
  acq = NULL,
  nuc = NULL,
  voi = NULL,
  rec = NULL,
  run = NULL,
  echo = NULL,
  inv = NULL,
  skip_existing = TRUE
)

Arguments

mrs_data

vector of MRS data paths or list of mrs_data objects.

output_dir

the base directory to create the BIDS structure.

suffix

optional vector of file suffixes. Default behaviour is to automatically determine these from the input data, however it is recommended that they are specified to allow more efficient skipping of existing data.

sub

optional vector of subject labels. If not specified, these will be automatically generated as a series of increasing zero-padded integer values corresponding to the mrs_data input indices.

ses

optional vector of session labels.

task

optional vector of task labels.

acq

optional vector of acquisition labels.

nuc

optional vector of nucleus labels.

voi

optional vector of volume of interest labels.

rec

optional vector of reconstruction labels.

run

optional vector of run indices.

echo

optional vector of echo time indices.

inv

optional vector of inversion indices.

skip_existing

skip any data files that have already been converted. Defaults to TRUE, set to FALSE to force an overwrite of any existing data files.


Convert mrs_data object to a matrix, with spectral points in the column dimension and dynamics in the row dimension.

Description

Convert mrs_data object to a matrix, with spectral points in the column dimension and dynamics in the row dimension.

Usage

mrs_data2mat(mrs_data, collapse = TRUE)

Arguments

mrs_data

MRS data object or list of MRS data objects.

collapse

collapse all other dimensions along the dynamic dimension, eg a 16x16 MRSI grid would be first collapsed across 256 dynamic scans.

Value

MRS data matrix.


Convert mrs_data object to a matrix, with spectral points in the column dimension and dynamics in the row dimension.

Description

Convert mrs_data object to a matrix, with spectral points in the column dimension and dynamics in the row dimension.

Usage

mrs_data2spec_mat(mrs_data, collapse = TRUE)

Arguments

mrs_data

MRS data object or list of MRS data objects.

collapse

collapse all other dimensions along the dynamic dimension, eg a 16x16 MRSI grid would be first collapsed across 256 dynamic scans.

Value

MRS data matrix.


Convert mrs_data object to a vector.

Description

Convert mrs_data object to a vector.

Usage

mrs_data2vec(mrs_data, dyn = 1, x_pos = 1, y_pos = 1, z_pos = 1, coil = 1)

Arguments

mrs_data

MRS data object.

dyn

dynamic index.

x_pos

x index.

y_pos

y index.

z_pos

z index.

coil

coil element index.

Value

MRS data vector.


Perform a fftshift on a matrix, with each column replaced by its shifted result.

Description

Perform a fftshift on a matrix, with each column replaced by its shifted result.

Usage

mvfftshift(x)

Arguments

x

matrix input.

Value

output matrix.


Perform an ifftshift on a matrix, with each column replaced by its shifted result.

Description

Perform an ifftshift on a matrix, with each column replaced by its shifted result.

Usage

mvifftshift(x)

Arguments

x

matrix input.

Value

output matrix.


Print fit coordinates from a single index.

Description

Print fit coordinates from a single index.

Usage

n2coord(n, fit_res)

Arguments

n

fit index.

fit_res

fit_result object.


Return the total number of coil elements in an MRS dataset.

Description

Return the total number of coil elements in an MRS dataset.

Usage

Ncoils(mrs_data)

Arguments

mrs_data

MRS data.


Return the total number of dynamic scans in an MRS dataset.

Description

Return the total number of dynamic scans in an MRS dataset.

Usage

Ndyns(mrs_data)

Arguments

mrs_data

MRS data.


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

Description

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

Usage

nifti_flip_lr(x)

Arguments

x

nifti object to be processed.

Value

nifti object with reversed x data direction.


Return the number of data points in an MRS dataset.

Description

Return the number of data points in an MRS dataset.

Usage

Npts(mrs_data)

Arguments

mrs_data

MRS data.

Value

number of data points.


Return the total number of spectra in an MRS dataset.

Description

Return the total number of spectra in an MRS dataset.

Usage

Nspec(mrs_data)

Arguments

mrs_data

MRS data.


Return the total number of acquired transients for an MRS dataset.

Description

Return the total number of acquired transients for an MRS dataset.

Usage

Ntrans(mrs_data)

Arguments

mrs_data

MRS data.


Return the total number of x locations in an MRS dataset.

Description

Return the total number of x locations in an MRS dataset.

Usage

Nx(mrs_data)

Arguments

mrs_data

MRS data.


Return the total number of y locations in an MRS dataset.

Description

Return the total number of y locations in an MRS dataset.

Usage

Ny(mrs_data)

Arguments

mrs_data

MRS data.


Return the total number of z locations in an MRS dataset.

Description

Return the total number of z locations in an MRS dataset.

Usage

Nz(mrs_data)

Arguments

mrs_data

MRS data.


Export a one-page pdf of a single fit result

Description

Export a one-page pdf of a single fit result

Usage

one_page_pdf(fit_res, pdf_out_path, title = NULL)

Arguments

fit_res

fit_result object.

pdf_out_path

path to the exported pdf file.

title

output title.


Display an orthographic projection plot of a nifti object.

Description

Display an orthographic projection plot of a nifti object.

Usage

ortho3(
  underlay,
  overlay = NULL,
  xyz = NULL,
  zlim = NULL,
  zlim_ol = NULL,
  alpha = 0.7,
  col_ol = viridisLite::viridis(64),
  orient_lab = TRUE,
  rescale = 1,
  crosshairs = TRUE,
  ch_lwd = 1,
  colourbar = TRUE,
  bg = "black",
  mar = c(0, 0, 0, 0),
  smallplot = c(0.63, 0.65, 0.07, 0.42),
  legend_axis_cex = 0.75
)

Arguments

underlay

underlay image to be shown in grayscale.

overlay

optional overlay image.

xyz

x, y, z slice coordinates to display.

zlim

underlay intensity limits.

zlim_ol

overlay intensity limits.

alpha

transparency of overlay.

col_ol

colour palette of overlay.

orient_lab

display orientation labels (default TRUE).

rescale

rescale factor for the underlay and overlay images.

crosshairs

display the crosshairs (default TRUE).

ch_lwd

crosshair linewidth.

colourbar

display a colourbar for the overlay (default TRUE).

bg

plot background colour.

mar

plot margins.

smallplot

smallplot option for positioning the colourbar.

legend_axis_cex

font expansion factor for the legend axis text.


Display an interactive orthographic projection plot of a nifti object.

Description

Display an interactive orthographic projection plot of a nifti object.

Usage

ortho3_inter(
  underlay,
  overlay = NULL,
  xyz = NULL,
  zlim = NULL,
  zlim_ol = NULL,
  alpha = 0.7,
  ...
)

Arguments

underlay

underlay image to be shown in grayscale.

overlay

optional overlay image.

xyz

x, y, z slice coordinates to display.

zlim

underlay intensity limits.

zlim_ol

overlay intensity limits.

alpha

transparency of overlay.

...

other options to be passed to the ortho3 function.


Search for the highest peak in a spectral region and return the frequency, height and FWHM.

Description

Search for the highest peak in a spectral region and return the frequency, height and FWHM.

Usage

peak_info(
  mrs_data,
  xlim = c(4, 0.5),
  interp_f = 4,
  scale = "ppm",
  mode = "real"
)

Arguments

mrs_data

an object of class mrs_data.

xlim

frequency range (default units of PPM) to search for the highest peak.

interp_f

interpolation factor, defaults to 4x.

scale

the units to use for the frequency scale, can be one of: "ppm", "hz" or "points".

mode

spectral mode, can be : "real", "imag" or "mod".

Value

list of arrays containing the highest peak frequency, height and FWHM in units of PPM and Hz.


Papoulis-Gerchberg (PG) algorithm method for k-space extrapolation.

Description

PG method as described in: Haupt CI, Schuff N, Weiner MW, Maudsley AA. Removal of lipid artifacts in 1H spectroscopic imaging by data extrapolation. Magn Reson Med. 1996 May;35(5):678-87. Extrapolation is performed to expand k-space coverage by a factor of 2, with the aim to reduce Gibbs ringing.

Usage

pg_extrap_xy(
  mrs_data,
  img_mask = NULL,
  kspace_mask = NULL,
  intensity_thresh = 0.15,
  iters = 50
)

Arguments

mrs_data

MRS data object.

img_mask

a boolean matrix of voxels with strong signals to be extrapolated. Must be twice the dimensions of the input data.

kspace_mask

a boolean matrix of kspace points that have been sampled. Typically a circle for MRSI, but defaults to the full rectangular area of k-space covered by the input data. Must match the x-y dimensions of the input data.

intensity_thresh

used to define img_mask based on the strength of the signal in each voxel. Defaults to intensities greater than 15% of the maximum. Ignored if img_mask is specified as argument.

iters

number of iterations to perform.

Value

extrapolated mrs_data object.


Apply phasing parameters to MRS data.

Description

Apply phasing parameters to MRS data.

Usage

phase(mrs_data, zero_order, first_order = 0)

Arguments

mrs_data

MRS data.

zero_order

zero'th order phase term in degrees.

first_order

first order (frequency dependent) phase term in ms.

Value

MRS data with applied phase parameters.


Corrected zero order phase and chemical shift offset in 1H MRS data from the brain.

Description

Corrected zero order phase and chemical shift offset in 1H MRS data from the brain.

Usage

phase_ref_1h_brain(mrs_data, mean_ref = FALSE, ret_corr_only = TRUE)

Arguments

mrs_data

MRS data to be corrected.

mean_ref

apply the phase and offset of the mean spectrum to all others. Default is FALSE.

ret_corr_only

return the corrected data only.

Value

corrected MRS data.


Convenience function to plot a baseline estimate with the original data.

Description

Convenience function to plot a baseline estimate with the original data.

Usage

plot_bc(orig_data, bc_data, ...)

Arguments

orig_data

the original data.

bc_data

the baseline corrected data.

...

other arguments to pass to the stackplot function.


Plot regressors as an image.

Description

Plot regressors as an image.

Usage

plot_reg(regressor_df)

Arguments

regressor_df

input regressor data frame.


Plot a 2D slice from an MRSI fit result object.

Description

Plot a 2D slice from an MRSI fit result object.

Usage

plot_slice_fit(
  fit_res,
  map,
  map_denom = NULL,
  slice = 1,
  zlim = NULL,
  interp = 1
)

Arguments

fit_res

fit_result object.

map

fit result values to display as a colour map. Can be specified as a character string or array of numeric values. Defaults to "tNAA".

map_denom

fit result values to divide the map argument by. Can be specified as a character string (eg "tCr") or array of numeric values.

slice

slice to plot in the z direction.

zlim

range of values to plot.

interp

interpolation factor.


Plot a 2D slice from an MRSI fit result object.

Description

Plot a 2D slice from an MRSI fit result object.

Usage

plot_slice_fit_inter(
  fit_res,
  map = NULL,
  map_denom = NULL,
  slice = 1,
  zlim = NULL,
  interp = 1,
  xlim = NULL
)

Arguments

fit_res

fit_result object.

map

fit result values to display as a colour map. Can be specified as a character string or array of numeric values. Defaults to "tNAA".

map_denom

fit result values to divide the map argument by. Can be specified as a character string (eg "tCr") or array of numeric values.

slice

slice to plot in the z direction.

zlim

range of values to plot.

interp

interpolation factor.

xlim

spectral plot limits for the x axis.


Plot a slice from a 7 dimensional array.

Description

Plot a slice from a 7 dimensional array.

Usage

plot_slice_map(
  data,
  zlim = NULL,
  mask_map = NULL,
  mask_cutoff = 20,
  interp = 1,
  slice = 1,
  dyn = 1,
  coil = 1,
  ref = 1,
  denom = NULL,
  horizontal = FALSE
)

Arguments

data

7d array of values to be plotted.

zlim

smallest and largest values to be plotted.

mask_map

matching map with logical values to indicate if the corresponding values should be plotted.

mask_cutoff

minimum values to plot (as a percentage of the maximum).

interp

map interpolation factor.

slice

the slice index to plot.

dyn

the dynamic index to plot.

coil

the coil element number to plot.

ref

reference index to plot.

denom

map to use as a denominator.

horizontal

display the colourbar horizontally (logical).


Plot an interactive slice map from a data array where voxels can be selected to display a corresponding spectrum.

Description

Plot an interactive slice map from a data array where voxels can be selected to display a corresponding spectrum.

Usage

plot_slice_map_inter(
  mrs_data,
  map = NULL,
  xlim = NULL,
  slice = 1,
  zlim = NULL,
  mask_map = NULL,
  denom = NULL,
  mask_cutoff = 20,
  interp = 1,
  mode = "re",
  y_scale = FALSE,
  ylim = NULL,
  coil = 1,
  fd = TRUE
)

Arguments

mrs_data

spectral data.

map

array of values to be plotted, defaults to the integration of the modulus of the full spectral width.

xlim

spectral region to plot.

slice

the slice index to plot.

zlim

smallest and largest values to be plotted.

mask_map

matching map with logical values to indicate if the corresponding values should be plotted.

denom

map to use as a denominator.

mask_cutoff

minimum values to plot (as a percentage of the maximum).

interp

map interpolation factor.

mode

representation of the complex spectrum to be plotted, can be one of: "re", "im", "mod" or "arg".

y_scale

option to display the y-axis values (logical).

ylim

intensity range to plot.

coil

coil element to plot.

fd

display data in the frequency-domain (default), or time-domain (logical).


Plot the spectral standard deviation.

Description

Plot the spectral standard deviation.

Usage

plot_spec_sd(mrs_data, xlim = NULL, scale_sd = 1.96, ...)

Arguments

mrs_data

MRS data to be plotted.

xlim

plotting limits in ppm.

scale_sd

scaling factor for the standard deviation trace.

...

other arguments passed to the stackplot function.


Plot a volume as an image overlay.

Description

Plot a volume as an image overlay.

Usage

plot_voi_overlay(mri, voi, export_path = NULL, zlim = NULL, ...)

Arguments

mri

image data as a nifti object or path to data file.

voi

volume data as a nifti object or path to data file.

export_path

optional path to save the image in png format.

zlim

underlay intensity limits.

...

additional arguments to the ortho3 function.


Plot a volume as an overlay on a segmented brain volume.

Description

Plot a volume as an overlay on a segmented brain volume.

Usage

plot_voi_overlay_seg(mri_seg, voi, export_path = NULL, ...)

Arguments

mri_seg

segmented brain volume as a nifti object.

voi

volume data as a nifti object.

export_path

optional path to save the image in png format.

...

additional arguments to the ortho3 function.


Plot the fitting results of an object of class fit_result.

Description

Plot the fitting results of an object of class fit_result.

Usage

## S3 method for class 'fit_result'
plot(
  x,
  dyn = 1,
  x_pos = 1,
  y_pos = 1,
  z_pos = 1,
  coil = 1,
  xlim = NULL,
  data_only = FALSE,
  label = NULL,
  plot_sigs = NULL,
  n = NULL,
  sub_bl = FALSE,
  mar = NULL,
  restore_def_par = TRUE,
  ylim = NULL,
  y_scale = FALSE,
  show_grid = TRUE,
  grid_nx = NULL,
  grid_ny = NA,
  invert_fit = FALSE,
  ...
)

Arguments

x

fit_result object.

dyn

the dynamic index to plot.

x_pos

the x index to plot.

y_pos

the y index to plot.

z_pos

the z index to plot.

coil

the coil element number to plot.

xlim

the range of values to display on the x-axis, eg xlim = c(4,1).

data_only

display only the processed data (logical).

label

character string to add to the top left of the plot window.

plot_sigs

a character vector of signal names to add to the plot.

n

single index element to plot (overrides other indices when given).

sub_bl

subtract the baseline from the data and fit (logical).

mar

option to adjust the plot margins. See ?par.

restore_def_par

restore default plotting par values after the plot has been made.

ylim

range of values to display on the y-axis, eg ylim = c(0,10).

y_scale

option to display the y-axis values (logical).

show_grid

plot gridlines behind the data (logical). Defaults to TRUE.

grid_nx

number of cells of the grid in x and y direction. When NULL the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction.

grid_ny

as above.

invert_fit

show the fit result "upside-down"/

...

further arguments to plot method.


Plotting method for objects of class mrs_data.

Description

Plotting method for objects of class mrs_data.

Usage

## S3 method for class 'mrs_data'
plot(
  x,
  dyn = 1,
  x_pos = 1,
  y_pos = 1,
  z_pos = 1,
  coil = 1,
  fd = TRUE,
  x_units = NULL,
  xlim = NULL,
  y_scale = FALSE,
  x_ax = TRUE,
  mode = "re",
  lwd = NULL,
  bty = NULL,
  label = "",
  restore_def_par = TRUE,
  mar = NULL,
  xaxis_lab = NULL,
  yaxis_lab = NULL,
  xat = NULL,
  xlabs = TRUE,
  yat = NULL,
  ylabs = TRUE,
  show_grid = TRUE,
  grid_nx = NULL,
  grid_ny = NA,
  col = NULL,
  alpha = NULL,
  bl_lty = NULL,
  hline = NULL,
  hline_lty = 2,
  hline_col = "red",
  vline = NULL,
  vline_lty = 2,
  vline_col = "red",
  ...
)

Arguments

x

object of class mrs_data.

dyn

the dynamic index to plot.

x_pos

the x index to plot.

y_pos

the y index to plot.

z_pos

the z index to plot.

coil

the coil element number to plot.

fd

display data in the frequency-domain (default), or time-domain (logical).

x_units

the units to use for the x-axis, can be one of: "ppm", "hz", "points" or "seconds".

xlim

the range of values to display on the x-axis, eg xlim = c(4,1).

y_scale

option to display the y-axis values (logical).

x_ax

option to display the x-axis values (logical).

mode

representation of the complex numbers to be plotted, can be one of: "re", "im", "mod" or "arg".

lwd

plot linewidth.

bty

option to draw a box around the plot. See ?par.

label

character string to add to the top left of the plot window.

restore_def_par

restore default plotting par values after the plot has been made.

mar

option to adjust the plot margins. See ?par.

xaxis_lab

x-axis label.

yaxis_lab

y-axis label.

xat

x-axis tick label values.

xlabs

x-axis tick labels.

yat

y-axis tick label values.

ylabs

y-axis tick labels.

show_grid

plot gridlines behind the data (logical). Defaults to TRUE.

grid_nx

number of cells of the grid in x and y direction. When NULL the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction.

grid_ny

as above.

col

set the line colour, eg col = rgb(0.5, 0.5, 0.5).

alpha

set the line transparency, eg alpha = 0.5 is 50% transparency. Overrides any transparency levels set by col.

bl_lty

linetype for the y = 0 baseline trace. A default value NULL results in no baseline being plotted.

hline

add a horizontal line at the specified value.

hline_lty

linetype for the horizontal line.

hline_col

colour for the horizontal line.

vline

add a vertical line at the specified value.

vline_lty

linetype for the vertical line.

vline_col

colour for the vertical line.

...

other arguments to pass to the plot method.


Return the ppm scale of an MRS dataset or fit result.

Description

Return the ppm scale of an MRS dataset or fit result.

Usage

ppm(x, ft = NULL, ref = NULL, fs = NULL, N = NULL)

## S3 method for class 'mrs_data'
ppm(x, ft = NULL, ref = NULL, fs = NULL, N = NULL)

## S3 method for class 'fit_result'
ppm(x, ft = NULL, ref = NULL, fs = NULL, N = NULL)

Arguments

x

MRS dataset of fit result.

ft

transmitter frequency in Hz, does not apply when the object is a fit result.

ref

reference value for ppm scale, does not apply when the object is a fit result.

fs

sampling frequency in Hz, does not apply when the object is a fit result.

N

number of data points in the spectral dimension, does not apply when the object is a fit result.

Value

ppm scale.


Save function results to file and load on subsequent calls to avoid repeat computation.

Description

Save function results to file and load on subsequent calls to avoid repeat computation.

Usage

precomp(file, fun, ...)

Arguments

file

file name to write the results.

fun

function to run.

...

arguments to be passed to fun.


Preprocess and perform quality assessment of a single SVS data set.

Description

Preprocess and perform quality assessment of a single SVS data set.

Usage

preproc_svs(path, label = NULL, output_dir = NULL, ref_inds = NULL)

Arguments

path

path to the fMRS data file or IMA directory.

label

a label to describe the data set.

output_dir

output directory.

ref_inds

a vector of 1-based indices for any water reference dynamic scans.


Preprocess and perform quality assessment of one or more SVS data sets.

Description

Preprocess and perform quality assessment of one or more SVS data sets.

Usage

preproc_svs_dataset(
  paths,
  labels = NULL,
  output_dir = "spant_analysis",
  exclude_labels = NULL,
  overwrite = FALSE,
  ref_inds = NULL,
  return_results = FALSE
)

Arguments

paths

paths to the fMRS data file or IMA directory.

labels

labels to describe each data set.

output_dir

output directory.

exclude_labels

vector of labels of scans to exclude, eg poor quality data.

overwrite

overwrite saved results, defaults to FALSE.

ref_inds

a vector of 1-based indices for any water reference dynamic scans.

return_results

function will return key outputs, defaults to FALSE.


Print a summary of an object of class fit_result.

Description

Print a summary of an object of class fit_result.

Usage

## S3 method for class 'fit_result'
print(x, ...)

Arguments

x

fit_result object.

...

further arguments.


Print a summary of mrs_data parameters.

Description

Print a summary of mrs_data parameters.

Usage

## S3 method for class 'mrs_data'
print(x, full = FALSE, ...)

Arguments

x

mrs_data object.

full

print all parameters (default FALSE).

...

further arguments.


Get the quantum coherence matrix for a spin system.

Description

Get the quantum coherence matrix for a spin system.

Usage

qn_states(sys)

Arguments

sys

spin system object.

Value

quantum coherence number matrix.


Robust Alignment to a Target Spectrum (RATS).

Description

Robust Alignment to a Target Spectrum (RATS).

Usage

rats(
  mrs_data,
  ref = NULL,
  xlim = c(4, 0.5),
  max_shift = 20,
  p_deg = 2,
  sp_N = 2,
  sp_deg = 3,
  max_t = 0.2,
  basis_type = "poly",
  rescale_output = TRUE,
  phase_corr = TRUE,
  ret_corr_only = TRUE,
  zero_freq_shift_t0 = FALSE,
  remove_freq_outliers = FALSE,
  freq_outlier_thresh = 3,
  remove_phase_outliers = FALSE,
  phase_outlier_thresh = 3,
  remove_amp_outliers = FALSE,
  amp_outlier_thresh = 3
)

Arguments

mrs_data

MRS data to be corrected.

ref

optional MRS data to use as a reference, the mean of all dynamics is used if this argument is not supplied.

xlim

optional frequency range to perform optimisation, set to NULL to use the full range.

max_shift

maximum allowable frequency shift in Hz.

p_deg

polynomial degree used for baseline modelling. Negative values disable baseline modelling.

sp_N

number of spline functions, note the true number will be sp_N + sp_deg.

sp_deg

degree of spline functions.

max_t

truncate the FID when longer than max_t to reduce time taken, set to NULL to use the entire FID.

basis_type

may be one of "poly" or "spline".

rescale_output

rescale the bl_matched_spec and bl output to improve consistency between dynamic scans.

phase_corr

apply phase correction (in addition to frequency). TRUE by default.

ret_corr_only

return the corrected mrs_data object only.

zero_freq_shift_t0

perform a linear fit to the frequency shifts and set the (linearly modeled) shift to be 0 Hz for the first dynamic scan.

remove_freq_outliers

remove dynamics based on their frequency shift.

freq_outlier_thresh

threshold to remove frequency outliers.

remove_phase_outliers

remove dynamics based on their phase shift.

phase_outlier_thresh

threshold to remove phase outliers.

remove_amp_outliers

remove dynamics based on their amplitude change.

amp_outlier_thresh

threshold to remove amplitude outliers.

Value

a list containing the corrected data; phase and shift values in units of degrees and Hz respectively.


Apply a weighting to the FID to enhance spectral resolution.

Description

Apply a weighting to the FID to enhance spectral resolution.

Usage

re_weighting(mrs_data, re, alpha)

Arguments

mrs_data

data to be enhanced.

re

resolution enhancement factor (rising exponential factor).

alpha

alpha factor (Gaussian decay)

Value

resolution enhanced mrs_data.


Apply Re operator to an MRS dataset.

Description

Apply Re operator to an MRS dataset.

Usage

## S3 method for class 'mrs_data'
Re(z)

Arguments

z

MRS data.

Value

MRS data following Re operator.


Read a basis file in LCModel .basis format.

Description

Read a basis file in LCModel .basis format.

Usage

read_basis(basis_file, ref = def_ref(), sort_basis = TRUE)

Arguments

basis_file

path to basis file.

ref

assumed ppm reference value.

sort_basis

sort the basis set based on signal names.

Value

basis object.


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.

Description

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.

Usage

read_ima_coil_dir(dir, extra = NULL, verbose = FALSE)

Arguments

dir

data directory path.

extra

an optional data frame to provide additional variables for use in subsequent analysis steps, eg id or grouping variables.

verbose

output extra information to the console.

Value

mrs_data object.


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.

Description

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.

Usage

read_ima_dyn_dir(dir, extra = NULL, verbose = FALSE)

Arguments

dir

data directory path.

extra

an optional data frame to provide additional variables for use in subsequent analysis steps, eg id or grouping variables.

verbose

output extra information to the console.

Value

mrs_data object.


Read an LCModel formatted coord file containing fit information.

Description

Read an LCModel formatted coord file containing fit information.

Usage

read_lcm_coord(coord_f)

Arguments

coord_f

path to the coord file.

Value

list containing a table of fit point and results structure containing signal amplitudes, errors and fitting diagnostics.


Read MRS data from the filesystem.

Description

Read MRS data from the filesystem.

Usage

read_mrs(
  path,
  format = NULL,
  ft = NULL,
  fs = NULL,
  ref = NULL,
  n_ref_scans = NULL,
  full_fid = FALSE,
  omit_svs_ref_scans = TRUE,
  verbose = FALSE,
  extra = NULL,
  fid_filt_dist = NULL
)

Arguments

path

file name or directory containing the MRS data.

format

string describing the data format. Must be one of the following : "spar_sdat", "rda", "dicom", "twix", "pfile", "list_data", "paravis", "dpt", "lcm_raw", "rds", "nifti", "varian", "jmrui_txt". If not specified, the format will be guessed from the filename extension, or will be assumed to be a Siemens ima dynamic data if the path is a directory.

ft

transmitter frequency in Hz (required for list_data format).

fs

sampling frequency in Hz (required for list_data format).

ref

reference value for ppm scale (required for list_data format).

n_ref_scans

override the number of water reference scans detected in the file header (GE p-file only).

full_fid

export all data points, including those before the start of the FID (default = FALSE), TWIX format only.

omit_svs_ref_scans

remove any reference scans sometimes saved in SVS twix data (default = TRUE).

verbose

print data file information (default = FALSE).

extra

an optional data frame to provide additional variables for use in subsequent analysis steps, eg id or grouping variables.

fid_filt_dist

indicate if the data has a distorted FID due to a brick-wall filter being used to downsample the data. Default is to auto detect this from the data, but TRUE or FALSE options can be given to override detection.

Value

MRS data object.

Examples

fname <- system.file("extdata", "philips_spar_sdat_WS.SDAT", package = "spant")
mrs_data <- read_mrs(fname)
print(mrs_data)

Read MRS data using the TARQUIN software package.

Description

Read MRS data using the TARQUIN software package.

Usage

read_mrs_tqn(fname, fname_ref = NA, format, id = NA, group = NA)

Arguments

fname

the filename containing the MRS data.

fname_ref

a second filename containing reference MRS data.

format

format of the MRS data. Can be one of the following: siemens, philips, ge, dcm, dpt, rda, lcm, varian, bruker, jmrui_txt.

id

optional ID string.

group

optional group string.

Value

MRS data object.

Examples

fname <- system.file("extdata","philips_spar_sdat_WS.SDAT",package="spant")
## Not run: 
mrs_data <- read_mrs_tqn(fname, format="philips")

## End(Not run)

Read an ASCII formatted pulse file.

Description

Read an ASCII formatted pulse file.

Usage

read_pulse_ascii(fname, deg2rad = TRUE)

Arguments

fname

ASCII formatted pulse file path.

deg2rad

convert phase values stored in degrees to radians.

Value

pulse waveform and header.


Read a Bruker formatted pulse file

Description

Read a Bruker formatted pulse file

Usage

read_pulse_bruker(fname)

Arguments

fname

Bruker formatted pulse file path.

Value

pulse waveform and header.


Read a .pta formatted pulse file compatible with Siemens PulseTool.

Description

Read a .pta formatted pulse file compatible with Siemens PulseTool.

Usage

read_pulse_pta(fname)

Arguments

fname

pta formatted pulse file path.

Value

pulse waveform and header.


Read the text format header found in Siemens IMA and TWIX data files.

Description

Read the text format header found in Siemens IMA and TWIX data files.

Usage

read_siemens_txt_hdr(input, version = "vd", verbose = FALSE, offset = 0)

Arguments

input

file name to read or raw data.

version

software version, can be "vb" or "vd".

verbose

print information to the console.

offset

offset to begin searching for the text header.

Value

a list of parameter values


Reader for csv fit results generated by TARQUIN.

Description

Reader for csv fit results generated by TARQUIN.

Usage

read_tqn_fit(fit_f)

Arguments

fit_f

TARQUIN fit file.

Value

A data frame of the fit data points.

Examples

## Not run: 
fit <- read_tqn_fit(system.file("extdata","fit.csv",package="spant"))

## End(Not run)

Reader for csv results generated by TARQUIN.

Description

Reader for csv results generated by TARQUIN.

Usage

read_tqn_result(result_f, remove_rcs = TRUE)

Arguments

result_f

TARQUIN result file.

remove_rcs

omit row, column and slice ids from output.

Value

list of amplitudes, crlbs and diagnostics.

Examples

## Not run: 
result <- read_tqn_result(system.file("extdata","result.csv",package="spant"))

## End(Not run)

Reconstruct complex time-domain data from the real part of frequency-domain data.

Description

Reconstruct complex time-domain data from the real part of frequency-domain data.

Usage

recon_imag(mrs_data)

Arguments

mrs_data

MRS data.

Value

reconstructed MRS data.


Reconstruct complex time-domain data from the real part of frequency-domain data.

Description

Reconstruct complex time-domain data from the real part of frequency-domain data.

Usage

recon_imag_vec(data)

Arguments

data

data points in the frequency domain.

Value

reconstructed signal.


Reconstruct 2D MRSI data from a twix file loaded with read_mrs.

Description

Reconstruct 2D MRSI data from a twix file loaded with read_mrs.

Usage

recon_twix_2d_mrsi(twix_mrs)

Arguments

twix_mrs

raw dynamic data.

Value

reconstructed data.


Create a rectangular mask stored as a matrix of logical values.

Description

Create a rectangular mask stored as a matrix of logical values.

Usage

rectangular_mask(xN, yN, x0, y0, xw, yw, angle)

Arguments

xN

number of pixels in the x dimension.

yN

number of pixels in the y dimension.

x0

centre of rectangle in the x direction in units of pixels.

y0

centre of rectangle in the y direction in units of pixels.

xw

width in the x direction in units of pixels.

yw

width in the y direction in units of pixels.

angle

angle of rotation in degrees.

Value

logical mask matrix with dimensions fov_yN x fov_xN.


Repeat an array over a given dimension.

Description

Repeat an array over a given dimension.

Usage

rep_array_dim(x, rep_dim, n)

Arguments

x

array.

rep_dim

dimension to extend.

n

number of times to repeat.

Value

extended array.


Replicate a scan in the dynamic dimension.

Description

Replicate a scan in the dynamic dimension.

Usage

rep_dyn(mrs_data, times)

Arguments

mrs_data

MRS data to be replicated.

times

number of times to replicate.

Value

replicated data object.


Replicate a scan over a given dimension.

Description

Replicate a scan over a given dimension.

Usage

rep_mrs(
  mrs_data,
  x_rep = 1,
  y_rep = 1,
  z_rep = 1,
  dyn_rep = 1,
  coil_rep = 1,
  warn = TRUE
)

Arguments

mrs_data

MRS data to be replicated.

x_rep

number of x replications.

y_rep

number of y replications.

z_rep

number of z replications.

dyn_rep

number of dynamic replications.

coil_rep

number of coil replications.

warn

print a warning when the data dimensions do not change.

Value

replicated data object.


Resample a basis-set to match a mrs_data acquisition.

Description

Resample a basis-set to match a mrs_data acquisition.

Usage

resample_basis(basis, mrs_data, ref_freq_match = TRUE)

Arguments

basis

the basis to be resampled.

mrs_data

the mrs_data to match the number of data points and sampling frequency.

ref_freq_match

apply a frequency shift to the basis to match the reference frequency (usually 4.65 or 4.68) of the mrs_data.

Value

resampled basis set object.


Resample an image to match a target image space.

Description

Resample an image to match a target image space.

Usage

resample_img(source, target, interp = 3L)

Arguments

source

image data as a nifti object.

target

image data as a nifti object.

interp

interpolation parameter, see nifyreg.linear definition.

Value

resampled image data as a nifti object.


Resample a VOI to match a target image space using nearest-neighbour interpolation.

Description

Resample a VOI to match a target image space using nearest-neighbour interpolation.

Usage

resample_voi(voi, mri)

Arguments

voi

volume data as a nifti object.

mri

image data as a nifti object.

Value

volume data as a nifti object.


Reslice a nifti object to match the orientation of mrs data.

Description

Reslice a nifti object to match the orientation of mrs data.

Usage

reslice_to_mrs(mri, mrs, interp = 3L)

Arguments

mri

nifti object to be resliced.

mrs

mrs_data object for the target orientation.

interp

interpolation parameter, see nifyreg.linear definition.

Value

resliced imaging data.


Generate mrs_data from a table of single Lorentzian resonances.

Description

Generate mrs_data from a table of single Lorentzian resonances.

Usage

reson_table2mrs_data(
  reson_table,
  acq_paras = def_acq_paras(),
  back_extrap_pts = 0
)

Arguments

reson_table

as produced by the hsvd function.

acq_paras

list of acquisition parameters. See

back_extrap_pts

number of data points to back extrapolate def_acq_paras

Value

mrs_data object.


Remove a subset of dynamic scans.

Description

Remove a subset of dynamic scans.

Usage

rm_dyns(mrs_data, subset)

Arguments

mrs_data

dynamic MRS data.

subset

vector containing indices to the dynamic scans to be removed.

Value

MRS data without the specified dynamic scans.


Apply water reference scaling to a fitting results object to yield metabolite quantities in units of "mmol per Kg wet weight".

Description

See the LCModel manual (section 10.2) on water-scaling for details on the assumptions and relevant references. Use this type of concentration scaling to compare fit results with LCModel and TARQUIN defaults. Otherwise scale_amp_molal_pvc is the preferred method. Note, the LCModel manual (section 1.3) states:

Usage

scale_amp_legacy(fit_result, ref_data, w_att = 0.7, w_conc = 35880, ...)

Arguments

fit_result

a result object generated from fitting.

ref_data

water reference MRS data object.

w_att

water attenuation factor (default = 0.7). Assumes water T2 of 80ms and a TE = 30 ms. exp(-30ms / 80ms) ~ 0.7.

w_conc

assumed water concentration (default = 35880). Default value corresponds to typical white matter. Set to 43300 for gray matter, and 55556 for phantom measurements.

...

additional arguments to get_td_amp function.

Details

"Concentrations should be labelled 'mmol per Kg wet weight'. We use the shorter (incorrect) abbreviation mM. The actual mM is the mmol per Kg wet weight multiplied by the specific gravity of the tissue, typically 1.04 in brain."

Value

a fit_result object with a rescaled results table.


Apply water reference scaling to a fitting results object to yield metabolite quantities in millimolar (mM) units (mol / kg of tissue water).

Description

Note, this function assumes the volume contains a homogeneous voxel, eg pure WM, GM or CSF. Also note that in the case of a homogeneous voxel the relative densities of MR-visible water (eg GM=0.78, WM=0.65, and CSF=0.97) cancel out and don't need to be considered. Use scale_amp_molal_pvc for volumes containing multiple compartments. Details of this method can be found in "Use of tissue water as a concentration reference for proton spectroscopic imaging" by Gasparovic et al MRM 2006 55(6):1219-26.

Usage

scale_amp_molal(
  fit_result,
  ref_data,
  te,
  tr,
  water_t1,
  water_t2,
  metab_t1,
  metab_t2,
  ...
)

Arguments

fit_result

result object generated from fitting.

ref_data

water reference MRS data object.

te

the MRS TE in seconds.

tr

the MRS TR in seconds.

water_t1

assumed water T1 value.

water_t2

assumed water T2 value.

metab_t1

assumed metabolite T1 value.

metab_t2

assumed metabolite T2 value.

...

additional arguments to get_td_amp function.

Value

A fit_result object with a rescaled results table.


Apply water reference scaling to a fitting results object to yield metabolite quantities in millimolar (mM) units (mol / kg of tissue water).

Description

Details of this method can be found in "Use of tissue water as a concentration reference for proton spectroscopic imaging" by Gasparovic et al MRM 2006 55(6):1219-26. 1.5 Tesla relaxation assumptions are taken from this paper. For 3 Tesla data, relaxation assumptions are taken from "NMR relaxation times in the human brain at 3.0 Tesla" by Wansapura et al J Magn Reson Imaging 1999 9(4):531-8.

Usage

scale_amp_molal_pvc(fit_result, ref_data, p_vols, te, tr, ...)

Arguments

fit_result

result object generated from fitting.

ref_data

water reference MRS data object.

p_vols

a numeric vector of partial volumes expressed as percentages. For example, a voxel containing 100% white matter tissue would use : p_vols = c(WM = 100, GM = 0, CSF = 0).

te

the MRS TE in seconds.

tr

the MRS TR in seconds.

...

additional arguments to get_td_amp function.

Value

A fit_result object with a rescaled results table.


Apply water reference scaling to a fitting results object to yield metabolite quantities in millimolar (mM) units (mol / Litre of tissue). This function is depreciated, please use scale_amp_legacy instead.

Description

See the LCModel manual (section 10.2) on water-scaling for details on the assumptions and relevant references. Use this type of concentration scaling to compare fit results with LCModel and TARQUIN defaults. Otherwise scale_amp_molal_pvc is generally the preferred method.

Usage

scale_amp_molar(fit_result, ref_data, w_att = 0.7, w_conc = 35880, ...)

Arguments

fit_result

a result object generated from fitting.

ref_data

water reference MRS data object.

w_att

water attenuation factor (default = 0.7). Assumes water T2 of 80ms and a TE = 30 ms. exp(-30ms / 80ms) ~ 0.7.

w_conc

assumed water concentration (default = 35880). Default value corresponds to typical white matter. Set to 43300 for gray matter, and 55556 for phantom measurements.

...

additional arguments to get_td_amp function.

Value

a fit_result object with a rescaled results table.


Convert default LCM/TARQUIN concentration scaling to molal units with partial volume correction.

Description

Convert default LCM/TARQUIN concentration scaling to molal units with partial volume correction.

Usage

scale_amp_molar2molal_pvc(fit_result, p_vols, te, tr)

Arguments

fit_result

a fit_result object to apply partial volume correction.

p_vols

a numeric vector of partial volumes expressed as percentages. For example, a voxel containing 100% white matter tissue would use : p_vols = c(WM = 100, GM = 0, CSF = 0).

te

the MRS TE.

tr

the MRS TR.

Value

a fit_result object with a rescaled results table.


Scale fitted amplitudes to a ratio of signal amplitude.

Description

Scale fitted amplitudes to a ratio of signal amplitude.

Usage

scale_amp_ratio(fit_result, name, use_mean_value = FALSE)

Arguments

fit_result

a result object generated from fitting.

name

the signal name to use as a denominator (usually, "tCr" or "tNAA").

use_mean_value

scales the result by the mean of the signal when set to TRUE.

Value

a fit_result object with a rescaled results table.


Scale fitted amplitudes to a ratio of signal amplitude.

Description

Scale fitted amplitudes to a ratio of signal amplitude.

Usage

scale_amp_ratio_value(fit_result, value)

Arguments

fit_result

a result object generated from fitting.

value

the number use as a denominator.

Value

a fit_result object with a rescaled results table.


Scale metabolite amplitudes as a ratio to the unsuppressed water amplitude.

Description

Scale metabolite amplitudes as a ratio to the unsuppressed water amplitude.

Usage

scale_amp_water_ratio(fit_result, ref_data, ...)

Arguments

fit_result

a result object generated from fitting.

ref_data

a water reference MRS data object.

...

additional arguments to get_td_amp function.

Value

a fit_result object with a rescaled results table.


Scale a basis object by a scalar.

Description

Scale a basis object by a scalar.

Usage

scale_basis_amp(basis, amp)

Arguments

basis

basis_set object to be scaled.

amp

multiplicative factor with length 1.

Value

basis_set object multiplied by the amplitude scale factor.


Scale a basis-set to be consistent with spant assumptions for water scaling.

Description

For correct water scaling, spant assumes the time-domain amplitude (t = 0) for a single proton is 0.5. Internally simulated basis-sets will be correctly scaled, however imported basis-sets should be assumed to be un-scaled and this function should be used. Note that the singlet specified should only contain one resonance, and that any additional signals (eg TSP or residual water) will result in incorrect scaling. Therefore, only simulated basis sets are appropriate for use with this function.

Usage

scale_basis_from_singlet(basis, name, protons)

Arguments

basis

basis set to be scaled.

name

the name of the singlet to be used as a scaling reference.

protons

the number of MRS visible protons contributing to the singlet resonance.

Value

a scaled basis.


Scale an mrs_data object by a scalar or vector or amplitudes.

Description

Scale an mrs_data object by a scalar or vector or amplitudes.

Usage

scale_mrs_amp(mrs_data, amp)

Arguments

mrs_data

data to be scaled.

amp

multiplicative factor, must have length equal to 1 or Nspec(mrs_data).

Value

mrs_data object multiplied by the amplitude scale factor.


Scale mrs_data to a spectral region.

Description

Scale mrs_data to a spectral region.

Usage

scale_spec(
  mrs_data,
  xlim = NULL,
  operator = "sum",
  freq_scale = "ppm",
  mode = "re",
  mean_dyns = NULL,
  ret_scale_factor = FALSE
)

Arguments

mrs_data

MRS data.

xlim

spectral range to be integrated (defaults to full range).

operator

can be "sum" (default), "mean", "l2", "max", "min" or "max-min".

freq_scale

units of xlim, can be : "ppm", "Hz" or "points".

mode

spectral mode, can be : "re", "im", "mod" or "cplx".

mean_dyns

mean the dynamic scans before applying the operator. The same scaling value will be applied to each individual dynamic.

ret_scale_factor

option to return the scaling factor in addition to the scaled data.

Value

normalised data.


Calculate the standard deviation spectrum from an mrs_data object.

Description

Calculate the standard deviation spectrum from an mrs_data object.

Usage

sd(x, na.rm)

Arguments

x

object of class mrs_data.

na.rm

remove NA values.

Value

sd mrs_data object.


Calculate the standard deviation spectrum from an mrs_data object.

Description

Calculate the standard deviation spectrum from an mrs_data object.

Usage

## S3 method for class 'mrs_data'
sd(x, na.rm = FALSE)

Arguments

x

object of class mrs_data.

na.rm

remove NA values.

Value

sd mrs_data object.


Return a time scale vector to match the FID of an MRS data object.

Description

Return a time scale vector to match the FID of an MRS data object.

Usage

seconds(mrs_data)

Arguments

mrs_data

MRS data.

Value

time scale vector in units of seconds.


CPMG style sequence with ideal pulses.

Description

CPMG style sequence with ideal pulses.

Usage

seq_cpmg_ideal(spin_params, ft, ref, TE = 0.03, echoes = 4)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE

echo time in seconds.

echoes

number of echoes.

Value

list of resonance amplitudes and frequencies.


MEGA-PRESS sequence with ideal localisation pulses and Gaussian shaped editing pulse.

Description

MEGA-PRESS sequence with ideal localisation pulses and Gaussian shaped editing pulse.

Usage

seq_mega_press_ideal(
  spin_params,
  ft,
  ref,
  ed_freq = 1.89,
  TE1 = 0.015,
  TE2 = 0.053,
  BW = 110,
  steps = 50
)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

ed_freq

editing pulse frequency in ppm.

TE1

TE1 sequence parameter in seconds (TE=TE1+TE2).

TE2

TE2 sequence parameter in seconds.

BW

editing pulse bandwidth in Hz.

steps

number of hard pulses used to approximate the editing pulse.

Value

list of resonance amplitudes and frequencies.


PRESS sequence with shaped refocusing pulses.

Description

PRESS sequence with shaped refocusing pulses.

Usage

seq_press_2d_shaped(
  spin_params,
  ft,
  ref,
  TE1 = 0.01,
  TE2 = 0.02,
  pulse_file,
  pulse_dur,
  pulse_file_format,
  refoc_flip_angle = 180,
  xy_pulse_ppm = NULL,
  resamp = TRUE,
  fs_resamp = 1e-04
)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE1

TE1 sequence parameter in seconds (TE=TE1+TE2).

TE2

TE2 sequence parameter in seconds.

pulse_file

path to refocusing pulse file.

pulse_dur

refocusing pulse duration.

pulse_file_format

file format for the refocusing pulse.

refoc_flip_angle

refocusing pulse flip angle in degrees (defaults to 180).

xy_pulse_ppm

a vector of ppm values for the offset of each sub-simulation.

resamp

option to resample the pulse shape.

fs_resamp

sampling frequency (Hz) to resample.

Value

list of resonance amplitudes and frequencies.


PRESS sequence with ideal pulses.

Description

PRESS sequence with ideal pulses.

Usage

seq_press_ideal(spin_params, ft, ref, TE1 = 0.01, TE2 = 0.02)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE1

TE1 sequence parameter in seconds (TE=TE1+TE2).

TE2

TE2 sequence parameter in seconds.

Value

list of resonance amplitudes and frequencies.


Simple pulse and acquire sequence with ideal pulses.

Description

Simple pulse and acquire sequence with ideal pulses.

Usage

seq_pulse_acquire(spin_params, ft, ref, nuc = "1H", acq_delay = 0)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

nuc

acquisition nucleus.

acq_delay

delay between excitation and acquisition.

Value

list of resonance amplitudes and frequencies.


sLASER sequence with ideal pulses.

Description

sLASER sequence with ideal pulses.

Usage

seq_slaser_ideal(spin_params, ft, ref, TE1 = 0.008, TE2 = 0.011, TE3 = 0.009)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE1

first echo time (between exc. and 1st echo) in seconds.

TE2

second echo time (between 2nd echo and 4th echo) in seconds.

TE3

third echo time (between 4th echo and 5th echo) in seconds.

Value

list of resonance amplitudes and frequencies.


Spin echo sequence with ideal pulses.

Description

Spin echo sequence with ideal pulses.

Usage

seq_spin_echo_ideal(spin_params, ft, ref, nuc = "1H", TE = 0.03)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

nuc

acquisition nucleus.

TE

echo time in seconds.

Value

list of resonance amplitudes and frequencies.


STEAM sequence with ideal pulses.

Description

STEAM sequence with ideal pulses.

Usage

seq_steam_ideal(spin_params, ft, ref, TE = 0.03, TM = 0.02, amp_scale = 2)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE

sequence parameter in seconds.

TM

sequence parameter in seconds.

amp_scale

amplitude scaling factor. Set to 2 (default) to ensure correct scaling for water reference scaling. Set to 1 to maintain the inherent loss of signal associated with STEAM.

Value

list of resonance amplitudes and frequencies.


STEAM sequence with ideal pulses and coherence order filtering to simulate gradient crushers.

Description

See Landheer et al NMR Biomed 2021 34(5):e4129 and Landheer et al MRM 2019 Apr;81(4):2209-2222 for more details on the coherence order filtering method.

Usage

seq_steam_ideal_cof(spin_params, ft, ref, TE = 0.03, TM = 0.02, amp_scale = 2)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE

sequence parameter in seconds.

TM

sequence parameter in seconds.

amp_scale

amplitude scaling factor. Set to 2 (default) to ensure correct scaling for water reference scaling. Set to 1 to maintain the inherent loss of signal associated with STEAM.

Value

list of resonance amplitudes and frequencies.


STEAM sequence with ideal pulses using the z-rotation gradient simulation method described by Young et al JMR 140, 146-152 (1999).

Description

STEAM sequence with ideal pulses using the z-rotation gradient simulation method described by Young et al JMR 140, 146-152 (1999).

Usage

seq_steam_ideal_young(
  spin_params,
  ft,
  ref,
  TE = 0.03,
  TM = 0.02,
  amp_scale = 2
)

Arguments

spin_params

spin system definition.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

TE

sequence parameter in seconds.

TM

sequence parameter in seconds.

amp_scale

amplitude scaling factor. Set to 2 (default) to ensure correct scaling for water reference scaling. Set to 1 to maintain the inherent loss of signal associated with STEAM.

Value

list of resonance amplitudes and frequencies.


Set the default acquisition parameters.

Description

Set the default acquisition parameters.

Usage

set_def_acq_paras(
  ft = getOption("spant.def_ft"),
  fs = getOption("spant.def_fs"),
  N = getOption("spant.def_N"),
  ref = getOption("spant.def_ref"),
  nuc = getOption("spant.nuc")
)

Arguments

ft

transmitter frequency in Hz.

fs

sampling frequency in Hz.

N

number of data points in the spectral dimension.

ref

reference value for ppm scale.

nuc

resonant nucleus.


Set the command to run the LCModel command-line program.

Description

Set the command to run the LCModel command-line program.

Usage

set_lcm_cmd(cmd)

Arguments

cmd

path to binary.


Apply line-broadening to an mrs_data object to achieve a specified linewidth.

Description

Apply line-broadening to an mrs_data object to achieve a specified linewidth.

Usage

set_lw(mrs_data, lw, xlim = c(4, 0.5), lg = 1, mask_narrow = TRUE)

Arguments

mrs_data

data in.

lw

target linewidth in units of ppm.

xlim

region to search for peaks to obtain a linewidth estimate.

lg

Lorentz-Gauss lineshape parameter.

mask_narrow

masks spectra where the requested linewidth is too narrow, if set FALSE the spectra are not changed.

Value

line-broadened data.


Set the masked voxels in a 2D MRSI dataset to given spectrum.

Description

Set the masked voxels in a 2D MRSI dataset to given spectrum.

Usage

set_mask_xy_mat(mrs_data, mask, mask_mrs_data)

Arguments

mrs_data

MRSI data object.

mask

matrix of boolean values specifying the voxels to set, where a value of TRUE indicates the voxel should be set to mask_mrs_data.

mask_mrs_data

the spectral data to be assigned to the masked voxels.

Value

updated dataset.


Set the number of transients for an mrs_data object.

Description

Set the number of transients for an mrs_data object.

Usage

set_Ntrans(mrs_data, n_trans)

Arguments

mrs_data

MRS data.

n_trans

number of acquired transients.


Set the precompute mode.

Description

Set the precompute mode.

Usage

set_precomp_mode(mode = NA)

Arguments

mode

can be one of: "default", "overwrite", "clean" or "disabled".


Set the verbosity of the precompute function.

Description

Set the verbosity of the precompute function.

Usage

set_precomp_verbose(verbose = NA)

Arguments

verbose

can be TRUE or FALSE.


Set the ppm reference value (eg ppm value at 0Hz).

Description

Set the ppm reference value (eg ppm value at 0Hz).

Usage

set_ref(mrs_data, ref)

Arguments

mrs_data

MRS data.

ref

reference value for ppm scale.


Set the number of time-domain data points, truncating or zero-filling as appropriate.

Description

Set the number of time-domain data points, truncating or zero-filling as appropriate.

Usage

set_td_pts(mrs_data, pts)

Arguments

mrs_data

MRS data.

pts

number of data points.

Value

MRS data with pts data points.


Set the command to run the TARQUIN command-line program.

Description

Set the command to run the TARQUIN command-line program.

Usage

set_tqn_cmd(cmd)

Arguments

cmd

path to binary.


Set the repetition time of an MRS dataset.

Description

Set the repetition time of an MRS dataset.

Usage

set_tr(mrs_data, tr)

Arguments

mrs_data

MRS data.

tr

repetition time in seconds.

Value

updated mrs_data set.


Apply a frequency shift to MRS data.

Description

Apply a frequency shift to MRS data.

Usage

shift(mrs_data, shift, units = "ppm")

Arguments

mrs_data

MRS data.

shift

frequency shift (in ppm by default).

units

of the shift ("ppm" or "hz").

Value

frequency shifted MRS data.


Apply frequency shifts to basis set signals.

Description

Apply frequency shifts to basis set signals.

Usage

shift_basis(basis, shifts)

Arguments

basis

the basis to apply the shift to.

shifts

a vector of frequency shifts to apply in ppm units. Must be the same length as there are basis elements, or one value to be applied to all elements.

Value

modified basis set object.


Simulate a basis set object.

Description

Simulate a basis set object.

Usage

sim_basis(
  mol_list,
  pul_seq = seq_pulse_acquire,
  acq_paras = def_acq_paras(),
  xlim = NULL,
  auto_scale = FALSE,
  use_basis_cache = FALSE,
  verbose = FALSE,
  ...
)

Arguments

mol_list

list of mol_parameter objects. Alternatively, a character vector matching molecules may also be provided. Use the get_mol_names function for a full list of molecules.

pul_seq

pulse sequence function to use.

acq_paras

list of acquisition parameters or an mrs_data object. See def_acq_paras

xlim

ppm range limiting signals to be simulated.

auto_scale

scale the basis based on the intensity of a singlet resonance. Needed for sequences with spatial simulation.

use_basis_cache

create and use a cache of simulated basis sets stored in the "spant_basis_cache" folder in the users home directory. Defaults to FALSE.

verbose

output simulation progress and timings.

...

extra parameters to pass to the pulse sequence function.

Value

basis object.


Simulate a basis-set suitable for 1H brain MRS analysis acquired with a PRESS sequence. Note, ideal pulses are assumed.

Description

Simulate a basis-set suitable for 1H brain MRS analysis acquired with a PRESS sequence. Note, ideal pulses are assumed.

Usage

sim_basis_1h_brain(
  pul_seq = seq_press_ideal,
  acq_paras = def_acq_paras(),
  xlim = c(0.5, 4.2),
  lcm_compat = FALSE,
  ...
)

Arguments

pul_seq

pulse sequence function to use.

acq_paras

list of acquisition parameters or an mrs_data object. See def_acq_paras.

xlim

range of frequencies to simulate in ppm.

lcm_compat

exclude lipid and MM signals for use with default LCModel options.

...

extra parameters to pass to the pulse sequence function.

Value

basis object.


Simulate a basis-set suitable for 1H brain MRS analysis acquired with a PRESS sequence. Note, ideal pulses are assumed.

Description

Simulate a basis-set suitable for 1H brain MRS analysis acquired with a PRESS sequence. Note, ideal pulses are assumed.

Usage

sim_basis_1h_brain_press(
  acq_paras = def_acq_paras(),
  xlim = c(0.5, 4.2),
  lcm_compat = FALSE,
  TE1 = 0.01,
  TE2 = 0.02
)

Arguments

acq_paras

list of acquisition parameters or an mrs_data object. See def_acq_paras

xlim

range of frequencies to simulate in ppm.

lcm_compat

exclude lipid and MM signals for use with default LCModel options.

TE1

TE1 of PRESS sequence (TE = TE1 + TE2).

TE2

TE2 of PRESS sequence.

Value

basis object.


Simulate a macromolecular and lipid basis-set suitable for 1H brain MRS analysis.

Description

Simulate a macromolecular and lipid basis-set suitable for 1H brain MRS analysis.

Usage

sim_basis_mm_lip_lcm(acq_paras = def_acq_paras())

Arguments

acq_paras

list of acquisition parameters or an mrs_data object. See def_acq_paras

Value

basis object.


Simulate a basis file using TARQUIN.

Description

Simulate a basis file using TARQUIN.

Usage

sim_basis_tqn(
  fs = def_fs(),
  ft = def_ft(),
  N = def_N(),
  ref = def_ref(),
  opts = NULL
)

Arguments

fs

sampling frequency

ft

transmitter frequency

N

number of data points

ref

chemical shift reference

opts

list of options to pass to TARQUIN.

Examples

## Not run: 
write_basis_tqn('test.basis',mrs_data,c("--echo","0.04"))

## End(Not run)

Simulate MRS data with a similar appearance to normal brain (by default).

Description

Simulate MRS data with a similar appearance to normal brain (by default).

Usage

sim_brain_1h(
  acq_paras = def_acq_paras(),
  type = "normal_v2",
  pul_seq = seq_slaser_ideal,
  xlim = c(0.5, 4.2),
  full_output = FALSE,
  amps = NULL,
  basis_lb = NULL,
  zero_lip_mm = FALSE,
  remove_lip_mm = FALSE,
  ...
)

Arguments

acq_paras

list of acquisition parameters or an mrs_data object. See def_acq_paras.

type

type of spectrum, only "normal" is implemented currently.

pul_seq

pulse sequence function to use.

xlim

range of frequencies to simulate in ppm.

full_output

when FALSE (default) only output the simulated MRS data. When TRUE output a list containing the MRS data, basis set object and corresponding amplitudes.

amps

a vector of basis amplitudes may be specified to modify the output spectrum.

basis_lb

apply additional Gaussian line-broadening to the basis (Hz).

zero_lip_mm

zero the amplitudes of any lipid or macromolecular components based on their name starting with "MM" or "Lip".

remove_lip_mm

remove any lipid or macromolecular basis components based on their name starting with "MM" or "Lip".

...

extra parameters to pass to the pulse sequence function.

Value

see full_output option.


Simulate a mol_parameter object.

Description

Simulate a mol_parameter object.

Usage

sim_mol(
  mol,
  pul_seq = seq_pulse_acquire,
  ft = def_ft(),
  ref = def_ref(),
  fs = def_fs(),
  N = def_N(),
  xlim = NULL,
  ...
)

Arguments

mol

mol_parameter object.

pul_seq

pulse sequence function to use.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

fs

sampling frequency in Hz.

N

number of data points in the spectral dimension.

xlim

ppm range limiting signals to be simulated.

...

extra parameters to pass to the pulse sequence function.

Value

mrs_data object.


Simulate an mrs_data object containing simulated Gaussian noise.

Description

Simulate an mrs_data object containing simulated Gaussian noise.

Usage

sim_noise(
  sd = 0.1,
  fs = def_fs(),
  ft = def_ft(),
  N = def_N(),
  ref = def_ref(),
  nuc = def_nuc(),
  dyns = 1,
  fd = TRUE
)

Arguments

sd

standard deviation of the noise.

fs

sampling frequency in Hz.

ft

transmitter frequency in Hz.

N

number of data points in the spectral dimension.

ref

reference value for ppm scale.

nuc

resonant nucleus.

dyns

number of dynamic scans to generate.

fd

return data in the frequency-domain (TRUE) or time-domain (FALSE)

Value

mrs_data object.


Simulate a MRS data object containing a set of simulated resonances.

Description

Simulate a MRS data object containing a set of simulated resonances.

Usage

sim_resonances(
  freq = 0,
  amp = 1,
  lw = 0,
  lg = 0,
  phase = 0,
  freq_ppm = TRUE,
  acq_paras = def_acq_paras(),
  fp_scale = TRUE,
  back_extrap_pts = 0,
  sum_resonances = TRUE
)

Arguments

freq

resonance frequency.

amp

resonance amplitude.

lw

line width in Hz.

lg

Lorentz-Gauss lineshape parameter (between 0 and 1).

phase

phase in degrees.

freq_ppm

frequencies are given in ppm units if set to TRUE, otherwise Hz are assumed.

acq_paras

list of acquisition parameters. See def_acq_paras

fp_scale

multiply the first data point by 0.5.

back_extrap_pts

number of data points to back extrapolate.

sum_resonances

sum all resonances (default is TRUE), otherwise return a dynamic mrs_data object.

Value

MRS data object.

Examples

sim_data <- sim_resonances(freq = 2, lw = 5)

Simulate an ideal pulse excitation profile by smoothing a top-hat function with a Gaussian.

Description

Simulate an ideal pulse excitation profile by smoothing a top-hat function with a Gaussian.

Usage

sim_th_excit_profile(bw = 1500, sigma = 50, fa = 180)

Arguments

bw

top-hat bandwidth (Hz).

sigma

Gaussian width smoothing parameter (Hz).

fa

intended flip angle of the pulse.

Value

data frame containing the frequency scale, excitation profile and corresponding flip-angles.


Simulate an mrs_data object containing complex zero valued samples.

Description

Simulate an mrs_data object containing complex zero valued samples.

Usage

sim_zero(
  fs = def_fs(),
  ft = def_ft(),
  N = def_N(),
  ref = def_ref(),
  nuc = def_nuc(),
  dyns = 1
)

Arguments

fs

sampling frequency in Hz.

ft

transmitter frequency in Hz.

N

number of data points in the spectral dimension.

ref

reference value for ppm scale.

nuc

resonant nucleus.

dyns

number of dynamic scans to generate.

Value

mrs_data object.


Smooth data across the dynamic dimension with a Gaussian kernel.

Description

Smooth data across the dynamic dimension with a Gaussian kernel.

Usage

smooth_dyns(mrs_data, sigma)

Arguments

mrs_data

data to be smoothed.

sigma

standard deviation of the underlying Gaussian kernel in seconds.

Value

smoothed mrs_data object.


Sort the basis-set elements alphabetically.

Description

Sort the basis-set elements alphabetically.

Usage

sort_basis(basis)

Arguments

basis

input basis.

Value

sorted basis.


Simulate and fit some spectra with ABfit for benchmarking purposes. Basic timing and performance metrics will be printed.

Description

Simulate and fit some spectra with ABfit for benchmarking purposes. Basic timing and performance metrics will be printed.

Usage

spant_abfit_benchmark(noise_reps = 10, return_res = FALSE, opts = abfit_opts())

Arguments

noise_reps

number of spectra to fit with differing noise samples.

return_res

return a list of fit_result objects.

opts

ABfit options structure.


Example MEGA-PRESS data with significant B0 drift.

Description

Example MEGA-PRESS data with significant B0 drift.

Usage

spant_mpress_drift

Format

An object of class mrs_data of dimension 1 x 1 x 1 x 1 x 40 x 1 x 1024.


Simulate an example fMRS dataset for a block design fMRS experiment and export a BIDS structure.

Description

Simulate an example fMRS dataset for a block design fMRS experiment and export a BIDS structure.

Usage

spant_sim_fmrs_dataset(output_dir = NULL)

Arguments

output_dir

output directory for the BIDS data. Defaults to : "HOME/sim_fmrs_dataset/data".


Simulate a typical metabolite basis set for benchmarking. Timing metrics will be printed on completion.

Description

Simulate a typical metabolite basis set for benchmarking. Timing metrics will be printed on completion.

Usage

spant_simulation_benchmark(sim_reps = 10, N = 1024)

Arguments

sim_reps

number of times to simulate the basis set.

N

number of FID data points to simulate.


Decompose an mrs_data object into white and gray matter spectra.

Description

An implementation of the method published by Goryawala et al MRM 79(6) 2886-2895 (2018). "Spectral decomposition for resolving partial volume effects in MRSI".

Usage

spec_decomp(mrs_data, wm, gm, norm_fractions = TRUE)

Arguments

mrs_data

data to be decomposed into white and gray matter spectra.

wm

vector of white matter contributions to each voxel.

gm

vector of gray matter contributions to each voxel.

norm_fractions

option to normalise the wm, gm vectors for each voxel.

Value

a list of two mrs_data objects corresponding to the two tissue types.


Perform a mathematical operation on a spectral region.

Description

Perform a mathematical operation on a spectral region.

Usage

spec_op(
  mrs_data,
  xlim = NULL,
  operator = "sum",
  freq_scale = "ppm",
  mode = "re"
)

Arguments

mrs_data

MRS data.

xlim

spectral range to be integrated (defaults to full range).

operator

can be "sum" (default), "mean", "l2", "max", "max_cplx, "min" or "max-min".

freq_scale

units of xlim, can be : "ppm", "hz" or "points".

mode

spectral mode, can be : "re", "im", "mod" or "cplx".

Value

an array of integral values.


Create a spin system object for pulse sequence simulation.

Description

Create a spin system object for pulse sequence simulation.

Usage

spin_sys(spin_params, ft, ref, precomp_jc_H = NULL, precomp_Iz = NULL)

Arguments

spin_params

an object describing the spin system properties.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

precomp_jc_H

use a precomputed J-coupling H matrix to save time.

precomp_Iz

use precomputed Iz matrices to save time.

Value

spin system object.


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.

Description

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.

Usage

spm_pve2categorical(fname)

Arguments

fname

any of the segmentation files (eg c1_MY_T1.nii).

Value

nifti object.


Signal space projection method for lipid suppression.

Description

Signal space projection method as described in: Tsai SY, Lin YR, Lin HY, Lin FH. Reduction of lipid contamination in MR spectroscopy imaging using signal space projection. Magn Reson Med 2019 Mar;81(3):1486-1498.

Usage

ssp(mrs_data, comps = 5, xlim = c(1.5, 0.8))

Arguments

mrs_data

MRS data object.

comps

the number of spatial components to use.

xlim

spectral range (in ppm) covering the lipid signals.

Value

lipid suppressed mrs_data object.


Produce a plot with multiple traces.

Description

Produce a plot with multiple traces.

Usage

stackplot(x, ...)

Arguments

x

object for plotting.

...

arguments to be passed to methods.


Plot the fitting results of an object of class fit_result with individual basis set components shown.

Description

Plot the fitting results of an object of class fit_result with individual basis set components shown.

Usage

## S3 method for class 'fit_result'
stackplot(
  x,
  xlim = NULL,
  y_offset = 0,
  dyn = 1,
  x_pos = 1,
  y_pos = 1,
  z_pos = 1,
  coil = 1,
  n = NULL,
  sub_bl = FALSE,
  labels = FALSE,
  label_names = NULL,
  sig_col = "black",
  restore_def_par = TRUE,
  omit_signals = NULL,
  combine_lipmm = FALSE,
  combine_metab = FALSE,
  mar = NULL,
  show_grid = TRUE,
  grid_nx = NULL,
  grid_ny = NA,
  invert_fit = FALSE,
  ...
)

Arguments

x

fit_result object.

xlim

the range of values to display on the x-axis, eg xlim = c(4,1).

y_offset

separate basis signals in the y-axis direction by this value.

dyn

the dynamic index to plot.

x_pos

the x index to plot.

y_pos

the y index to plot.

z_pos

the z index to plot.

coil

the coil element number to plot.

n

single index element to plot (overrides other indices when given).

sub_bl

subtract the baseline from the data and fit (logical).

labels

print signal labels at the right side of the plot.

label_names

provide a character vector of signal names to replace the defaults determined from the basis set.

sig_col

colour of individual signal components.

restore_def_par

restore default plotting par values after the plot has been made.

omit_signals

a character vector of basis signal names to be removed from the plot.

combine_lipmm

combine all basis signals with names starting with "Lip" or "MM".

combine_metab

combine all basis signals with names not starting with "Lip" or "MM".

mar

option to adjust the plot margins. See ?par.

show_grid

plot gridlines behind the data (logical). Defaults to TRUE.

grid_nx

number of cells of the grid in x and y direction. When NULL the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction.

grid_ny

as above.

invert_fit

show the fit result "upside-down"/

...

further arguments to plot method.


Stackplot plotting method for objects of class mrs_data.

Description

Stackplot plotting method for objects of class mrs_data.

Usage

## S3 method for class 'mrs_data'
stackplot(
  x,
  xlim = NULL,
  mode = "re",
  x_units = NULL,
  fd = TRUE,
  col = NULL,
  alpha = NULL,
  x_offset = 0,
  y_offset = 0,
  plot_dim = NULL,
  x_pos = NULL,
  y_pos = NULL,
  z_pos = NULL,
  dyn = 1,
  coil = 1,
  bty = NULL,
  labels = NULL,
  lab_cex = 1,
  bl_lty = NULL,
  restore_def_par = TRUE,
  show_grid = NULL,
  grid_nx = NULL,
  grid_ny = NA,
  lwd = NULL,
  vline = NULL,
  vline_lty = 2,
  vline_col = "red",
  mar = NULL,
  ...
)

Arguments

x

object of class mrs_data.

xlim

the range of values to display on the x-axis, eg xlim = c(4,1).

mode

representation of the complex numbers to be plotted, can be one of: "re", "im", "mod" or "arg".

x_units

the units to use for the x-axis, can be one of: "ppm", "hz", "points" or "seconds".

fd

display data in the frequency-domain (default), or time-domain (logical).

col

set the colour of the line, eg col = rgb(1, 0, 0, 0.5).

alpha

set the line transparency, eg alpha = 0.5 is 50% transparency. Overrides any transparency levels set by col.

x_offset

separate plots in the x-axis direction by this value. Default value is 0.

y_offset

separate plots in the y-axis direction by this value.

plot_dim

the dimension to display on the y-axis, can be one of: "dyn", "x", "y", "z", "coil" or NULL. If NULL (the default) all spectra will be collapsed into the dynamic dimension and displayed.

x_pos

the x index to plot.

y_pos

the y index to plot.

z_pos

the z index to plot.

dyn

the dynamic index to plot.

coil

the coil element number to plot.

bty

option to draw a box around the plot. See ?par.

labels

add labels to each data item.

lab_cex

label size.

bl_lty

linetype for the y = 0 baseline trace. A default value NULL results in no baseline being plotted.

restore_def_par

restore default plotting par values after the plot has been made.

show_grid

plot gridlines behind the data (logical). Defaults to TRUE.

grid_nx

number of cells of the grid in x and y direction. When NULL the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction.

grid_ny

as above.

lwd

plot linewidth.

vline

x-value to draw a vertical line.

vline_lty

linetype for the vertical line.

vline_col

colour for the vertical line.

mar

option to adjust the plot margins. See ?par.

...

other arguments to pass to the matplot method.


Subtract the first dynamic spectrum from a dynamic series.

Description

Subtract the first dynamic spectrum from a dynamic series.

Usage

sub_first_dyn(mrs_data, scale = 1)

Arguments

mrs_data

dynamic MRS data.

scale

scale factor for the first spectrum.

Value

subtracted data.


Subtract the mean dynamic spectrum from a dynamic series.

Description

Subtract the mean dynamic spectrum from a dynamic series.

Usage

sub_mean_dyns(mrs_data, scale = 1)

Arguments

mrs_data

dynamic MRS data.

scale

scale factor for the mean spectrum.

Value

subtracted data.


Subtract the median dynamic spectrum from a dynamic series.

Description

Subtract the median dynamic spectrum from a dynamic series.

Usage

sub_median_dyns(mrs_data, scale = 1)

Arguments

mrs_data

dynamic MRS data.

scale

scale factor for the medium spectrum.

Value

subtracted data.


Calculate the sum across receiver coil elements.

Description

Calculate the sum across receiver coil elements.

Usage

sum_coils(mrs_data)

Arguments

mrs_data

MRS data split across receiver coil elements.

Value

sum across coil elements.


Calculate the sum of data dynamics.

Description

Calculate the sum of data dynamics.

Usage

sum_dyns(mrs_data)

Arguments

mrs_data

dynamic MRS data.

Value

sum of data dynamics.


Sum two mrs_data objects.

Description

Sum two mrs_data objects.

Usage

sum_mrs(a, b, force = FALSE)

Arguments

a

first mrs_data object to be summed.

b

second mrs_data object to be summed.

force

set to TRUE to force mrs_data objects to be summed, even if they are in different time/frequency domains.

Value

a + b


Return the sum of a list of mrs_data objects.

Description

Return the sum of a list of mrs_data objects.

Usage

sum_mrs_list(mrs_list)

Arguments

mrs_list

list of mrs_data objects.

Value

sum mrs_data object.


Output a table of fit amplitudes and error estimates for a single-voxel fit.

Description

Output a table of fit amplitudes and error estimates for a single-voxel fit.

Usage

sv_res_table(fit_res, format_out = FALSE)

Arguments

fit_res

input vector.

format_out

reduce the accuracy of values to aid table formatting.

Value

data.frame of values.


Standard SVS 1H brain analysis pipeline.

Description

Standard SVS 1H brain analysis pipeline.

Usage

svs_1h_brain_analysis(
  metab,
  basis = NULL,
  w_ref = NULL,
  mri_seg = NULL,
  mri = NULL,
  output_dir = NULL,
  extra = NULL,
  decimate = NULL,
  rats_corr = TRUE,
  ecc = FALSE,
  comb_dyns = TRUE,
  hsvd_filt = FALSE,
  scale_amps = TRUE,
  te = NULL,
  tr = NULL,
  preproc_only = FALSE,
  method = "ABFIT",
  opts = NULL
)

Arguments

metab

filepath or mrs_data object containing MRS metabolite data.

basis

basis set object to use for analysis.

w_ref

filepath or mrs_data object containing MRS water reference data.

mri_seg

filepath or nifti object containing segmented MRI data.

mri

filepath or nifti object containing anatomical MRI data.

output_dir

directory path to output fitting results.

extra

data.frame with one row containing additional information to be attached to the fit results table.

decimate

option to decimate the input data by a factor of two. The default value of NULL does not perform decimation unless the spectral width is greater than 20 PPM.

rats_corr

option to perform rats correction, defaults to TRUE.

ecc

option to perform water reference based eddy current correction, defaults to FALSE.

comb_dyns

option to combine dynamic scans, defaults to TRUE.

hsvd_filt

option to apply hsvd water removal, defaults to FALSE.

scale_amps

option to scale metabolite amplitude estimates, defaults to TRUE.

te

metabolite mrs data echo time in seconds.

tr

metabolite mrs data repetition time in seconds.

preproc_only

only perform the preprocessing steps and omit fitting. The preprocessed metabolite data will be returned in this case.

method

analysis method to use, see fit_mrs help.

opts

options to pass to the analysis method.

Value

a fit_result or mrs_data object depending on the preproc_only option.


Standard SVS 1H brain analysis pipeline.

Description

Note this function is still under development and liable to changes.

Usage

svs_1h_brain_analysis_dev(
  metab,
  w_ref = NULL,
  output_dir = NULL,
  basis = NULL,
  p_vols = NULL,
  append_basis = NULL,
  remove_basis = NULL,
  dfp_corr = FALSE,
  omit_bad_dynamics = FALSE,
  te = NULL,
  tr = NULL,
  output_ratio = "tCr",
  ecc = FALSE,
  abfit_opts = NULL,
  verbose = FALSE
)

Arguments

metab

filepath or mrs_data object containing MRS metabolite data.

w_ref

filepath or mrs_data object containing MRS water reference data.

output_dir

directory path to output fitting results.

basis

precompiled basis set object to use for analysis.

p_vols

a numeric vector of partial volumes expressed as percentages. Defaults to 100% white matter. A voxel containing 100% gray matter tissue would use : p_vols = c(WM = 0, GM = 100, CSF = 0).

append_basis

names of extra signals to add to the default basis. Eg append_basis = c("peth", "cit"). Cannot be used with precompiled basis sets.

remove_basis

names of signals to remove from the basis. Cannot be used with precompiled basis sets.

dfp_corr

perform dynamic frequency and phase correction using the RATS method.

omit_bad_dynamics

detect and remove bad dynamics.

te

metabolite mrs data echo time in seconds. If not supplied this will be guessed from the metab data file.

tr

metabolite mrs data repetition time in seconds. If not supplied this will be guessed from the metab data file.

output_ratio

optional string to specify a metabolite ratio to output. Defaults to "tCr" and multiple metabolites may be specified for multiple outputs. Set as NULL to omit.

ecc

option to perform water reference based eddy current correction, defaults to FALSE.

abfit_opts

options to pass to ABfit.

verbose

output potentially useful information.

Examples

metab <- system.file("extdata", "philips_spar_sdat_WS.SDAT",
                     package = "spant")
w_ref <- system.file("extdata", "philips_spar_sdat_W.SDAT",
                     package = "spant")
## Not run: 
fit_result <- svs_1h_brain_analysis(metab, w_ref, "fit_res_dir")

## End(Not run)

Batch interface to the standard SVS 1H brain analysis pipeline.

Description

Batch interface to the standard SVS 1H brain analysis pipeline.

Usage

svs_1h_brain_batch_analysis(
  metab_list,
  w_ref_list = NULL,
  mri_seg_list = NULL,
  mri_list = NULL,
  output_dir_list = NULL,
  extra = NULL,
  ...
)

Arguments

metab_list

list of file paths or mrs_data objects containing MRS metabolite data.

w_ref_list

list of file paths or mrs_data objects containing MRS water reference data.

mri_seg_list

list of file paths or nifti objects containing segmented MRI data.

mri_list

list of file paths or nifti objects containing anatomical MRI data.

output_dir_list

list of directory paths to output fitting results.

extra

a data frame with the same number of rows as metab_list, containing additional information to be attached to the fit results table.

...

additional options to be passed to the svs_1h_brain_analysis function.

Value

a list of fit_result objects.


Perform a t-test on spectral data points.

Description

Perform a t-test on spectral data points.

Usage

t_test_spec(mrs_data, group)

Arguments

mrs_data

an mrs_data object with spectra in the dynamic dimension.

group

vector describing the group membership of each dynamic spectrum.

Value

a list of statistical results.


Time-domain convolution based filter.

Description

Time-domain convolution based filter described by: Marion D, Ikura M, Bax A. Improved solvent suppression in one-dimensional and twodimensional NMR spectra by convolution of time-domain data. J Magn Reson 1989;84:425-430.

Usage

td_conv_filt(mrs_data, K = 25, ext = 1)

Arguments

mrs_data

MRS data to be filtered.

K

window width in data points.

ext

point separation for linear extrapolation.


Transform time-domain data to the frequency-domain.

Description

Transform time-domain data to the frequency-domain.

Usage

td2fd(mrs_data)

Arguments

mrs_data

MRS data in time-domain representation.

Value

MRS data in frequency-domain representation.


Time-domain spectral registration.

Description

An implementation of the method published by Near et al MRM 73:44-50 (2015).

Usage

tdsr(mrs_data, ref = NULL, xlim = c(4, 0.5), max_t = 0.2)

Arguments

mrs_data

MRS data to be corrected.

ref

optional MRS data to use as a reference, the mean of all dynamics is used if this argument is not supplied.

xlim

optional frequency range to perform optimisation, set to NULL to use the full range.

max_t

truncate the FID when longer than max_t to reduce time taken.

Value

a list containing the corrected data; phase and shift values in units of degrees and Hz respectively.


Return the echo time of an MRS dataset.

Description

Return the echo time of an MRS dataset.

Usage

te(mrs_data)

Arguments

mrs_data

MRS data.

Value

echo time in seconds.


Return the repetition time of an MRS dataset.

Description

Return the repetition time of an MRS dataset.

Usage

tr(mrs_data)

Arguments

mrs_data

MRS data.

Value

repetition time in seconds.


Return a list of options for VARPRO based fitting with 3 free parameters.

Description

Return a list of options for VARPRO based fitting with 3 free parameters.

Usage

varpro_3_para_opts(
  nstart = 20,
  init_damping = 2,
  maxiters = 200,
  max_shift = 5,
  max_damping = 5,
  anal_jac = FALSE,
  bl_smth_pts = 80
)

Arguments

nstart

position in the time-domain to start fitting, units of data points.

init_damping

starting value for the global Gaussian line-broadening term - measured in Hz.

maxiters

maximum number of levmar iterations to perform.

max_shift

maximum global shift allowed, measured in Hz.

max_damping

maximum damping allowed, FWHM measured in Hz.

anal_jac

option to use the analytic or numerical Jacobian (logical).

bl_smth_pts

number of data points to use in the baseline smoothing calculation.

Value

list of options.


Return a list of options for a basic VARPRO analysis.

Description

Return a list of options for a basic VARPRO analysis.

Usage

varpro_basic_opts(method = "fd_re", nnls = TRUE, ppm_left = 4, ppm_right = 0.2)

Arguments

method

one of "td", "fd", "fd_re".

nnls

restrict basis amplitudes to non-negative values.

ppm_left

downfield frequency limit for the fitting range (ppm).

ppm_right

upfield frequency limit for the fitting range (ppm).

Value

full list of options.


Return a list of options for VARPRO based fitting.

Description

Return a list of options for VARPRO based fitting.

Usage

varpro_opts(
  nstart = 20,
  init_g_damping = 2,
  maxiters = 200,
  max_shift = 5,
  max_g_damping = 5,
  max_ind_damping = 5,
  anal_jac = TRUE,
  bl_smth_pts = 80
)

Arguments

nstart

position in the time-domain to start fitting, units of data points.

init_g_damping

starting value for the global Gaussian line-broadening term - measured in Hz.

maxiters

maximum number of levmar iterations to perform.

max_shift

maximum shift allowed to each element in the basis set, measured in Hz.

max_g_damping

maximum permitted global Gaussian line-broadening.

max_ind_damping

maximum permitted Lorentzian line-broadening for each element in the basis set, measured in Hz.

anal_jac

option to use the analytic or numerical Jacobian (logical).

bl_smth_pts

number of data points to use in the baseline smoothing calculation.

Value

list of options.

Examples

varpro_opts(nstart = 10)

Convert a vector into a mrs_data object.

Description

Convert a vector into a mrs_data object.

Usage

vec2mrs_data(
  vec,
  mrs_data = NULL,
  fs = NULL,
  ft = NULL,
  ref = NULL,
  nuc = NULL,
  dyns = 1,
  fd = FALSE
)

Arguments

vec

the data vector.

mrs_data

example data to copy acquisition parameters from.

fs

sampling frequency in Hz.

ft

transmitter frequency in Hz.

ref

reference value for ppm scale.

nuc

resonant nucleus.

dyns

replicate the data across the dynamic dimension.

fd

flag to indicate if the vector is in the frequency domain (logical).

Value

mrs_data object.


Write a basis object to an LCModel .basis formatted file.

Description

Write a basis object to an LCModel .basis formatted file.

Usage

write_basis(basis, basis_file, fwhmba = 0.1)

Arguments

basis

basis object to be exported.

basis_file

path to basis file to be generated.

fwhmba

parameter used by LCModel.


Generate a basis file using TARQUIN.

Description

Generate a basis file using TARQUIN.

Usage

write_basis_tqn(basis_file, metab_data, opts = NULL)

Arguments

basis_file

filename of the basis file to be generated.

metab_data

MRS data object to match the generated basis parameters.

opts

list of options to pass to TARQUIN.

Examples

## Not run: 
write_basis_tqn('test.basis',mrs_data,c("--echo","0.04"))

## End(Not run)

Write MRS data object to file.

Description

Write MRS data object to file.

Usage

write_mrs(mrs_data, fname, format = NULL, force = FALSE)

Arguments

mrs_data

object to be written to file, or list of mrs_data objects.

fname

one or more filenames to output.

format

string describing the data format. Must be one of the following : "nifti", "dpt", "lcm_raw", "rds". If not specified, the format will be guessed from the filename extension.

force

set to TRUE to overwrite any existing files.


Write MRS data object to file in NIFTI format.

Description

Write MRS data object to file in NIFTI format.

Usage

write_mrs_nifti(mrs_data, fname)

Arguments

mrs_data

object to be written to file.

fname

the filename of the output NIFTI MRS data.


Write an ASCII formatted pulse file.

Description

Write an ASCII formatted pulse file.

Usage

write_pulse_ascii(pulse, path)

Arguments

pulse

pulse data object.

path

file path for export.


Fade a spectrum to zero by frequency domain multiplication with a tanh function. Note this operation distorts data points at the end of the FID.

Description

Fade a spectrum to zero by frequency domain multiplication with a tanh function. Note this operation distorts data points at the end of the FID.

Usage

zero_fade_spec(mrs_data, start_ppm, end_ppm)

Arguments

mrs_data

data to be faded.

start_ppm

start point of the fade in ppm units.

end_ppm

end point of the fade in ppm units.

Value

modified mrs_data object.


Zero all coherences including and above a given order.

Description

Zero all coherences including and above a given order.

Usage

zero_higher_orders(sys, rho, order)

Arguments

sys

spin system object.

rho

density matrix.

order

states higher than or equal to this argument will be set to zero.

Value

density matrix.


Set mrs_data object data points at the end of the FID to zero.

Description

Set mrs_data object data points at the end of the FID to zero.

Usage

zero_td_pts_end(mrs_data, pts)

Arguments

mrs_data

MRS data.

pts

number of end points to set to zero.

Value

modified mrs_data object.


Zero-fill MRS data in the time domain.

Description

Zero-fill MRS data in the time domain.

Usage

zf(x, factor = 2, offset = 0)

## S3 method for class 'list'
zf(x, factor = 2, offset = 0)

## S3 method for class 'mrs_data'
zf(x, factor = 2, offset = 0)

## S3 method for class 'basis_set'
zf(x, factor = 2, offset = 0)

Arguments

x

input mrs_data or basis_set object.

factor

zero-filling factor, factor of 2 returns a dataset with twice the original data points.

offset

number of points from the end of the FID to insert the zero values.

Value

zero-filled data.


Zero-fill MRSI data in the k-space x-y direction.

Description

Zero-fill MRSI data in the k-space x-y direction.

Usage

zf_xy(mrs_data, factor = 2)

Arguments

mrs_data

MRSI data.

factor

zero-filling factor, a factor of 2 returns a dataset with twice the original points in the x-y directions. Factors smaller than one are permitted, such that a factor of 0.5 returns half the k-space points in the x-y directions.

Value

zero-filled data.