Detrend Creation and Application

Data Structures
struct	pmOverscanOptions
	Options for overscan subtraction. More...
struct	pmDetrendSelectOptions
struct	pmDetrendSelectResults
struct	pmDetrendFileOptions
struct	pmFringeRegions
	Fringe measurement regions. More...
struct	pmFringeStats
	Fringe measurements for a particular image. More...
struct	pmFringeScale
	The fringe correction solution. More...
struct	pmShutterCorrection
	Shutter correction parameters, applicable for a single pixel. More...
Enumerations
enum	pmFit { PM_FIT_NONE, PM_FIT_POLY_ORD, PM_FIT_POLY_CHEBY, PM_FIT_SPLINE }
	Type of fit to perform. More...
enum	pmDetrendType { PM_DETREND_TYPE_MASK, PM_DETREND_TYPE_BIAS, PM_DETREND_TYPE_DARK, PM_DETREND_TYPE_FLAT, PM_DETREND_TYPE_FLAT_CORRECTION, PM_DETREND_TYPE_SHUTTER, PM_DETREND_TYPE_FRINGE_IMAGE, PM_DETREND_TYPE_FRINGE_TABLE, PM_DETREND_TYPE_BACKGROUND }
Functions
pmOverscanOptions *	pmOverscanOptionsAlloc (bool single, pmFit fitType, unsigned int order, psStats *stat)
	Allocator for overscan options.
bool	pmBiasSubtract (pmReadout *in, pmOverscanOptions *overscanOpts, const pmReadout *bias, const pmReadout *dark)
	Subtract the overscan, bias and/or dark.
psString	pmDetrendTypeToString (pmDetrendType type)
pmDetrendSelectOptions *	pmDetrendSelectOptionsAlloc (const char *camera, psTime time, pmDetrendType type)
pmDetrendSelectResults *	pmDetrendSelectResultsAlloc ()
pmDetrendSelectResults *	pmDetrendSelect (const pmDetrendSelectOptions *options, const pmConfig *config)
char *	pmDetrendFile (const char *detID, const char *classID, const pmConfig *config)
bool	pmFlatField (pmReadout *in, const pmReadout *flat)
	Apply flat field calibration to a readout.
bool	pmFlatNormalize (psVector **expFluxesPtr, psVector **chipGainsPtr, const psImage *bgMatrix)
	Normalize flat-field measurements.
pmFringeRegions *	pmFringeRegionsAlloc (int nPts, int dX, int dY, int nX, int nY)
	Allocate fringe regions.
bool	pmFringeRegionsCreatePoints (pmFringeRegions *fringe, const psImage *image, psRandom *random)
	Generate the fringe points.
bool	pmFringeRegionsWriteFits (psFits *fits, psMetadata *header, const pmFringeRegions *regions, const char *extname)
	Write the regions to a FITS file.
pmFringeRegions *	pmFringeRegionsReadFits (psMetadata *header, const psFits *fits, const char *extname)
	Read the regions from a FITS file.
pmFringeStats *	pmFringeStatsAlloc (pmFringeRegions *regions)
	Allocate fringe statistics.
pmFringeStats *	pmFringeStatsMeasure (pmFringeRegions *fringe, const pmReadout *readout, psMaskType maskVal)
	Measure the fringe statistics for an image.
bool	pmFringeStatsWriteFits (psFits *fits, psMetadata *header, const pmFringeStats *fringe, const char *extname)
	Write the fringe stats for an image to a FITS table.
pmFringeStats *	pmFringeStatsReadFits (psMetadata *header, const psFits *fits, const char *extname, pmFringeRegions *regions)
	Read the fringe stats for an image from a FITS table.
pmFringeStats *	pmFringeStatsConcatenate (const psArray *fringes, const psVector *x0, const psVector *y0)
	Concatenate the fringe stats for several readouts into a single fringe stats.
