Next: , Previous: ave_dev_err, Up: imagefcts


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