Next: , Previous: ave_dev_err, Up: imagefcts   [Contents]


12.2 center_variter

iteratively determine the center of a distribution

Synopsis

#include <suplib/imagefcts.h>

int center_variter(
  void *objs,
  void *wwork,
  unsigned long n_objs,
  double tot_wt,
  size_t s_obj,
  double dtol,
  double fvar,
  unsigned long max_iter,
  unsigned long max_clip,
  double *center,
  double *dev_used,
  size_t *n_used,
  double *wt_used,
  void **objs_used,
  double (*get_x)(const void *obj,double *x),
  void (*put_x)(void *obj,double x),
  int (*comp)(const void *obj1,const void *obj2)
);

Parameters

void *objs

the list of objects to process

void *wwork

a work space of size 3 * s_obj

unsigned long n_objs

total number of objects to process

double tot_wt

the total (summed) weight of all of the objects.

size_t s_obj

the size of an object in bytes

double dtol

smallest absolute (not percentage) difference between two distances so as to consider them distinct.

double fvar

fraction of determined variance in distance above which to ignore objects in center determination.

unsigned long max_iter

maximum number of iterations to perform.

unsigned long max_clip

maximum number of clips per iteration to perform.

double *center

the final determined center

double *dev_used

the standard deviation of the objects remaining after the last round of clips

size_t *n_used

the number of objects remaining after the last round of clips

double *wt_used

the summed weights of the objects remaining after the last round of clips

void **objs_used

a pointer to the objects used

double (*get_x)(const void *obj,double *x)

routine which retrieves position of an object. returns weight of object

void (*put_x)(void *obj,double x)

routine which stuffs a position into an object.

int (*comp)(const void *obj1,const void *obj2)

routine which compares two objects based upon their squared distances (same setup as routines for *<qsort>*)

Description

center_variter determines the center of a distribution by iteratively rejecting objects whose deviation in distance from a determined center is greater than a given number of sample deviations from the center. After each iteration, changes in the determined center are measured; if the changes are less than a specified threshold, the algorithm is deemed to have converged. Additionally, there is a limit on the number of iterations performed. The input list of objects is reordered.

Returns

It returns the following information about the set of objects which survived the clipping spree:

center

the final determined center

dev_used

the mean deviation from the center

n_used

the number of objects

wt_used

the weight of the objects

objs_used

a pointer into the (reordered) input list where the final list of objects starts

The actual value returned by center_variter will be one of:

CVR_OK

everything went well

CVR_LESSTHANTWO

less than two objects were left after clipping. fvar was probably too low

CVR_MAXITER

the iteration limit was reached.

A More Detailed Description Of The Algorithm

  1. a mean center is determined and used as the initial guess
  2. distances to the determined center are calculated for all objects, and the variance (with respect to zero distance) is calculated.
  3. objects with variances greater than the specified limit are rejected and the group variance recalculated after each rejection. this is repeated until either no more objects are rejected, the object count drops below a limit, or an iteration limit is reached.
  4. a new mean center is calculated using the objects surviving the culling, and compared to the previous determination. if the distance between the two centers is less than the specified tolerance, the procedure ends. if the iteration limit has not been reached, the process continues with step 2.

Author

Diab Jerius


Next: , Previous: ave_dev_err, Up: imagefcts   [Contents]