Statistics

Typedefs
typedef struct _cpl_stats_	cpl_stats
	The opaque CPL stats data type.
typedef enum _cpl_stats_mode_	cpl_stats_mode
	The CPL stats mode. It is a bit field.

Enumerations
enum	_cpl_stats_mode_ {   CPL_STATS_MIN ,   CPL_STATS_MAX ,   CPL_STATS_MEAN ,   CPL_STATS_MEDIAN ,   CPL_STATS_STDEV ,   CPL_STATS_FLUX ,   CPL_STATS_ABSFLUX ,   CPL_STATS_SQFLUX ,   CPL_STATS_MINPOS ,   CPL_STATS_MAXPOS ,   CPL_STATS_CENTROID ,   CPL_STATS_MEDIAN_DEV ,   CPL_STATS_MAD ,   CPL_STATS_ALL }
	The values of the CPL stats mode. The values can be combined with bitwise or. More...

Functions
void	cpl_stats_delete (cpl_stats *stats)
	Free memory associated to an cpl_stats object.
cpl_error_code	cpl_stats_dump (const cpl_stats *self, cpl_stats_mode mode, FILE *stream)
	Dump a cpl_stats object.
double	cpl_stats_get_absflux (const cpl_stats *in)
	Get the absolute flux from a cpl_stats object.
double	cpl_stats_get_centroid_x (const cpl_stats *in)
	Get the x centroid position from a cpl_stats object.
double	cpl_stats_get_centroid_y (const cpl_stats *in)
	Get the y centroid position from a cpl_stats object.
double	cpl_stats_get_flux (const cpl_stats *in)
	Get the flux from a cpl_stats object.
double	cpl_stats_get_mad (const cpl_stats *in)
	Get the median of the absolute median deviation.
double	cpl_stats_get_max (const cpl_stats *in)
	Get the maximum from a cpl_stats object.
cpl_size	cpl_stats_get_max_x (const cpl_stats *in)
	Get the maximum x position from a cpl_stats object.
cpl_size	cpl_stats_get_max_y (const cpl_stats *in)
	Get the maximum y position from a cpl_stats object.
double	cpl_stats_get_mean (const cpl_stats *in)
	Get the mean from a cpl_stats object.
double	cpl_stats_get_median (const cpl_stats *in)
	Get the median from a cpl_stats object.
double	cpl_stats_get_median_dev (const cpl_stats *in)
	Get the mean of the absolute median deviation from a cpl_stats object.
double	cpl_stats_get_min (const cpl_stats *in)
	Get the minimum from a cpl_stats object.
cpl_size	cpl_stats_get_min_x (const cpl_stats *in)
	Get the minimum x position from a cpl_stats object.
cpl_size	cpl_stats_get_min_y (const cpl_stats *in)
	Get the minimum y position from a cpl_stats object.
cpl_size	cpl_stats_get_npix (const cpl_stats *in)
	Get the number of pixels from a cpl_stats object.
double	cpl_stats_get_sqflux (const cpl_stats *in)
	Get the sum of the squared values from a cpl_stats object.
double	cpl_stats_get_stdev (const cpl_stats *in)
	Get the std. dev. from a cpl_stats object.
cpl_stats *	cpl_stats_new_from_image (const cpl_image *image, cpl_stats_mode mode)
	Compute various statistics of an image.
