FITMAN Chapter 2.4 - dwong263/MAGIQ GitHub Wiki

*.cst File Format

The constraints which are placed on the fitting procedure and individual peaks must be specified in a separate ASCII file with the *.cst extension. The constraints section of the file must begin with:

****_Constraints_File_Begins_****

and end with:

****_Constraints_File_Ends_****

Constraint File Sections

The constraints file contains three distinct sections called:

[Parameters]

[Variables]

[Peaks]

Each section contains specific information which is interpreted by the fitting routine.

[Parameters] Section

The [Parameters] sections contains the following:

Parameter Description Default
shift_units <s> Specifies the units for offsets to shift values in the constraints file. Two choices are available hz or ppm. ppm
output_shift_units <s> Specifies the units of the output shift values. The constraints portion of th output file will appear as in the original constraints file. The output_shift_units parameter affects only the guess portion of the output file. Two choices are available hz or ppm. Hz
tolerance <n> Specifies the % change in chi squared value between iterations which must be achieved before the fit is completed. The routine must be repeated “minimum_iterations” before the fit completes. 0.001
noise_points <n> Specifies the number of points at end of file used to calculate the standard deviation of the noise. The default is set at 32. 32
fixed_noise Specifies a fixed value for the standard deviation of the noise. If this is encountered the noise is not calculated from the data file but is taken to be the value specified. inactive
alambda_increment <n> Specifies the multiplicative factor used to increment alambda. 10
alambda_decrement <n> Specifies the multiplicative factor used to decrement alambda. 10
number_peaks <n> Specifies the number of peaks use in the fitting. 0
fwhm_exp_weighting <n> Specifies the full-width half-maximum (FWHM) of the exponential weighting function. This can be applied to data fit in the time or frequency domain (although it is handled differently in each domain). 0
maximum_iterations <n> Specifies the maximum number of iterations which will be executed before the fit is terminated. If this is achieved the current paramter values are retained in the output file. 50
minimum_iterations <n> Specifies the minimum number of iterations which must meet the tolerance level in order for the fit to be completed. 5
positive_amplitudes This flag force all amplitudes to be positive. This is identical to using the >0 boundary condition following each amplitude parameter. inactive
noise_equal This flag forces the noise in each the real and imaginary channel to be equal. Since the noise is calculated independantly for each channel they may be slightly different. The noise in each channel is taken to be the average of the noise in the two channels calculated independently. inactive
fix_all_shift This flag fixes all the shifts to values specified in the guess file. This is equivalent to placing the @ symbol in front of the first curly bracket defining each shift parameter inactive
fix_all_delay_time This flag fixes all the delay times to values specified in the guess file. This is equivalent to placing the @ symbol in front of the first curly bracket defining each delay time parameter. inactive
fix_all_l_width This flag fixes all the Lorentzian widths to values specified in the guess file. This is equivalent to placing the @ symbol in front of the first curly bracket defining each Lorentzian width parameter. inactive
fix_all_g_width This flag fixes all the Gaussian widths to values specified in the guess file. This is equivalent to placeing the @ symbol in front of the first curly bracket defining each Gaussian width parameter. inactive
fix_all_phase This flag fixes all the phases to values specified in the guess file. This is equivalent to placing the @ symbol in front of the first curly bracket defining each phase parameter. inactive
fix_all_amplitude This flag fixes all the amplitudes to values specified in the guess file. This is equivalent to placing the @ symbol in front of the first curly bracket defining each amplitude parameter. inactive
range <n> <n> Specifies the range of points over which to fit if fitting is done in the time domain. If fitting is done in the frequency domain, this specifies the range of points of time domain data which are fourier transformed to the frequency domain. 1 256
qrt_sin_weighting_range <n> <n> Specifies the range over which to apply the quarter sine weighting function at the beginning of the data. 0 0
zero_fill <n> Specifies the number of points to zero fill to if fitting in the frequency domain. 1024
frequency_range <n> <n> Specifies the frequency range over which to fit when fitting in the frequency domain. This value is specified in Hz. Values must be entered in “reverse” order since by convention the spectral frequency axis is positive on the left and negative on the right. Therefore to fit the majority of the 1H spectrum at 4T the following would be specified: frequency_range 0 -400. 0 0

