Loading...
Searching...
No Matches
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, or undefined on error

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, or undefined on error

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, or undefined on error

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, or undefined on error

See also
  cpl_stats_get_min()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and CPL_STATS_MAX.

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.

See also
  cpl_stats_get_min_x()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, 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.

See also
  cpl_stats_get_min_x()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, 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, or undefined on error

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, 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.

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, or undefined on error

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, and CPL_STATS_MIN.

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
- 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, 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.

See also
  cpl_stats_get_min_x()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, 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 on error.

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, or non-positive on error

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 on error

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 on error

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().