#include <sc_basic.h>
#include <sc_modsky.h>

Data Structures
struct	_scvars_

struct	_scpars_

#define	SC_DEFERRVAL 9.99

#define	SC_CORRFAC_MIN 0.01

#define	SC_CORRFAC_MAX 100.

#define	SC_MINNLIN 3

#define	SC_MAXRELFAC 2.

#define	SC_MAXPARERR 0.5

typedef struct _scvars_	scvars

typedef struct _scpars_	scpars

int	nfev

cpl_boolean	lastcall

cpl_error_code	sc_mpfit (mp_result result, cpl_table scispec, cpl_table skyspec, cpl_table fitpar, const cpl_parameterlist *parlist)

int	sc_mpfit_calcdev (int m, int n, double p, double dy, double *dvec, void vars)

cpl_error_code	sc_mpfit_modinitpar (cpl_table fitpar, cpl_table scispec, cpl_table skyspec, const cpl_parameterlist parlist)

cpl_error_code	sc_mpfit_setpar (scpars fitpars, const cpl_table fitpar, const char fittype)

cpl_error_code	sc_mpfit_allocmempar (scpars *fitpars, const int npar)

cpl_error_code	sc_mpfit_freemempar (scpars *fitpars)

cpl_error_code	sc_mpfit_allocmemresult (mp_result *result, const int m, const int n)

cpl_error_code	sc_mpfit_initresult (mp_result *result, const int m, const int n)

cpl_error_code	sc_mpfit_copyresult (mp_result outresult, const mp_result inresult)

cpl_error_code	sc_mpfit_freememresult (mp_result *result)

cpl_error_code	sc_mpfit_substbadfitpar (cpl_table fitpar, const cpl_table initfitpar, const cpl_parameterlist *parlist)

Detailed Description

Header for routines related to the handling of CMPFIT

Author: Stefan Noll & ESO In-Kind Team Innsbruck

Since: 17 Feb 2011

Date: 24 Feb 2014

Definition in file sc_mpfit.h.

Macro Definition Documentation

◆ SC_CORRFAC_MAX

#define SC_CORRFAC_MAX 100.

Maximum correction factor for line groups

Definition at line 69 of file sc_mpfit.h.

◆ SC_CORRFAC_MIN

#define SC_CORRFAC_MIN 0.01

Minimum correction factor for line groups

Definition at line 67 of file sc_mpfit.h.

◆ SC_DEFERRVAL

#define SC_DEFERRVAL 9.99

Default error value (taken if no specific error is available)

Definition at line 65 of file sc_mpfit.h.

◆ SC_MAXPARERR

#define SC_MAXPARERR 0.5

Maximum relative uncertainty of fit parameters for line flux correction (otherwise the initial parameter value is taken)

Definition at line 77 of file sc_mpfit.h.

◆ SC_MAXRELFAC

#define SC_MAXRELFAC 2.

Maximum relative deviation between correction factor of a system A group with less than SC_MINNLIN lines and the system mean

Definition at line 74 of file sc_mpfit.h.

◆ SC_MINNLIN

#define SC_MINNLIN 3

Minimum number of valid lines for a save line group

Definition at line 71 of file sc_mpfit.h.

Typedef Documentation

◆ scpars

typedef struct _scpars_ scpars

Structure for holding the fit parameters and their constraints

Parameters

n	number of parameters
p	parameter vector for fitting
pars	structure for parameter constraints

◆ scvars

typedef struct _scvars_ scvars

Structure for holding the spectral data and the driver file parameters

Parameters

scispec	CPL table with science spectrum
skyspec	CPL table with sky spectrum and line group weights
fitpar	CPL table with fit parameters
sinc	CPL vector with damped sinc kernel
parlist	general CPL parameter list

Function Documentation

◆ sc_mpfit()

cpl_error_code sc_mpfit	(	mp_result *	result,
		cpl_table *	scispec,
		cpl_table *	skyspec,
		cpl_table *	fitpar,
		const cpl_parameterlist *	parlist
	)

Handles the fitting routine CMPFIT (see mpfit.c for details on the fitting algorithm).

Needs the science line spectrum plus error-related weights, the sky line spectrum plus error-related and line group weights, and descriptions, fit flags, and initial values of the fit parameters provided by a dedicated table and the general parameter list.