[Variables] Section

The [Variables] section contains the following:

<s>  <n>

where <s> specifies the variable name and <n> specifies the value assigned to it.

[Peaks] Section

Assigning Variables to Peaks

The [Peaks] section contains the following:

;PEAK#  SHIFT     LORENTZIAN WIDTH    AMPLITUDE    PHASE    DELAY     GAUSSIAN WIDTH
1       {shift1} {lorentzian_width1} {amplitude1} {phase1} {delay1} {Gaussian_width1}

repeated for every peak.

The semi-colon identifies a remark and forces the parsing routine to ignore this line.

Linking to Other Peaks

The strings within the curly brackets identify the variable name used for linking. Therefore any other peak can be linked to the above peak parameters by specifying the same string. Offsets can also be used for linking. For example the second peak and third peaks could be constrained as follows:

2   {shift2} {lorentzian_width2} {amplitude1}*2 {phase1} {delay1} {Gaussian_width2}
3   {shift3} {lorentzian_width3} {amplitude1}   {phase1} {delay1} {Gaussian_width3}

This is interpreted as follows. Since each peak has a different string to constrain SHIFT these will be fit as independent parameters. The same is true for LORENTZIAN WIDTH and GAUSSIAN WIDTH parameters. The amplitude strings for all three peaks are the same, although the amplitude for peak two is scaled by a factor of 2. Therefore this identifies a triplet with the amplitude ratios 1:2:1. Similarly, since the PHASE and DELAY strings are the same for all three peaks, they are all linked. Since no offsets are provided for these parameters, they will all have the same value.

Linking Offsets

When linking parameters the following functions can be used:

Parameter Function
SHIFT + or -
LORENTZIAN WIDTH + or -
AMPLITUDE * or /
PHASE + or -
DELAY + or -
GAUSSIAN WIDTH + or -

Multiple arguments can also be use as long as no spaces separate them. For example:

{shift1}+-0.5+0.1

This will be resolved to {shift1}-0.4.

Fixing Peak Values

Any peak parameter can be fixed to the value specified for the corresponding peak in the guess file by placing an @ sign in front of the first curly bracket of the parameter constraint. For example:

4   @{shift3} @{lorentzian_width3} @{amplitude1} @{phase1} @{delay1} @{Gaussian_width3}

This fixed the value of each parameter to the corresponding guess in the guess file. It makes no difference what the strings are within the curly brackets (these are ignored).

Imposing Limits on Parameter Values

Limits may also be specified for specific parameters using the > or < symbols. This ensures that parameters will not exceed the specified values in the fitting. If a limit is exceeded, the parameter is removed from the fit and the entire fit is restarted using the current set of parameter values as the initial guess. A message to this effect is given during the fit (i.e. peak 1 parameter 3 has exceeded minimum bounds). Parameters are removed from the fit according to the following rules:

4   @{shift3} @{lorentzian_width3} {amplitude1} >0 @{phase1} @{delay1} @{Gaussian_width3}
Parameter Rule
SHIFT parameters The entire peak is removed from the fit
AMPLITUDE parameters The entire peak is removed from the fit
PHASE parameters The entire peak is removed from the fit
DELAY parameters The entire peak is removed from the fit
LORENTZIAN WIDTH parameters Lorentzian width is fixed to zero. If Gaussian width is also fixed to zero the peak is removed
GAUSSIAN WIDTH parameters Gaussian width is fixed to zero. If Lorentzian width is also fixed to zero the peak is removed
⚠️ **GitHub.com Fallback** ⚠️