High-Level Data Reduction Library: hdrl_mode.c File Reference

High-Level Data Reduction Library 1.6.0 High-Level data reduction routines for ESO pipelines

Loading...
Searching...
No Matches
Macros | Functions
hdrl_mode.c File Reference
`#include "hdrl_mode.h"`
`#include "hdrl_sigclip.h"`
`#include "hdrl_utils.h"`
`#include "hdrl_collapse.h"`
`#include "hdrl_random.h"`
`#include <cpl.h>`
`#include <string.h>`
`#include <math.h>`
`#include <time.h>`
`#include <gsl/gsl_multifit.h>`
`#include <gsl/gsl_vector.h>`
`#include <gsl/gsl_histogram.h>`
`#include <gsl/gsl_poly.h>`
Include dependency graph for hdrl_mode.c:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros
#define | omp_get_max_threads() 1
#define | omp_get_thread_num() 0

## Functions
cpl_parameterlist * | hdrl_mode_parameter_create_parlist (const char *base_context, const char *prefix, const hdrl_parameter *defaults)
| Create parameters for the mode collapse.
cpl_error_code | hdrl_mode_parameter_parse_parlist (const cpl_parameterlist *parlist, const char *prefix, double *histo_min, double *histo_max, double *bin_size, hdrl_mode_type *method, cpl_size *error_niter)
| parse parameterlist for mode parameters to init corresponding hdrl structure parameters
hdrl_mode_compute_binsize
  determines 'optimal' histogram bin size Parameters
  vec | [input] data vector we adopt Scott's rule for determining the bin size of an histogram, multiplied by 2 and with STDDEV replaced by MAD
see Wikipedia: https://en.wikipedia.org/wiki/Histogram#Scott's_normal_reference_rule Returns histogram bin size
hdrl_mode_get_nbin
  computes the number of histogram bins Parameters
  min | histogram min value
  max | histogram max value
  size | bin size
hdrl_mode_histogram
  creates histogram Parameters
  vec | [input] data vector
  histo_min | [input] min data to be considered in histogram
  histo_max | [input] max data to be considered in histogram
  nbin | [input] number of bins in histogram
Returns GSL histogram or NULL in case of error Developer should make sure that nbin > 0
hdrl_mode_histogram_to_table
  computes histogram Parameters
  histogram | [input] histogram created by GSL
  histo_min | [input] min data to be considered in histogram
  histo_step | [input] histogram sampling step
  nbin | [input] number of bins in histogram
Returns output histogram: stored in a table with results in columns: # BIN: data values corresponding to each bin number # INTERVAL_LOWER: data values corresponding to the (lower) intensity of each bin # INTERVAL_UPPER: data values corresponding to the (upper) intensity of each bin # COUNTS: column counting how many data have intensity values corresponding to each bin intensity range Note this routine is useful for debugging (and visualization) purposes
cpl_error_code | hdrl_mode_clip_image (const cpl_image *source, const double histo_min, const double histo_max, const double bin_size, const hdrl_mode_type method, const cpl_size error_niter, double *mode, double *mode_error, cpl_size *naccepted)
| Compute mode of data.
cpl_error_code | hdrl_mode_clip (cpl_vector *vec, const double histo_min, const double histo_max, const double bin_size, const hdrl_mode_type method, const cpl_size error_niter, double *mode, double *mode_error, cpl_size *naccepted)
| Compute mode of data.
cpl_error_code | hdrl_mode_bootstrap (const cpl_vector *vec, const double histo_min, const double histo_max, const double bin_size, const hdrl_mode_type method, const cpl_size error_niter, double *mode_error)
| uses Montecarlo simulations based on the bootstrap technique to determine the error of the mode of the underlying distribution

## Macro Definition Documentation

## ◆ omp_get_max_threads

#define omp_get_max_threads | ( |  | ) | 1

## ◆ omp_get_thread_num

#define omp_get_thread_num | ( |  | ) | 0

## Function Documentation

## ◆ hdrl_mode_bootstrap()

cpl_error_code hdrl_mode_bootstrap | ( | const cpl_vector * | vec,
|  | const double | histo_min,
|  | const double | histo_max,
|  | const double | bin_size,
|  | const hdrl_mode_type | method,
|  | const cpl_size | error_niter,
|  | double * | mode_error
| ) |  |

uses Montecarlo simulations based on the bootstrap technique to determine the error of the mode of the underlying distribution

Parameters

  vec | input vector for the bootstrap simulations
  histo_min | minimum value of low pixels to use in the histogram
  histo_max | maximum value of high pixels to be use in the histogram
  bin_size | size of the histogram bin
  method | method to use for the mode computation
  error_niter | number of iterations to compute the error of the mode
  mode_error | returned error of the mode

Returns
  cpl_error_code

The returned mode error is the mad-based standard deviation of the simulations where simulations that did not converge where excluded a priori.

## ◆ hdrl_mode_clip()

cpl_error_code hdrl_mode_clip | ( | cpl_vector * | vec,
|  | const double | histo_min,
|  | const double | histo_max,
|  | const double | bin_size,
|  | const hdrl_mode_type | method,
|  | const cpl_size | error_niter,
|  | double * | mode,
|  | double * | mode_error,
|  | cpl_size * | naccepted
| ) |  |