The input data are used to compute a modified sky line spectrum which is compared to the science line spectrum by deriving a vector of weighted deviations. The sky spectrum is optimised by an initial estimate of line group specific correction factors from the ratio of science and sky line spectrum for selected, suitable line pixels. As next step this estimate is repeated to improve the clipping of unsuitable pixels. Finally, CMPFIT is called for a selection of line group fit parameters which were flagged as crucial for a further fit improvement by the previous flux correction estimate.

The agreement of the wavelength grids of the science and sky spectrum is improved by the fit of a Chebyshev polynomial by means of CMPFIT. For obtaining an optimal polynomial the degree is increased iteratively. For this reason, the fit plan described above is usually repeated multiple times. After the first cycle the initial estimate is substituted by the fit of the wavelength grid. In each run the degree of the Chebyshev polynomial for the wavelength correction is increased by 1 (exception: constant and linear term are considered together) and the best-fit parameters of the previous run are used as input. If ${\chi^2}$ becomes worse or improves by less than the relative value wtol, the loop is stopped and the best results of the previous iterations are finally taken. Otherwise the procedure runs until the maximum degree given by the parameter cheby_max is reached. Moreover, the parameter cheby_min defines a minimum degree for which a fit is performed. If cheby_min is greater than cheby_max. A mode is applied which returns the results for the degree cheby_max, even if the ${\chi^2}$ is lower for an iteration with a smaller degree.

Information on the fit quality is written into a special results structure. The CPL table with the science line spectrum is supplemented by the best-fit sky line spectrum and the weighted deviations taken for the ${\chi^2}$ computation. Moreover, an ASCII file which summarises the fit results (fit quality, run time, and best-fit parameter values plus uncertainties) is written.

INPUT:

Parameters

scispec	CPL table with science spectrum
skyspec	CPL table with sky spectrum and line group weights
fitpar	CPL table of fit parameters
parlist	general CPL parameter list

OUTPUT:

Parameters

result	CMPFIT structure for fit results
scispec	CPL table with science and best-fit modified sky spectrum
fitpar	fit parameter table with best-fit values

ERRORS:

Insufficient memory
Error in subroutine

Definition at line 60 of file sc_mpfit.c.

References lastcall, sc_basic_calcsinc(), sc_basic_copytable_content(), SC_DEFERRVAL, SC_LENLINE, SC_MAXLEN, sc_modsky(), sc_mpfit_allocmempar(), sc_mpfit_allocmemresult(), sc_mpfit_calcdev(), sc_mpfit_copyresult(), sc_mpfit_freemempar(), sc_mpfit_freememresult(), sc_mpfit_initresult(), sc_mpfit_modinitpar(), sc_mpfit_setpar(), and sc_mpfit_substbadfitpar().

Referenced by sc_skycorr_fit().

◆ sc_mpfit_allocmempar()

cpl_error_code sc_mpfit_allocmempar	(	scpars *	fitpars,
		const int	npar
	)

Allocates memory for an scpars structure.

INPUT:

Parameters

npar	number of fit parameters

OUTPUT:

Parameters

fitpars scpars structure containing npar fit parameters

ERRORS:

Insufficient memory

Definition at line 1264 of file sc_mpfit.c.

References SC_LENLINE, and SC_MAXLEN.

Referenced by sc_mpfit().

◆ sc_mpfit_allocmemresult()

cpl_error_code sc_mpfit_allocmemresult	(	mp_result *	result,
		const int	m,
		const int	n
	)

Allocates memory for fit residuals and parameter errors in the CMPFIT results structure.

INPUT:

Parameters

m	number of data points
n	number of parameters

OUTPUT:

Parameters

result CMPFIT structure for fit results with allocated memory for residuals and parameter errors

ERRORS:

Insufficient memory

Definition at line 1373 of file sc_mpfit.c.

References SC_MAXLEN.

Referenced by sc_mpfit().

◆ sc_mpfit_calcdev()

int sc_mpfit_calcdev	(	int	m,
		int	n,
		double *	p,
		double *	dy,
		double **	dvec,
		void *	vars
	)