bool	pmFringesFormat (pmCell *cell, psMetadata *header, const psArray *fringes)
	Write an array of fringes measurements to a FITS table.
psArray *	pmFringesParse (pmCell *cell)
	Parses an array of fringes measurements from a FITS table.
pmFringeScale *	pmFringeScaleMeasure (pmFringeStats *science, psArray *fringes, float rej, unsigned int nIter, float keepFrac)
	Measure the scales for the fringe correction.
pmFringeScale *	pmFringeScaleAlloc (int nFringeFrames)
	Allocate fringe scales.
psImage *	pmFringeCorrect (pmReadout *in, pmFringeRegions *fringes, psArray *fringeImages, psArray *fringeStats, psMaskType maskVal, float rej, unsigned int nIter, float keepFrac)
	Solve for and apply the fringe correction.
bool	pmMaskBadPixels (pmReadout *input, const pmReadout *mask, psMaskType maskVal)
	Applies the bad pixel mask to the input.
psImage *	pmMaskFlagSuspectPixels (psImage *out, const pmReadout *readout, float rej, psMaskType maskVal, float frac, psRandom *rng)
	Find pixels outlying from the background, flagging suspect pixels.
psImage *	pmMaskIdentifyBadPixels (const psImage *suspects, float thresh, psMaskType maskVal)
	Identify bad pixels from the suspect pixels image.
pmReadout *	pmNonLinearityPolynomial (pmReadout *in, const psPolynomial1D *coeff)
	Correct non-linearity through polynomial.
pmReadout *	pmNonLinearityLookup (pmReadout *in, const psVector *inFlux, const psVector *outFlux)
	Correct non-linearity through table lookup.
pmShutterCorrection *	pmShutterCorrectionAlloc ()
	Allocator for shutter correction parameters.
pmShutterCorrection *	pmShutterCorrectionGuess (const psVector *exptime, const psVector *counts)
	Guess a shutter correction, based on plot of counts vs exposure time.
pmShutterCorrection *	pmShutterCorrectionLinFit (const psVector *exptime, const psVector *counts, const psVector *cntError, const psVector *mask, float offref, int nIter, float rej, psMaskType maskVal)
	Generate shutter correction based on a linear fit.
pmShutterCorrection *	pmShutterCorrectionFullFit (const psVector *exptime, const psVector *counts, const psVector *cntError, const pmShutterCorrection *guess)
	Generate shutter correction based on a full non-linear fit.
psImage *	pmShutterCorrectionMeasure (const psArray *readouts, int size, psStatsOptions meanStat, psStatsOptions stdevStat, int nIter, float rej, psMaskType maskVal)
	Measure a shutter correction image from an array of images.
bool	pmShutterCorrectionApply (pmReadout *readout, const pmReadout *shutter)
	Apply a shutter correction.

---

Enumeration Type Documentation

enum pmDetrendType

Enumerator:

PM_DETREND_TYPE_MASK
PM_DETREND_TYPE_BIAS
PM_DETREND_TYPE_DARK
PM_DETREND_TYPE_FLAT
PM_DETREND_TYPE_FLAT_CORRECTION
PM_DETREND_TYPE_SHUTTER
PM_DETREND_TYPE_FRINGE_IMAGE
PM_DETREND_TYPE_FRINGE_TABLE
PM_DETREND_TYPE_BACKGROUND

Definition at line 25 of file pmDetrendDB.h.

enum pmFit

Type of fit to perform.

Enumerator:

PM_FIT_NONE	No fit.
PM_FIT_POLY_ORD	Fit ordinary polynomial.
PM_FIT_POLY_CHEBY	Fit Chebyshev polynomial.
PM_FIT_SPLINE	Fit cubic splines.

Definition at line 23 of file pmBias.h.

---

Function Documentation

bool pmBiasSubtract	(	pmReadout *	in,
		pmOverscanOptions *	overscanOpts,
		const pmReadout *	bias,
		const pmReadout *	dark
	)

