Proposals:Statistics Framework Runtime Vector Size

Refactoring the Statistics Framework to have Runtime Length

Currently, the Statistics Framework requires the MeasurementVector to have a length defined at compile time.

Rationale for having compile time length

The statistics classes in ITK have MeasurementVectorSize (length of each measurement vector) as a static const value. This has until now been sufficient since typical statistics operations involve sampling an image where the number of measurement vectors is a variable, but the measurement vector size is usually fixed and depends on the dimension of the parametric space.

Rationale for having run time length

For algorithms such as Normalized cuts [1] and other Kernel PCA feature space projection techniques [2], it may be necessary to keep the dimensionality of the feature space as a variable. This requires removing MeasurementVectorSize as a static method and making it an iVar.

[1] PAMI - Vol26, No2, Spectral Grouping using the Nystrom method , Feb 2004

[2] Neural Computation - Nonlinear component analysis as a Kernel Eigenvalue problem, vol 10, 1998

API changes / additions

The statistics framework can be broadly classified into - classes that derive from Sample (List samples, subsamples, SampleAdaptors, Membership samples, Histogram, VariableDimensionHistogram etc) - Algorithms ( that derive from SampleAlgorithmBase ) - DistanceMetrics ( derive from DistanceMetric ) - DensityFunctions - Others

1. itk::Sample

This class now supports a method to set/get the MeasurementVector length. This must be set explicitly in cases where measurement vectors are variable size containers (itk::Array etc) as below.

 typedef itk::Sample< Array < double > > SampleType;
 SampleType::Pointer sample = SampleType::New();
 sample->SetMeasurementVectorSize( length );
 SampleType::MeasurementVectorType m(length);
 m.Fill( 4.57 );
 sample->PushBack( m );

An exception will usually be thrown by any class that tries to process a sample whose MeasurementVector length has not been set. The StaticConst macro to access it is no longer available. Use the Get/Set methods.

2. DistanceMetrics

This class also contains methods to set/Get measurement vector length. Typedefs for MeanType, OriginType, etc have been changed from FixedLength to VariableLength containers. For instance...

 typedef itk::Vector< float, 2 > MeasurementVectorType;
 typedef itk::Statistics::EuclideanDistance< MeasurementVectorType > DistanceMetricType;
 DistanceMetricType::Pointer distanceMetric = DistanceMetricType::New();
 DistanceMetricType::OriginType originPoint( 2 );  // not DistanceMetricType::OriginType originPoint;
 MeasurementVectorType queryPointA;
 MeasurementVectorType queryPointB;
 originPoint[0] = 0;
 originPoint[1] = 0;
 queryPointA[0] = 2;
 queryPointA[1] = 2;
 queryPointB[0] = 3;
 queryPointB[1] = 3;
 distanceMetric->SetOrigin( originPoint );
 std::cout << "Euclidean distance between the two query points (A and B) = " 
           << distanceMetric->Evaluate( queryPointA, queryPointB ) << std::endl;

3. DensityFunctions

The density functions also contain the MeasurementVector length as an ivar.

 densityfunction->SetMeasurementVectorSize( length );

4. SampleAlgorithms

Several statistics algorithms derive from SampleAlgorithmBase. They generally take an itk::Sample as an input and produce some statistically relevant information or another sample. These classes also contain the MeasurementVectorLength as an iVar and contain public: Set/Get macros to change the MeasurementVectorSize. They query the sample passed as input for the MeasurementVectorLength. They also contain consistency checks to ensure for instance that appropriate parameters are passed to the algorithm have conistent lengths.

 typedef itk::Sample< Array< float > > SampleType;
 typedef itk::Statistics::WeightedCovarianceCalculator< SampleType > CalculatorType;
 CalculatorType::MeanType mean( 3 );
 CalculatorType::Pointer calculator = CalculatorType::New();
 calculator->SetMean( mean );
 calculator->SetInputSample( sample ); // queried from sample.. length must be 3 or an exception
 calculator->SetWeightFunction(weightFunction.GetPointer()) ;

5. itk::Histogram

The existing histogram class is untouched. The itk::VariableDimensionHistogram handles histograms where the number of histogram axes is not known a-priori. In future the Histogram class may be deprecated/removed and the classes that generate histograms will generate VariableDimensionHistograms

6. Others

A few other classes like GoodnessOfFit, KdTrees etc contain the measurement vector length as an ivar. It is the users responsiblity to set these as appropriate.