User function for CMPFIT. Provides spectral data and fit parameters to sc_modsky. Gets weighted deviations between the modified sky line spectrum and the science line spectrum from sc_modsky. The syntax of the function is predefined by CMPFIT.

INPUT:

Parameters

m	number of data points
n	number of parameters
p	array of fit parameters
dvec	derivatives (not used)
vars	private data -> observed spectrum and driver file parameters

OUTPUT:

Parameters

dy	array of residuals ([model - obs. spectrum] * weight)

ERRORS:

none

Definition at line 517 of file sc_mpfit.c.

References nfev, and sc_modsky().

Referenced by sc_mpfit().

◆ sc_mpfit_copyresult()

cpl_error_code sc_mpfit_copyresult	(	mp_result *	outresult,
		const mp_result *	inresult
	)

Copies content of CMPFIT structure for fit results.

INPUT:

Parameters

inresult CMPFIT structure for fit results

OUTPUT:

Parameters

outresult copied CMPFIT structure for fit results

ERRORS:

none

Definition at line 1461 of file sc_mpfit.c.

Referenced by sc_mpfit().

◆ sc_mpfit_freemempar()

cpl_error_code sc_mpfit_freemempar ( scpars * fitpars )

Frees memory occupied by an scpars structure.

INPUT:

Parameters

fitpars scpars structure with fit parameters

OUTPUT:

Parameters

fitpars scpars structure without allocated memory

ERRORS:

none

Definition at line 1333 of file sc_mpfit.c.

Referenced by sc_mpfit().

◆ sc_mpfit_freememresult()

cpl_error_code sc_mpfit_freememresult ( mp_result * result )

Frees memory occupied by a CMPFIT structure for fit residuals and parameter errors. Memory allocated for carrying the covariance matrix is not freed.

INPUT:

Parameters

result CMPFIT structure for fit results with allocated memory for residuals and parameter errors

OUTPUT:

Parameters

result CMPFIT structure for fit results without memory for residuals and parameter errors

ERRORS:

none

Definition at line 1502 of file sc_mpfit.c.

Referenced by sc_mpfit(), and sc_skycorr_fit().

◆ sc_mpfit_initresult()

cpl_error_code sc_mpfit_initresult	(	mp_result *	result,
		const int	m,
		const int	n
	)

Initialises CMPFIT structure for fit results.

INPUT:

Parameters

result	CMPFIT structure for fit results
m	number of data points
n	number of parameters

OUTPUT:

Parameters

result initialised CMPFIT structure for fit results

ERRORS:

none

Definition at line 1420 of file sc_mpfit.c.

Referenced by sc_mpfit().

◆ sc_mpfit_modinitpar()

cpl_error_code sc_mpfit_modinitpar	(	cpl_table *	fitpar,
		cpl_table *	scispec,
		cpl_table *	skyspec,
		const cpl_parameterlist *	parlist
	)

Optimises initial fit parameters for line groups by considering the mean ratio of group-specific line fluxes in the science and sky spectrum. The pixels identified as line peaks in the science spectrum (see sc_specdiss_find_emissionlines) and those at a distance of not more than FWHM / 2 (computed by sc_fwhmest) from these peaks are taken for the ratio calculation only. Moreover, outliers (e.g. object lines) indicating a deviation of the ratio of more than siglim ${\sigma}$ (see input parameter list) from the mean ratio of the line peaks (as computed by sc_basic_clipmean) are excluded. Then, only those lines are used that dominate a spectrum pixel by a weight of at least the value of the input parameter weightlim. This criterion is separately applied to A and B line groups. A ${\sigma}$ -clipping procedure using sc_basic_clipmean is also performed for the pixels of each group. If the resulting clipped pixels of a line outnumber the valid ones by a factor of 2 and more, the entire line is clipped. If it turns out that a line group does not have suitable lines for estimating the line correction factor, the mean ratio of all lines is taken for A groups and a value of 1 is taken for B groups.

The routine prepares the use of CMPFIT. Apart from the start values for the line flux correction factors, the selected line peak pixels are also set for the fitting procedure. No other pixels are considered for the ${\chi^2}$ calculation. Moreover, it is decided which parameters are flagged as free and which parameters are hold. Line groups for which the initial estimate failed are also not considered for the fitting procedure. On the other hand, the user can influence the selection by the parameter fitlim which only selects line groups that indicate a ratio of RMS to mean correction factor of at least the value given. Consequently, the fitting can be carried out for the uncertain but fittable groups only.

