Signal definition
The dialog records the model name, nucleus, resonance frequency, ppm value at the spectral center, number of complex samples, acquisition bandwidth, and first-order phase.
Expert page for NMR/MR spectroscopy knowledgeable users
TDFDFit Modelling Frame
The TDFDFit modelling frame is one of the key expert interfaces in spectrIm-QMRS. It is used to construct, inspect, constrain, optimize, and save prior-knowledge models that can later be applied to clinical or research MRS and MRSI datasets.
This page is intended for spectroscopists and users with solid NMR/MR spectroscopy knowledge. Clinical users are advised to start with the automatic TDFDFit model creator.
Purpose
TDFDFit is the default spectrIm-QMRS fitting engine for prior-knowledge based quantification. It performs nonlinear least-squares fitting of MR spectra using model components that can encode known resonance positions, linewidth behavior, phase relations, amplitude ratios, and basis-set information.
The modelling frame is where these models are created. It allows a spectroscopy expert to start from a measured prototype spectrum, add spectral components, define constraints, optimize the model, and then save a TDFDFit model that can be reused for comparable datasets measured with the same nucleus, field strength, sequence, and acquisition settings.
In version 3.0.1 Alpha this expert GUI remains important, but it is complemented by the new automatic TDFDFit model creator and the ILV basis set simulator. Those newer workflows are intended to make clinically useful models easier to generate when a dedicated MRS spectroscopist is not available.
The older expert route for loading externally simulated MRUI numeric basis patterns is preserved on the TDFDFit basis-set loading walkthrough.
Models created here, or generated by the automatic model creator, can be used by the Parallel pthreads-TDFDFit CPU fitting workflow.
Prior-Knowledge Modelling Window
When a new TDFDFit model is created from the spectrIm-QMRS menu or toolbar, the modelling frame first shows a metadata dialog for the loaded spectral dataset. These values are normally extracted from the DICOM MRS or MRSI data and should usually already form a valid starting point for a model.
Fitting preparation
The data truncation point and the number of points to ignore define how the beginning and end of the time-domain signal are handled during fitting. These settings influence spectral resolution, robustness, and computation time.
After applying these settings, the main modelling window becomes available. The left side contains the model tree and parameter editors; the right side displays the measured or prototype spectrum together with the current model response.
To be checked manually: these screenshots come from the older website documentation. They are still useful for explaining the modelling concept, but the exact version 3.0.1 Alpha toolbar layout should be refreshed with a current screenshot when available.
Adding Voigt Lines
A new model starts empty. It can be populated with several component types: Voigt lines, numeric patterns, parametric patterns, and metabolite objects. A Voigt line combines Lorentzian and Gaussian broadening and is a practical elementary component for building a prototype model directly from a measured spectrum.
The fastest manual workflow is to press the + Voigt
toolbar button and then click on the spectrum. The click position
defines the initial resonance position and amplitude of the new line.
Each added line appears both in the spectrum display and in the
model tree.
Repeating the same action at the visible peak positions creates an
initial prototype spectrum. The automatically assigned names such as
Line_01 can later be replaced by chemically meaningful
component names.
Once a reasonable initial model has been built, the
Optimize prototype model action fits the prototype model
to the selected spectrum. At this stage the fit may look visually
good, but the parameters may still be too unconstrained for reliable
quantification.
Why Prior Knowledge Is Needed
An unconstrained model has many degrees of freedom. It can often adapt very well to the measured spectrum, but a visually convincing fit does not guarantee that the fitted parameters are physically meaningful. Overlapping resonances, noise, baseline effects, and correlated parameters can produce fits that look plausible while reporting unstable or biased metabolite estimates.
Prior knowledge reduces this ambiguity by constraining parameters that are known from spectroscopy, sequence physics, or simulated basis sets. For example, an isolated Voigt line has five principal parameters. In a model with N independent Voigt lines this would imply roughly 5N free parameters. If relative frequency offsets, phase relations, linewidths, or amplitude ratios are known, the same model can often be fitted with far fewer independent parameters.
This reduces computation time and can lower the variance of fitted parameters, which is reflected in smaller Cramer-Rao bounds. The tradeoff is that incorrect prior knowledge can introduce bias. The modelling frame is therefore deliberately interactive: it lets an expert impose constraints, inspect the result, and decide whether the model still represents the physical spectrum.
Prior-Knowledge Editor
After the prototype spectrum is assembled, the prior-knowledge editor is used to define which parameters are free, fixed, or linked to another component. In the older example below, the editor region is highlighted in the modelling frame.
A practical first step is to rename generic model-tree entries to meaningful resonance or metabolite labels. This makes the later constraint definitions readable and reduces the chance of linking a parameter to the wrong reference component.
Prior knowledge is then defined separately for each parameter class.
A parameter can be left Free, kept unchanged by linking it
to itself, or linked to a reference component so that it follows the
fitted behavior of that reference parameter.
In this example, NAA is used as the reference component for several other resonances. This kind of linking can impose a common frequency shift, phase behavior, or linewidth behavior across multiple spectral components.
The constrained model is saved and optimized again. Because the model has fewer free parameters, the result may fit less flexibly than the unconstrained prototype, but the fitted parameters should be more interpretable when the prior knowledge is valid.
Selecting a component in the model tree updates the parameter editor and highlights the selected component in the spectrum display. This is the inspection step where the expert verifies whether linked offsets, phases, Lorentzian linewidths, Gaussian linewidths, and component amplitudes behave as intended.
How the Saved Model Is Used
When the optimized spectral model is satisfactory, it is saved as a reusable TDFDFit model. The model can then be applied to measured datasets of the same type, meaning comparable scanner field strength, nucleus, acquisition sequence, and measurement parameters.
In clinical workflows the model becomes the prior-knowledge template that the fitting engine applies to selected spectra or voxels. In research workflows it also provides an explicit, inspectable record of the assumptions used for quantification. The next workflow step is described on Applying predefined TDFDFit models to spectra. Expert users who start from externally simulated basis spectra can also review the manual basis-set loading walkthrough.