DATAMANIP (kdatamanip) functions


LIBRARY ROUTINE

lkstats - calculate statistics of data object

LIBRARY CALL

int lkstats (
   kobject src_obj,
   kobject gate_obj,
   kobject stats_obj,
   unsigned long  active_stats,
   unsigned long  aux_info,
   unsigned long  stats_region,
   kfile          *ascii_file,
   int		  ascii_flag)

INPUT

OUTPUT

RETURN VALUE

TRUE (1) on success, FALSE (0) on failure

DESCRIPTION

Library Routine for kstats. For the input src_obj, lkstats calculates the set of statistics defined by the flags set in the active_stats variable. The results are stored in the stats_obj data object. The active_stats flag can be built by or'ing the statistics flags defined in include/kdatamanip/kstats.h. The aux_info variable defines additional, non-statistical information, such as object data dimensions and position of the minimum and maximum values, that may also be recorded in stats_obj. The aux_info flag can be built by or'ing the auxiliary information flags defined in include/kdatamanip/kstats.h.

Data with corresponding mask or gate values of zero (gating defined by gate_obj) are not included in any statistics calculations. If the gating object is different sized than the source object, it will be resized to match the source object, padded with 1.

If the input data object contains a map, the data will be mapped before the statistics are calcualted. All output information will reflect this mapping.

The following statistics are available:

mean = 1/N*sum(x(i)) i=1..N var = 1/(N-1)*sum( (x(i) - mean)**2 ) i=1..N stddev = sqrt(var) i=1..N rms = sqrt(1/N*sum(x(i)**2)) i=1..N skew = 1/N*sum( ((x(i) - mean)/stddev) **3 ) i=1..N kurtosis=(1/N*sum( ((x(i) - mean)/stddev) **4)) - 3 i=1..N minimum value maximum value minimum value coordinates maximum value coordinates sum of all points sum of all positive points sum of all negative points number of contributing points number of positive contributing points number of negative contributing points number of zero-valued contributing points dimensions of data

Statistics are stored in the stats_obj as double float. Each statistic is stored as an element of a N-D vector defined along the value data "elements" dimension of the stats_obj, where N is the number of statistics defined by the active_stats variable.

The order in which the elements of the statistics vector are stored in the statistics data object is given in the object's comment attribute.

When M sets of statistics are calculated for M multiple regions of the input data object (defined by the flags set in the stats_region variable), the statistics vectors are stored along the width dimension (width=M, elements=N).

The stats_region variable defines how the data object is sliced along the dimensions for calculation of statistics over sub-regions. For example, if the width and height flags are set in the "stats_region" variable, the statistics for each width-height plane will be calculated separately. For an image object this can be viewed as calculating the statistics across the various bands of the image. The stats_region flag can be built by or'ing the region dimensionality flags defined in include/kdatamanip/kstats.h.

While computing variance, the division factor is set to (N-1) in order to obtain a more accurate estimate. For a more detailed explanation refer to any standard statistics text.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

Tom Robey - modified the variance formula to use a more accurate two pass version Oct 22, 1996

FILES

$DATAMANIP/objects/library/kdatamanip/src/lkstats.c

SEE ALSO

kdatamanip(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.