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 themodal 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