Subtract the overscan, bias and/or dark.

Subtracts the overscan, as measured from the bias member of the input readout (if options are non-NULL), bias (if non-NULL) and dark (if non-NULL) scaled by the CELL.DARKTIME concept.

Parameters:

in	Input readout, to be overscan/bias/dark corrected
overscanOpts	Options for overscan subtraction, or NULL
bias	Bias image to subtract, or NULL
dark	Dark image to scale and subtract, or NULL

char* pmDetrendFile	(	const char *	detID,
		const char *	classID,
		const pmConfig *	config
	)

pmDetrendSelectResults* pmDetrendSelect	(	const pmDetrendSelectOptions *	options,
		const pmConfig *	config
	)

pmDetrendSelectOptions* pmDetrendSelectOptionsAlloc	(	const char *	camera,
		psTime	time,
		pmDetrendType	type
	)

pmDetrendSelectResults* pmDetrendSelectResultsAlloc

(

)

psString pmDetrendTypeToString

(

pmDetrendType

type

)

bool pmFlatField	(	pmReadout *	in,
		const pmReadout *	flat
	)

Apply flat field calibration to a readout.

This function applies the flat field calibration to the input readout. Support is available for different image types, though the input and flat images must have the same type. The relative offsets between the input and flat images is determined from the readout row0,col0 and the CELL.X0 and CELL.Y0 concepts. Normalisation of the flat is left as the responsibility of the caller. Non-positive pixels in the flat are masked, if there is a mask present in the input readout.

Parameters:

in	Readout with input image
flat	Readout with flat image

bool pmFlatNormalize	(	psVector **	expFluxesPtr,
		psVector **	chipGainsPtr,
		const psImage *	bgMatrix
	)

Normalize flat-field measurements.

We have f_ij = g_i s_j where f_ij is the flux recorded for chip i and integration j, g_i is the gain for the i-th chip, s_j is the flux of the source in the j-th integration. An initial guess for the chip gains might be helpful, but is not necessary. The matrix of background measurements contains the background for the flat fields used in the combination, as a function of exposure (rows) and chip (columns). The exposure fluxes and chip gains are modified upon return with the solved values. Returns true if the solution converged.

Parameters:

expFluxesPtr	Flux in each exposure, or NULL; modified
chipGainsPtr	Initial guess of the chip gains or NULL; modified
bgMatrix	Background measurements: rows are exposures, cols are chips

psImage* pmFringeCorrect	(	pmReadout *	in,
		pmFringeRegions *	fringes,
		psArray *	fringeImages,
		psArray *	fringeStats,
		psMaskType	maskVal,
		float	rej,
		unsigned int	nIter,
		float	keepFrac
	)

Solve for and apply the fringe correction.

This is a wrapper around each of the fringe correction components to measure the fringe points, solve for the fringe correction, and apply the fringe correction. The input fringe images are modified (scaled by the solution coefficients in order to correct the science image). Returns the summed fringe image.

Parameters:

in	Input science image
fringes	The fringe regions used
fringeImages	Fringe template images to use in correction
fringeStats	Fringe stats (for templates) to use in correction
maskVal	Value to mask for science image
rej	Rejection threshold, for pmFringeScaleMeasure
nIter	Maximum number of iterations, for pmFringeScaleMeasure
keepFrac	Minimum fraction of regions to keep, for pmFringeScaleMeasure

pmFringeRegions* pmFringeRegionsAlloc	(	int	nPts,
		int	dX,
		int	dY,
		int	nX,
		int	nY
	)

Allocate fringe regions.

Parameters:

nPts	Number of fringe points to create
dX	Half-width of fringe boxes
dY	Half-height of fringe boxes
nX	Smoothing scale in x
nY	Smoothing scale in y

bool pmFringeRegionsCreatePoints	(	pmFringeRegions *	fringe,
		const psImage *	image,
		psRandom *	random
	)

