name: Statistics : public AlgorithmBase
synopsis:

>     g++ [flags ...] file ...-l /isip/tools/lib/$ISIP_BINARY/lib_algo.a

>     #include <Statistics.h>

>     Statistics(ALGORITHM algorithm = DEF_ALGORITHM);
>     Statistics(const Statistics& arg);
>     boolean compute(VectorFloat& output, const VectorFloat& input,
>                     AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE);
>     boolean compute(Vector <VectorFloat>& output,
>     		const Vector <VectorFloat>& input,
>     		AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE);

quick start:

>     Statistics stat0;
>     Statistics stat1(stat0);
>     VectorFloat input(L"0, 1, 2, 3, 4");
>     VectorFloat output;
>     stat1.setAlgorithm(Statistics::MEDIAN);
>     stat1.compute(output, input);

description:
The Statistics class calculates various statistical parameters of the input data such as the maximum, mean, and variance. Two types of implementations have been supported - FRAME_INTERNAL and ACCUMULATE. FRAME_INTERNAL computes the requested feature over one frame of data. This is useful for computing the average value of a signal on a frame-by-frame basis. ACCUMULATE computes the requested feature across all frames, and can be used to output a value for the entire file. This is useful when computing the mean value of a signal for the entire file.
A summary of the options available for this class is given below:
Note that the form of the output (scalar or vector) depends on the computational mode (CMODE). The mathematical descriptions of the operations represented in this table are shown below:
Skew and Kurtosis are not currently supported.
dependencies:

- AlgorithmBase
- AlgorithmData
- Vector
- MemoryManager

public constants:

- define the class name:

      static const String CLASS_NAME = L"Statistics";

- define algorithm choices:

      enum ALGORITHM { MINIMUM = 0, MINIMUM_MAG, MAXIMUM, MAXIMUM_MAG, MEAN, MEDIAN, VARIANCE, STDEV, SKEW, KURTOSIS, DEF_ALGORITHM = MINIMUM };

- define implementation choices:

      enum IMPLEMENTATION { LINEAR = 0, DEF_IMPLEMENTATION = LINEAR};

- define static NameMap objects:

      static const NameMap ALGO_MAP = L"MINIMUM, MINIMUM_MAG, MAXIMUM, MAXIMUM_MAG, MEAN, MEDIAN, VARIANCE, STDEV, SKEW, KURTOSIS";

      static const NameMap IMPL_MAP = L"LINEAR";

- define i/o related constants:

      static const String Statistics::DEF_PARAM = L"";

      static const String Statistics::PARAM_ALGORITHM = L"algorithm";

      static const String Statistics::PARAM_IMPLEMENTATION = L"implementation";

      static const String Statistics::PARAM_CMODE = L"compute_mode";

      static const String Statistics::PARAM_DMODE = L"data_mode";

- define default value(s) of the class data:

      static const long DEF_DELAY = 0;

      static const long DEF_NUM_FRAMES = 0;

- define default argument(s):

      static const AlgorithmData::COEF_TYPE DEF_COEF_TYPE = AlgorithmData::DEF_CTYPE;

error codes:

- general error codes:

      static const long ERR = 71800;

protected data:

- algorithm name:

      ALGORITHM algorithm_d;

- implementation name:

      IMPLEMENTATION implementation_d;

- static memory manager:

      static MemoryManager mgr_d;

- define a variety of accumulators for input vectors: note that the median operation is rather expensive since it requires keeping track of all prior data members.

      Vector<AlgorithmData> accum_sumsqr_d;

      Vector<AlgorithmData> accum_sum_d;

      Vector<AlgorithmData> accum_result_d;

      Vector<AlgorithmData> accum_frame_data_d;

      long accum_samples_d;

      long accum_frames_d;

- define some useful counters:

      long accum_samples_d;

      long accum_frames_d;

- define a flag to keep track of the computation history:

      boolean is_calculated_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods: setDebug is inherited from the AlgorithmBase class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Statistics();

      Statistics(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

      Statistics(const Statistics& arg);

- assign methods:

      boolean assign(const Statistics& arg);

- operator= methods:

      Statistics& operator= (const Statistics& arg);

- i/o methods:

      long sofSize() const;

      boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

      boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

      boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

- equality methods:

      boolean eq(const Statistics& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

- set methods:

      boolean setAlgorithm(ALGORITHM algorithm);

      boolean setImplementation(IMPLEMENTATION implementation);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

      boolean setAccumulateVar(long num_channel, long dimension);

- get methods:

      ALGORITHM getAlgorithm();

      IMPLEMENTATION getImplementation() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation) const;

- computational methods:

      boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

- AlgorithmBase interface contract methods:

      boolean assign(const AlgorithmBase& arg);

      boolean eq(const AlgorithmBase& arg) const;

      const String& className() const;

      boolean init();

      boolean apply(Vector<AlgorithmData>& output, const Vector<AlgorithmData>& input);

      boolean setParser(SofParser* parser);

private methods:

- common i/o methods:

      boolean readDataCommon(Sof& sof, const String& pname, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeDataCommon(Sof& sof, const String& pname) const;

- mode and computation mode-specific computation methods

      boolean computeFrameInt(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

      boolean computeFrameAccumulate(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

      boolean computeSampleAccumulate(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

- algorithm and implementation specific computation methods:

      boolean computeMin(VectorFloat& output, const VectorFloat& input);

      boolean computeMax(VectorFloat& output, const VectorFloat& input);

      boolean computeMinMag(VectorFloat& output, const VectorFloat& input);

      boolean computeMaxMag(VectorFloat& output, const VectorFloat& input);

      boolean computeMean(VectorFloat& output, const VectorFloat& input);

      boolean computeMedian(VectorFloat& output, const VectorFloat& input);

      boolean computeVar(VectorFloat& output, const VectorFloat& input);

      boolean computeStdDev(VectorFloat& output, const VectorFloat& input);

examples:

- This example shows how to compute various statistical parameters:

      // isip include files
      //
      #include <Statistics.h>
      #include <Console.h>

      // main program starts here
      //
      int main(int argc, const char **argv) {

        // declare input
        //
        VectorFloat input;
        input.assign(L"0, 1, 2, 3");

        // declare output
        //
        VectorFloat output;

        // define the expected results
        //
        VectorFloat exp_median(L"1.5");
        VectorFloat exp_max(L"3");
        VectorFloat exp_max_mag(L"3");
        VectorFloat exp_min(L"0");
        VectorFloat exp_min_mag(L"0");
        VectorFloat exp_mean(L"1.5");
        VectorFloat exp_var(L"1.25");
        VectorFloat exp_stddev(L"1.11803");

        // compute minimum
        //
        stat2.setAlgorithm(MINIMUM);
        stat2.compute(output, input);
        if (!output.almostEqual(exp_min)) {
          Console::put(L"Error in minimum");
        }

        // compute maximum
        //
        stat2.setAlgorithm(MAXIMUM);
        stat2.compute(output, input);
        if (!output.almostEqual(exp_max)) {
          Console::put(L"Error in maximum");
        }

        // compute median
        //
        stat2.setAlgorithm(MEDIAN);
        stat2.compute(output, input);
        if (!output.almostEqual(exp_median)) {
          Console::put(L"Error in median");
        }

        // exit gracefully
        //
        return true;
      }

notes:

- none.