INPUT:

Parameters

fitpar	CPL table of fit parameters
scispec	CPL table with science spectrum
skyspec	CPL table with sky spectrum
parlist	input CPL parameter list

OUTPUT:

Parameters

fitpar fit parameter table with adapted start values for line groups

ERRORS:

none

Definition at line 577 of file sc_mpfit.c.

References sc_basic_clipmean(), SC_CORRFAC_MAX, SC_CORRFAC_MIN, SC_DEFERRVAL, SC_LENLINE, SC_MAXRELFAC, and SC_MINNLIN.

Referenced by sc_mpfit().

◆ sc_mpfit_setpar()

cpl_error_code sc_mpfit_setpar	(	scpars *	fitpars,
		const cpl_table *	fitpar,
		const char	fittype
	)

Provides a vector of parameters which are variables of the CMPFIT fitting process. Moreover, constraints for these parameters are delivered by the CMPFIT structure mp_par. Both objects are returned by a container structure. The parameter information is taken from the fit parameter table fitpar. The input parameter fittype decides whether line groups ('l') or the wavelength grid ('w') are fitted.

INPUT:

Parameters

fitpar	CPL table of fit parameters
fittype	'l' for line groups or 'w' for wavelength grid

OUTPUT:

Parameters

fitpars structure containing the fit parameters

ERRORS:

Inconsistent data grids

Definition at line 1186 of file sc_mpfit.c.

References SC_CORRFAC_MAX, SC_CORRFAC_MIN, SC_LENLINE, SC_MAXLEN, and SC_TOL.

Referenced by sc_mpfit().

◆ sc_mpfit_substbadfitpar()

cpl_error_code sc_mpfit_substbadfitpar	(	cpl_table *	fitpar,
		const cpl_table *	initfitpar,
		const cpl_parameterlist *	parlist
	)

Substitutes bad fits of flux correction factors by value of initial estimate. Bad fits are recognised by a relative uncertainty greater than SC_MAXPARERR. If the A group fits of a system are identified as bad, then all B group fits of this system are also rejected. On the other hand, B groups are not touched if the A group fits of the same system are sufficiently good. The fit uncertainties of the substituted parameters are set to SC_DEFERRVAL.

INPUT:

Parameters

fitpar	CPL table with best fit parameters
initfitpar	CPL table with initial estimates of fit parameters
parlist	general CPL parameter list

OUTPUT:

Parameters

fitpar fit parameter table with initial estimates and no fit errors for substituted parameters

ERRORS:

none

Definition at line 1537 of file sc_mpfit.c.

References SC_DEFERRVAL, and SC_MAXPARERR.

Referenced by sc_mpfit().

Variable Documentation

◆ lastcall

cpl_boolean lastcall

extern

Last modsky call?

Definition at line 53 of file sc_mpfit.c.

Referenced by sc_modsky(), sc_modsky_moderrors(), sc_modsky_rebin(), and sc_mpfit().

◆ nfev

int nfev

extern

Number of fitting function calls

Definition at line 51 of file sc_mpfit.c.

Referenced by sc_modsky_modlines(), sc_modsky_modwavegrid(), and sc_mpfit_calcdev().

Data Structures

Detailed Description

Macro Definition Documentation

◆ SC_CORRFAC_MAX

◆ SC_CORRFAC_MIN

◆ SC_DEFERRVAL

◆ SC_MAXPARERR

◆ SC_MAXRELFAC

◆ SC_MINNLIN

Typedef Documentation

◆ scpars

◆ scvars

Function Documentation

◆ sc_mpfit()

◆ sc_mpfit_allocmempar()

◆ sc_mpfit_allocmemresult()

◆ sc_mpfit_calcdev()

◆ sc_mpfit_copyresult()

◆ sc_mpfit_freemempar()

◆ sc_mpfit_freememresult()

◆ sc_mpfit_initresult()

◆ sc_mpfit_modinitpar()

◆ sc_mpfit_setpar()

◆ sc_mpfit_substbadfitpar()

Variable Documentation

◆ lastcall

◆ nfev