Generate the fringe points.

Fringe points are generated randomly over the image. No effort is made to avoid masked regions (indeed, the function knows nothing about masks). If the random number generator is NULL, then a new one will be used.

Parameters:

fringe	Fringe regions to generate
image	Image for the regions (defines the size)
random	Random number generator, or NULL

pmFringeRegions* pmFringeRegionsReadFits	(	psMetadata *	header,
		const psFits *	fits,
		const char *	extname
	)

Read the regions from a FITS file.

The fringe regions are read from the FITS file, at the given extension name. The scalars are retrieved from the header, while the table provides the fringe coordinates and mask.

Parameters:

header	Header to read, or NULL
fits	Input FITS file
extname	Extension name, or NULL

bool pmFringeRegionsWriteFits	(	psFits *	fits,
		psMetadata *	header,
		const pmFringeRegions *	regions,
		const char *	extname
	)

Write the regions to a FITS file.

The fringe regions are written to the FITS file, with the given extension name. The header is supplemented with scalar values dX, dY, nX and nY (as PSFRNGDX, PSFRNGDY, PSFRNGNX, PSFRNGNY) from the fringe regions, while the fringe coordinates and mask are written as a FITS table (as x, y, mask).

Parameters:

fits	Output FITS file
header	Additional headers to write, or NULL
regions	Regions to write
extname	Extension name, or NULL

pmFringeScale* pmFringeScaleAlloc

(

int

nFringeFrames

)

Allocate fringe scales.

Parameters:

nFringeFrames

Number of fringe frames

pmFringeScale* pmFringeScaleMeasure	(	pmFringeStats *	science,
		psArray *	fringes,
		float	rej,
		unsigned int	nIter,
		float	keepFrac
	)

Measure the scales for the fringe correction.

Given a fringe measurement for a science image, and an array of template fringe measurements, this function measures the contribution of each of the templates to the input. Rejection is performed on the fringe regions, to weed out stars etc.

Parameters:

science	Fringe measurements from science image
fringes	Array of fringe measurements from templates
rej	Rejection threshold (in standard deviations)
nIter	Maximum number of iterations
keepFrac	Minimum fraction of regions to keep

bool pmFringesFormat	(	pmCell *	cell,
		psMetadata *	header,
		const psArray *	fringes
	)

Write an array of fringes measurements to a FITS table.

Writes an array of fringe measurements for a cell as a FITS table in the analysis metadata. The array of fringe statistics must all use the same fringe regions (or there is no point in storing them all together). The header is supplemented with scalar values dX, dY, nX and nY (as PSFRNGDX, PSFRNGDY, PSFRNGNX, PSFRNGNY) from the fringe regions, while the fringe coordinates and mask are written as a FITS table (as x, y, mask, f, df; f and df are vectors).

Parameters:

cell	Cell for which to write
header	Header, or NULL
fringes	Array of pmFringeStats, all for the same pmFringeRegion

psArray* pmFringesParse

(

pmCell *

cell

)

Parses an array of fringes measurements from a FITS table.

The fringes for the cell are read from the FITS table in the analysis metadata. The table provides the region and the (possibly multiple) fringe statistics for that region. The current extension is used if the extension name is not provided.

Parameters:

cell	Cell for which to read fringes

pmFringeStats* pmFringeStatsAlloc

(

pmFringeRegions *

regions

)

Allocate fringe statistics.

pmFringeStats* pmFringeStatsConcatenate	(	const psArray *	fringes,
		const psVector *	x0,
		const psVector *	y0
	)

Concatenate the fringe stats for several readouts into a single fringe stats.

Each readout of each chip must be measured separately (so as to avoid any gaps between the cells, as in the case for GPC). But the fit must be performed with all the readouts belonging to a chip (in order to get a secure measurement of the fringe amplitudes). To do so, we need to concatenate the fringe measurements for each of the chip components. This function generates a new pmFringeStats from concatenating those in the array. The corresponding pmFringeRegions is also generated.