cpl_stats *	cpl_stats_new_from_image_window (const cpl_image *image, cpl_stats_mode mode, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
	Compute various statistics of an image sub-window.

Detailed Description

This module provides functions to handle the cpl_stats object. This object can contain the statistics that have been computed from different CPL objects. Currently, only the function that computes statistics on images (or images windows) is provided.

Synopsis:

#include "cpl_stats.h"

Typedef Documentation

cpl_stats

typedef struct _cpl_stats_ cpl_stats

The opaque CPL stats data type.

cpl_stats_mode

typedef enum _cpl_stats_mode_ cpl_stats_mode

The CPL stats mode. It is a bit field.

Enumeration Type Documentation

_cpl_stats_mode_

enum _cpl_stats_mode_

The values of the CPL stats mode. The values can be combined with bitwise or.

Enumerator
CPL_STATS_MIN	The minimum
CPL_STATS_MAX	The maximum
CPL_STATS_MEAN	The mean
CPL_STATS_MEDIAN	The median
CPL_STATS_STDEV	The standard deviation
CPL_STATS_FLUX	The flux
CPL_STATS_ABSFLUX	The absolute flux
CPL_STATS_SQFLUX	The square flux
CPL_STATS_MINPOS	The position of the minimum
CPL_STATS_MAXPOS	The position of the maximum
CPL_STATS_CENTROID	The centroid position
CPL_STATS_MEDIAN_DEV	The mean of the absolute median deviation
CPL_STATS_MAD	The median of the absolute median deviation
CPL_STATS_ALL	All of the above

Function Documentation

cpl_stats_delete()

void cpl_stats_delete

(

cpl_stats *

stats

)

Free memory associated to an cpl_stats object.

Parameters

stats

the object to delete

Returns

void

Frees all memory associated to a cpl_stats object. If the object stats is NULL, nothing is done and no error is set.

References cpl_free().

cpl_stats_dump()

cpl_error_code cpl_stats_dump	(	const cpl_stats *	self,
		cpl_stats_mode	mode,
		FILE *	stream
	)

Dump a cpl_stats object.

Parameters

self	cpl_stats object to dump
mode	Bit field specifying which statistics to dump
stream	The output stream

Returns

CPL_ERROR_NONE or the relevant the _cpl_error_code_

See also

cpl_stats_new_from_image_window()

It is an error to request parameters that have not been set.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL
• CPL_ERROR_ILLEGAL_INPUT if mode specifies statistics that have not been computed
• CPL_ERROR_FILE_IO if the write fails

References cpl_ensure_code, CPL_ERROR_FILE_IO, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, CPL_SIZE_FORMAT, CPL_STATS_ABSFLUX, CPL_STATS_CENTROID, CPL_STATS_FLUX, CPL_STATS_MAD, CPL_STATS_MAX, CPL_STATS_MAXPOS, CPL_STATS_MEAN, CPL_STATS_MEDIAN, CPL_STATS_MEDIAN_DEV, CPL_STATS_MIN, CPL_STATS_MINPOS, CPL_STATS_SQFLUX, and CPL_STATS_STDEV.

cpl_stats_get_absflux()

double cpl_stats_get_absflux

(

const cpl_stats *

in

)

Get the absolute flux from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

The absolute flux, or a negative number on error

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_ABSFLUX.

cpl_stats_get_centroid_x()

double cpl_stats_get_centroid_x

(

const cpl_stats *

in

)

Get the x centroid position from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the x centroid

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_CENTROID.

cpl_stats_get_centroid_y()

double cpl_stats_get_centroid_y

(

const cpl_stats *

in

)

Get the y centroid position from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the y centroid

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_CENTROID.

cpl_stats_get_flux()

double cpl_stats_get_flux

(

const cpl_stats *

in

)

Get the flux from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the flux

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_FLUX.

cpl_stats_get_mad()

double cpl_stats_get_mad

(

const cpl_stats *

in

)

Get the median of the absolute median deviation.

Parameters

in	the cpl_stats object

Returns

The median of the absolute median deviation, or undefined on error

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_MAD.

Referenced by cpl_image_get_mad(), and cpl_image_get_mad_window().

cpl_stats_get_max()

double cpl_stats_get_max

(

const cpl_stats *

in

)

Get the maximum from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the maximum value

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_STATS_MAX, and CPL_STATS_MAXPOS.

Referenced by cpl_image_normalise().

cpl_stats_get_max_x()

cpl_size cpl_stats_get_max_x

(

const cpl_stats *

in

)

Get the maximum x position from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the x position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_STATS_MAX, and CPL_STATS_MAXPOS.

Referenced by cpl_image_get_maxpos(), and cpl_image_get_maxpos_window().

cpl_stats_get_max_y()

cpl_size cpl_stats_get_max_y

(

const cpl_stats *

in

)

Get the maximum y position from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the y position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_STATS_MAX, and CPL_STATS_MAXPOS.

Referenced by cpl_image_get_maxpos(), and cpl_image_get_maxpos_window().

cpl_stats_get_mean()

double cpl_stats_get_mean

(

const cpl_stats *

in

)

Get the mean from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the mean value

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_MEAN.

cpl_stats_get_median()

double cpl_stats_get_median

(

const cpl_stats *

in

)

Get the median from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the median value

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_MEDIAN.

Referenced by cpl_image_get_mad(), cpl_image_get_mad_window(), cpl_image_get_median_dev(), and cpl_image_get_median_dev_window().

cpl_stats_get_median_dev()

double cpl_stats_get_median_dev

(

const cpl_stats *

in

)

Get the mean of the absolute median deviation from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

The mean of the absolute median deviation, or undefined on error

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_MEDIAN_DEV.

Referenced by cpl_image_get_median_dev(), and cpl_image_get_median_dev_window().

cpl_stats_get_min()

double cpl_stats_get_min

(

const cpl_stats *

in

)

Get the minimum from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the minimum value

The call that created the cpl_stats object must have determined the minimum value.

In case of error, the _cpl_error_code_ code is set, and the returned double is undefined.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL
• CPL_ERROR_ILLEGAL_INPUT if the requested stat has not been computed in in

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_STATS_MIN, and CPL_STATS_MINPOS.

Referenced by cpl_image_normalise().

cpl_stats_get_min_x()

cpl_size cpl_stats_get_min_x

(

const cpl_stats *

in

)

Get the minimum x position from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the x position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_STATS_MIN, and CPL_STATS_MINPOS.

Referenced by cpl_image_get_minpos(), and cpl_image_get_minpos_window().

cpl_stats_get_min_y()

cpl_size cpl_stats_get_min_y

(

const cpl_stats *

in

)

Get the minimum y position from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the y position (1 for the first pixel), non-positive on error.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_STATS_MIN, and CPL_STATS_MINPOS.

Referenced by cpl_image_get_minpos(), and cpl_image_get_minpos_window().

cpl_stats_get_npix()

cpl_size cpl_stats_get_npix

(

const cpl_stats *

in

)

Get the number of pixels from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the number of pixels, -1 in error case.

The creation of a cpl_stats object always causes the number of pixels to be determined.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

cpl_stats_get_sqflux()

double cpl_stats_get_sqflux

(

const cpl_stats *

in

)

Get the sum of the squared values from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the square flux, or a negative number on error

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_SQFLUX.

cpl_stats_get_stdev()

double cpl_stats_get_stdev

(

const cpl_stats *

in

)

Get the std. dev. from a cpl_stats object.

Parameters

in	the cpl_stats object

Returns

the standard deviation

See also

cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_STDEV.

cpl_stats_new_from_image()

cpl_stats * cpl_stats_new_from_image	(	const cpl_image *	image,
		cpl_stats_mode	mode
	)

Compute various statistics of an image.

Parameters

image	input image.
mode	Bit field specifying which statistics to compute

Returns

1 newly allocated cpl_stats structure or NULL in error case

See also

cpl_stats_new_from_image_window()

References cpl_ensure, CPL_ERROR_NULL_INPUT, and cpl_stats_new_from_image_window().

cpl_stats_new_from_image_window()

cpl_stats * cpl_stats_new_from_image_window	(	const cpl_image *	image,
		cpl_stats_mode	mode,
		cpl_size	llx,
		cpl_size	lly,
		cpl_size	urx,
		cpl_size	ury
	)

Compute various statistics of an image sub-window.

Parameters

image	Input image.
mode	Bit field specifying which statistics to compute
llx	Lower left x position (FITS convention)
lly	Lower left y position (FITS convention)
urx	Upper right x position (FITS convention)
ury	Upper right y position (FITS convention)

Returns

1 newly allocated cpl_stats structure or NULL in error case

Compute various image statistics.

The specified bounds are included in the specified region.

The statistics to compute is specified with a bit field, that may be set to any of these values

• CPL_STATS_MIN
• CPL_STATS_MAX
• CPL_STATS_MEAN
• CPL_STATS_MEDIAN
• CPL_STATS_MEDIAN_DEV
• CPL_STATS_MAD
• CPL_STATS_STDEV
• CPL_STATS_FLUX
• CPL_STATS_ABSFLUX
• CPL_STATS_SQFLUX
• CPL_STATS_CENTROID
• CPL_STATS_MINPOS
• CPL_STATS_MAXPOS or any bitwise or (|) of these. For convenience the special value CPL_STATS_ALL may also be used, it is the conbination of all of the above values.

E.g. the mode CPL_STATS_MIN | CPL_STATS_MEDIAN specifies the minimum and the median of the image.

In the case of CPL_STATS_MIN and CPL_STATS_MAX where more than one set of coordinates share the extremum it is undefined which of those coordinates will be returned.

On i386 platforms there can be significant differences in the round-off of the computation of single statistics and statistics computed via CPL_STATS_ALL. This is especially true for squared quantities such as the CPL_STATS_SQFLUX and CPL_STATS_STDEV.

Images can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT.

For the CPL_STATS_CENTROID computation, if there are negative pixels, the minimum value is added to all the pixels in order to have all pixels with positive values for computation.

The returned object must be deallocated using cpl_stats_delete().

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL
• CPL_ERROR_ACCESS_OUT_OF_RANGE if the defined window is not in the image
• CPL_ERROR_ILLEGAL_INPUT if the window definition is wrong (e.g llx > urx)
• CPL_ERROR_DATA_NOT_FOUND if all the pixels are bad
• CPL_ERROR_INVALID_TYPE if the passed image type is not supported
• CPL_ERROR_INVALID_TYPE if mode is 1, e.g. due to a logical or (||) of the allowed options.
• CPL_ERROR_UNSUPPORTED_MODE if mode is otherwise different from the allowed options.

References cpl_free(), and cpl_malloc().

Referenced by cpl_stats_new_from_image().