Compute mode of data.

Parameters

  | vec | The data for which mode is to be computed.
  | histo_min | Min of histogram
  | histo_max | Max of histogram
  | bin_size | the histogram bin size
  | method | the mode computation method
  | error_niter | the number of iterations to determine error model
  [out] | mode | The mode
  [out] | mode_error | The error associated to the mode
  [out] | naccepted | the number of good data points

Returns
  `CPL_ERROR_NONE` or the appropriate error code.

The developer provide vec != NULL See also hdrl_mode_clip_image().

## ◆ hdrl_mode_clip_image()

cpl_error_code hdrl_mode_clip_image | ( | const cpl_image * | source,
|  | const double | histo_min,
|  | const double | histo_max,
|  | const double | bin_size,
|  | const hdrl_mode_type | method,
|  | const cpl_size | error_niter,
|  | double * | mode,
|  | double * | mode_error,
|  | cpl_size * | naccepted
| ) |  |

Compute mode of data.

Parameters

  | source | The data for which mode is to be computed.
  | histo_min | Min of histogram
  | histo_max | Max of histogram
  | bin_size | the histogram bin size
  | method | the mode computation method
  | error_niter | the number of iterations to determine error model
  [out] | mode | The mode
  [out] | mode_error | The error associated to the mode
  [out] | naccepted | the number of bins used to determine mode

Returns
  `CPL_ERROR_NONE` or the appropriate error code.

The developer provide source != NULL

The mode (or modal value) of a distribution of values is defined as the value of the distribution that appears more often (the maximum of the function distribution). This function computes the mode and the associated error for the case of a discrete distribution of points as defined by the input source image.

In the case of a discrete distribution, one can define the `modal class'' (the position of the highest peak of the histogram), and the`modal frequency" (the value of the highest peak of the histogram), which are related to the mode of the underlying continuous distribution. The values of histo_min/max can be changed to remove outliers or optimise computation time. The value of the modal frequency depends from the chosen bin size used to create the histogram and from statistical noise. Large bin size helps in finding an high and unique modal frequency, but decreases the resolution because the bin is large. A small bin increases the resolution of the modal class but decreases the modal frequency and therefore increases the chance that, because of the statistical noise, the highest peak in the histogram is not related to the mode of the underlying distribution.

The mode can be computed with three different methods:

fit: the distribution function maximum is obtained via a parabolic fit after making some check (that the distribution is sufficiently symmetric)

weight: the distribution function maximum is obtained by an ad hoc weight of the histogram bins adjacent to the maximum. This method is appropriate for point distributions that are not perfectly symmetric.

median: the distribution function maximum is obtained by computing the median of the data points.

The error computation can be computed analytically (if error_miter=0) or using a Montecarlo simulation (if error_miter > 0)

Results depend additionally on following parameters:

bin_size: if bin_size <=0 bin_size is automatically determined. as bin_size = 2. * 3.49 * stdev / pow(size, 1. / 3. ) ; where stdev is a robust estimation of the standard deviation obtained from the MAD of the image

histo_min: if histo_min < histo_max histo_min if histo_min < histo_max else histo_min = is equal min(distribution) - 0.5 * bin_size

histo_max: if histo_min < histo_max histo_max = histo_min + nbin * bin_size else histo_min = is equal max(distribution) + 0.5 * bin_size

## ◆ hdrl_mode_parameter_create_parlist()

cpl_parameterlist * hdrl_mode_parameter_create_parlist | ( | const char * | base_context,
|  | const char * | prefix,
|  | const hdrl_parameter * | defaults
| ) |  |

Create parameters for the mode collapse.

Parameters

  base_context | base context of parameter (e.g. recipe name)
  prefix | prefix of parameter, may be empty string
  defaults | default mode parameters

Returns
  The created parameter list Creates a parameterlist containing base_context.prefix.histo_min, base_context.prefix.histo_max, base_context.prefix.bin_size, base_context.prefix.method, base_context.prefix.error_niter
  the allocated parameter structure or NULL in case of error The user should make sure that base_context != NULL, prefix != NULL, defaults != NULL

## ◆ hdrl_mode_parameter_parse_parlist()

cpl_error_code hdrl_mode_parameter_parse_parlist | ( | const cpl_parameterlist * | parlist,
|  | const char * | prefix,
|  | double * | histo_min,
|  | double * | histo_max,
|  | double * | bin_size,
|  | hdrl_mode_type * | method,
|  | cpl_size * | error_niter
| ) |  |

parse parameterlist for mode parameters to init corresponding hdrl structure parameters

Parameters

  parlist | parameter list to parse
  prefix | prefix of parameter name
  histo_min | minimum value of low pixels to use
  histo_max | maximum value of high pixels to be use
  bin_size | size of the histogram bin
  method | method to use for the mode computation
  error_niter | number of iterations to compute the error of the mode

See also
  hdrl_mode_clip_get_parlist()

Returns
  cpl_error_code

parameterlist should have been created with hdrl_mode_clip_get_parlist or have the same name hierarchy

Developer should make sure that parlist != NULL, prefix != NULL