Parameters:

fringes	Array of pmFringeStats for the readouts
x0	Offset in x for the readout
y0	Offset in y for the readout

pmFringeStats* pmFringeStatsMeasure	(	pmFringeRegions *	fringe,
		const pmReadout *	readout,
		psMaskType	maskVal
	)

Measure the fringe statistics for an image.

Given an input image and fringe regions at which to measure, measures the median and stdev at each of the fringe points. If the fringe points are undefined, they are generated.

Parameters:

fringe	Fringe regions at which to measure
readout	Readout for which to measure
maskVal	Mask value for image

pmFringeStats* pmFringeStatsReadFits	(	psMetadata *	header,
		const psFits *	fits,
		const char *	extname,
		pmFringeRegions *	regions
	)

Read the fringe stats for an image from a FITS table.

The fringe measurements are read from the FITS file, at the given extension name. The table provides the median and stdev measurements. It is assumed that the fringe measurements correspond to the regions provided.

Parameters:

header	Header to read, or NULL
fits	FITS file from which to read
extname	Extension name to read
regions	Corresponding regions

bool pmFringeStatsWriteFits	(	psFits *	fits,
		psMetadata *	header,
		const pmFringeStats *	fringe,
		const char *	extname
	)

Write the fringe stats for an image to a FITS table.

The fringe measurements are written to the FITS file with the given extension name. The median and stdev measurements are written as a FITS table (as f and df).

Parameters:

fits	FITS file to which to write
header	Additional headers to write, or NULL
fringe	Fringe statistics to be written
extname	Extension name for table

bool pmMaskBadPixels	(	pmReadout *	input,
		const pmReadout *	mask,
		psMaskType	maskVal
	)

Applies the bad pixel mask to the input.

Pixels marked as bad within the mask are marked as bad within the input image's mask. If maskVal is non-zero, all pixels in the mask have any of the same bits sets as maskVal shall have the corresponding bits raised. If maskVal is zero, any zero pixels in the mask are OR-ed with PM_MASK_BAD. Position offsets (such as due to trimming) between the input and mask are applied so that the same pixels are referred to. The science readout must already have a supplied mask element (use eg. pmReadoutSetMask). The supplied mask image must be of MASK type

Parameters:

input	Input science image
mask	Mask image to apply
maskVal	Mask value to apply

psImage* pmMaskFlagSuspectPixels	(	psImage *	out,
		const pmReadout *	readout,
		float	rej,
		psMaskType	maskVal,
		float	frac,
		psRandom *	rng
	)

Find pixels outlying from the background, flagging suspect pixels.

Pixels more than "rej" standard deviations from the background level (in flat-fielded, background-subtracted images) have the corresponding pixel in the "suspect pixels" image incremented. After accumulating over a suitable sample of images, bad pixels should have a high value in the suspect pixels image, allowing them to be identified. The suspect pixels image is of type S32.

Parameters:

out	Suspected bad pixels image, or NULL
readout	Readout to inspect
rej	Rejection threshold (standard deviations)
maskVal	Mask value for statistics
frac	Fraction of pixels to consider
rng	Random number generator

psImage* pmMaskIdentifyBadPixels	(	const psImage *	suspects,
		float	thresh,
		psMaskType	maskVal
	)

Identify bad pixels from the suspect pixels image.

Bad pixels are identified from the suspect pixels image (accumulated over a large number of images). Pixels marked as suspect in more than "thresh" standard deviations from the mean are identified as bad pixels (output image). If "thresh" is negative, a Poisson is assumed.

Parameters:

suspects	Accumulated suspect pixels image
thresh	Threshold for bad pixel (standard deviations)
maskVal	Value to set for bad pixels

pmReadout* pmNonLinearityLookup	(	pmReadout *	in,
		const psVector *	inFlux,
		const psVector *	outFlux
	)

