Site built with pkgdown 2.1.0.
+Site built with pkgdown 2.1.1.
diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html index 69792ba5..a31e36a8 100644 --- a/docs/LICENSE-text.html +++ b/docs/LICENSE-text.html @@ -17,7 +17,7 @@ @@ -762,7 +762,7 @@Site built with pkgdown 2.1.0.
+Site built with pkgdown 2.1.1.
diff --git a/docs/articles/index.html b/docs/articles/index.html index aad69369..308d6ddd 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -17,7 +17,7 @@ @@ -95,7 +95,7 @@Site built with pkgdown 2.1.0.
+Site built with pkgdown 2.1.1.
diff --git a/docs/articles/spant-intro.html b/docs/articles/spant-intro.html index 0ab4d399..35a8352c 100644 --- a/docs/articles/spant-intro.html +++ b/docs/articles/spant-intro.html @@ -38,7 +38,7 @@ @@ -315,7 +315,7 @@An alternative method scales the metabolite values into molar (mM) units (mol / Litre of tissue) based on assumptions outlined in the LCModel manual and references therein (section 10.2). This approach may @@ -323,6 +323,8 @@
fit_res_molar <- scale_amp_molar(fit_res, mrs_data_wref)
+#> Warning in scale_amp_molar(fit_res, mrs_data_wref): Function name
+#> (scale_amp_molar) is missleading and has been replaced with scale_amp_legacy.
fit_res_molar$res_tab$tNAA
#> [1] 6.826335Note, while “absolute” units are attractive, a large number of @@ -350,7 +352,7 @@
Site built with pkgdown 2.1.0.
+Site built with pkgdown 2.1.1.
diff --git a/docs/articles/spant-preprocessing.html b/docs/articles/spant-preprocessing.html index 733deb7e..ca1abd4d 100644 --- a/docs/articles/spant-preprocessing.html +++ b/docs/articles/spant-preprocessing.html @@ -38,7 +38,7 @@ @@ -175,7 +175,7 @@Site built with pkgdown 2.1.0.
+Site built with pkgdown 2.1.1.
diff --git a/docs/authors.html b/docs/authors.html index ee2d0e06..66ddee89 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -17,7 +17,7 @@ @@ -140,7 +140,7 @@The online spant user manual (pdf version) is written for users with minimal experience in R or MRS processing and is the best place to start.
+For more advanced users, help developing custom analysis pipeline can be found below.
+Introduction : https://martin3141.github.io/spant/articles/spant-intro.html
+Short tutorials : https://martin3141.github.io/spant/articles/
+Function reference : https://martin3141.github.io/spant/reference/
+Once the spant library has been loaded with library(spant), type ?spant on the console for instructions on how to access the offline documentation. Note that offline help on the available functions can be quickly shown in RStudio using ?function_name, eg ?read_mrs.
Download and install the latest version of R (https://cloud.r-project.org/), or with your package manager if using a recent Linux distribution, eg sudo apt install r-base.
Quick introduction to the basic analysis workflow : https://martin3141.github.io/spant/articles/spant-intro.html
-Short tutorials : https://martin3141.github.io/spant/articles/
-Function reference : https://martin3141.github.io/spant/reference/
-Once the spant library has been loaded with library(spant), type ?spant on the console for instructions on how to access the offline documentation. Note that offline help on the available functions can be quickly shown in RStudio using ?function_name, eg ?read_mrs.
CRAN packages need to be compiled on Linux, and therefore you may need to ensure some additional system libraries are installed. spant may be installed from a clean installation of Ubuntu 20.04 with the following commands pasted into the terminal:
@@ -265,7 +267,7 @@R/abfit.R
+ abfit_reg_opts.RdReturn a list of options for an ABfit analysis with regularision.
+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
+)initial value of the Gaussian global damping parameter +(Hz). Very poorly shimmed or high field data may benefit from a larger value.
The maximum number of iterations to run for the detailed fit.
The maximum allowable global shift to be applied in the +approximate (pre-fit) phases of analysis (ppm).
The maximum allowable global shift to be applied in the +detailed fit phase of analysis (ppm).
maximum permitted value of the global damping parameter +(Hz).
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.
manually set the the baseline smoothness parameter.
downfield frequency limit for the fitting range (ppm).
upfield frequency limit for the fitting range (ppm).
zero pad the data to twice the original length before fitting.
manually set the the baseline smoothness parameter (ED per +ppm).
automatically determine the level of baseline smoothness.
spline basis density (signals per ppm).
adjust the spline basis density in the detailed +fit phase, based on the required level of smoothness, to reduce computation +time.
add the fitted spline functions to the fit result.
maximum allowable value of the asymmetry parameter.
maximum allowable frequency shift for individual basis +signals (ppm).
maximum allowable Lorentzian damping factor for +individual basis signals (Hz).
maximum iterations for the coarse (pre-)fit.
optimisation method for the coarse (pre-)fit.
minimum value for the candidate baseline flexibility +analyses (ED per ppm).
minimum value for the candidate baseline flexibility +analyses (ED per ppm).
number of candidate baseline analyses to perform.
level of baseline flexibility to use in the coarse +fitting stage of the algorithm (ED per ppm).
remove broad signals in the coarse fitting stage +of the algorithm.
perform a pre-alignment step before coarse fitting.
maximum allowable shift in the pre-alignment step +(ppm).
a vector of prominent spectral frequencies used in +the pre-alignment step (ppm).
spectral region to estimate the noise level (ppm).
method to determine the optimal smoothness.
modification factor for the AIC calculation. +Larger values result in less flexible baselines.
use a analytical approximation to the jacobian in the +detailed fitting stage.
downfield frequency limit for the fitting range in +the coarse fitting stage of the algorithm (ppm).
upfield frequency limit for the fitting range in the +coarse fitting stage of the algorithm (ppm).
apply and optimise a frequency dependant phase term.
initial value for the frequency dependant phase term (ms).
maximum allowable change from the initial frequency +dependant phase term (ms).
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.
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.
method to calculate the metabolite amplitudes. May be +one of: "lh_pnnls" or "ls".
perform a 1D search for the optimal phase in the +prefit stage of the algorithm.
frequency shift parameter.
frequency shift parameter for NAA and NAAG.
individual line broadening parameter.
lineshape asymmetry parameter.
include more fitting parameters in the fit table, +e.g. individual shift and damping factors for each basis set element.
include raw fitting parameters in the fit table. +For advanced diagnostic use only.
input raw fitting parameters. For advanced diagnostic +use only.
optimize the global line-broadening term only.
limits for the line-breading term as a percentage +of the starting value when optim_lw_only is TRUE.
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.
apply lb_init to the basis during the approximate +iterative fit.
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.
full list of options.
+opts <- abfit_reg_opts(ppm_left = 4.2, noise_region = c(-1, -3))
+Note this function is still under development and liable to changes.
+fit_svs(
+ metab,
+ 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 = "tCr",
+ ecc = FALSE,
+ hsvd_width = 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,
+ verbose = FALSE
+)path or mrs_data object containing MRS metabolite data.
path or mrs_data object containing MRS water reference data.
directory path to output fitting results.
precompiled basis set object to use for analysis.
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).
Override automatic data format detection. See format argument
+in read_mrs() for permitted values.
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.
metabolite mrs data echo time in seconds. If not supplied this will +be guessed from the metab data file.
metabolite mrs data repetition time in seconds. If not supplied +this will be guessed from the metab data file.
PRESS or sLASER sequence timing parameter in seconds.
PRESS or sLASER sequence timing parameter in seconds.
sLASER sequence timing parameter in seconds.
STEAM mixing time parameter in seconds.
names of extra signals to add to the default basis. Eg +append_basis = c("peth", "cit"). Cannot be used with precompiled basis sets.
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.
perform simple frequency alignment to known reference peaks.
perform dynamic frequency and phase correction using the RATS +method.
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.
option to perform water reference based eddy current correction, +defaults to FALSE.
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.
options to pass to ABfit.
specify a subset of dynamics to analyse, for example +1:16 would only fit the first 16 dynamic scans.
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.
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.
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.
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.
output an additional table with a subset of +metabolite levels, eg c("tNAA", "tNAA/tCr", "tNAA/tCho", "Lac/tNAA").
perform temporal averaging with the specified block +size. Defaults to NULL, eg average across all dynamic scans.
a numerical 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).
output potentially useful information.
metab <- system.file("extdata", "philips_spar_sdat_WS.SDAT",
+ package = "spant")
+w_ref <- system.file("extdata", "philips_spar_sdat_W.SDAT",
+ package = "spant")
+if (FALSE) { # \dontrun{
+fit_result <- svs_1h_brain_analysis(metab, w_ref, "fit_res_dir")
+} # }
+R/fit_svs.R
+ fit_svs_gui.RdGUI interface for the standard SVS 1H brain analysis pipeline, this is a +work in progress, and not ready for serious use.
+fit_svs_gui()R/mrs_data_io.R
read_mrs.RdRead MRS data from a file.
+Read MRS data from the filesystem.
read_mrs(
- fname,
+ path,
format = NULL,
ft = NULL,
fs = NULL,
@@ -97,15 +97,16 @@ Read MRS data from a file.
Arguments
-- fname
-filename of the dpt format MRS data.
- 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.
- ft
@@ -191,7 +192,7 @@ Examples
R/amp_scaling.R
+ scale_amp_legacy.RdSee 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:
+scale_amp_legacy(fit_result, ref_data, w_att = 0.7, w_conc = 35880, ...)a result object generated from fitting.
water reference MRS data object.
water attenuation factor (default = 0.7). Assumes water T2 of +80ms and a TE = 30 ms. exp(-30ms / 80ms) ~ 0.7.
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.
a fit_result object with a rescaled results table.
"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."
+R/utils.R
+ sv_res_table.RdOutput a table of fit amplitudes and error estimates for a single-voxel fit.
+sv_res_table(fit_res, format_out = FALSE)data.frame of values.
+