Correct non-linearity through table lookup.

For each pixel in the input image, performs linear interpolation on the table (from the two vectors) to determine the corrected flux.

Parameters:

in	Input image, to correct
inFlux	Table column with input fluxes
outFlux	Table column with output fluxes

pmReadout* pmNonLinearityPolynomial	(	pmReadout *	in,
		const psPolynomial1D *	coeff
	)

Correct non-linearity through polynomial.

Applies a polynomial to the flux of each pixel in the input image to determine the corrected flux.

Parameters:

in	Input image, to correct
coeff	Polynomial for non-linearity correction

pmOverscanOptions* pmOverscanOptionsAlloc	(	bool	single,
		pmFit	fitType,
		unsigned int	order,
		psStats *	stat
	)

Allocator for overscan options.

Parameters:

single	Reduce all overscan regions to a single value?
fitType	Type of fit to overscan
order	Order of polynomial, or number of splines
stat	Statistic to use

pmShutterCorrection* pmShutterCorrectionAlloc

(

)

Allocator for shutter correction parameters.

bool pmShutterCorrectionApply	(	pmReadout *	readout,
		const pmReadout *	shutter
	)

Apply a shutter correction.

Given a shutter correction (with dT for each pixel), applies this correction to an input image.

Parameters:

readout	Readout to which to apply shutter correction
shutter	Shutter correction readout, with dT for each pixel

pmShutterCorrection* pmShutterCorrectionFullFit	(	const psVector *	exptime,
		const psVector *	counts,
		const psVector *	cntError,
		const pmShutterCorrection *	guess
	)

Generate shutter correction based on a full non-linear fit.

Performs a full non-linear fit to counts as a function of exposure time. The main purpose is to solve for the reference time offset, so that future fits may be performed using linear fitting with the reference time offset fixed.

Parameters:

exptime	Exposure times for each exposure
counts	Counts for each exposure
cntError	Error in the counts
guess	Initial guess

pmShutterCorrection* pmShutterCorrectionGuess	(	const psVector *	exptime,
		const psVector *	counts
	)

Guess a shutter correction, based on plot of counts vs exposure time.

This function is used before doing the full non-linear fit, to get parameters close to the true. Assumes exptime vector is sorted (ascending order; longest is last) prior to input.

Parameters:

exptime	Exposure times for each exposure
counts	Counts for each exposure

pmShutterCorrection* pmShutterCorrectionLinFit	(	const psVector *	exptime,
		const psVector *	counts,
		const psVector *	cntError,
		const psVector *	mask,
		float	offref,
		int	nIter,
		float	rej,
		psMaskType	maskVal
	)

Generate shutter correction based on a linear fit.

Performs a linear fit to counts as a function of exposure time, with the reference time offset fixed (so that the system is linear). Performs iterative clipping, if nIter > 1.

Parameters:

exptime	Exposure times for each exposure
counts	Counts for each exposure
cntError	Error in the counts
mask	Mask for each exposure
offref	Reference time offset
nIter	Number of iterations
rej	Rejection threshold (sigma)
maskVal	Mask value

psImage* pmShutterCorrectionMeasure	(	const psArray *	readouts,
		int	size,
		psStatsOptions	meanStat,
		psStatsOptions	stdevStat,
		int	nIter,
		float	rej,
		psMaskType	maskVal
	)

Measure a shutter correction image from an array of images.

Given an array of readouts (with known exposure times from the cell concepts), this function measures the shutter correction (our principal concern is for the time offset, rather than the normalisation) by measuring the reference time offset using the full non-linear fit for a small number of representative regions (middle and corners), and then using that to perform a linear fit to each pixel.

Parameters:

readouts	Array of readouts
size	Size of samples for statistics for non-linear fit
meanStat	Statistic to use for mean
stdevStat	Statistic to use for stdev
nIter	Number of iterations
rej	Rejection threshold (sigma)
maskVal	Mask value

---