Proposals:Statistics Framework Runtime Vector Size: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
 
(20 intermediate revisions by one other user not shown)
Line 15: Line 15:
[2] Neural Computation - Nonlinear component analysis as a Kernel Eigenvalue problem, vol 10, 1998
[2] Neural Computation - Nonlinear component analysis as a Kernel Eigenvalue problem, vol 10, 1998


= Proposed Implementation Plan =


This requires removing MeasurementVectorSize as a static method and making it an iVar.


FixedArrays, itk::Matrix and vnl_fixed that are templated over MeasurementVectorSize will have to be replaced by itk::Array, vnl_matrix and vnl_vector, where the size may be chosen at run time.


The SymmetricEigenAnalysis class must be used for eigen analysis since it is not templated over the dimension.


Bounds checking will have to be performed manually on all methods that use these FixedArrays.


API hiccups are unavoidable.. Warning macros will have to be provided. An open question is how to appropriately provide deprecated warning macros. I would suggest we place them in the constructor of all affected classes.


Very few statistics classes are used outside the statistics group. One of them is itk::Histogram.. Affects Histogram metrics. Typedefs like IndexType and SizeType will have to be replaced.




= Testing =
= API changes for the user =


See NAMICSandbox/RefactoringStatisticsClasses/
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


The goal is to test the Tests in the folder running fine before moving them to ITK. The tests can be run as usual after building with CMake. See
1. <tt><b style="color:red">itk::Sample</b></tt>
NAMICSandbox/RefactoringStatisticsClasses/README


Currently the following tests pass:
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 (<tt>itk::Array</tt> etc) as below.


itkCovarianceCalculatorTest
  typedef itk::Sample< Array < double > > SampleType;
itkDenseFrequencyContainerTest
  SampleType::Pointer sample = SampleType::New();
itkHistogramTest
  sample->SetMeasurementVectorSize( length );
itkKdTreeGeneratorTest
  SampleType::MeasurementVectorType m(length);
itkListSampleTest
  m.Fill( 4.57 );
itkListSampleToHistogramFilterTest
  sample->PushBack( m );
itkListSampleToHistogramGeneratorTest
itkListSampleToHistogramFilterTest
itkListSampleToHistogramGeneratorTest
itkMembershipSampleTest
itkMembershipSampleGeneratorTest
itkMeanCalculatorTest
itkNeighborhoodSamplerTest
itkStatisticsAlgorithmTest
itkSubsampleTest
itkVariableDimensionHistogramTest
itkWeightedMeanCalculatorTest
itkWeightedCovarianceCalculatorTest


= Proposed Transition Plan =
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.


= Current Status =


1. VariableDimensionHistogram
2. <b style="color:red">DistanceMetrics</b>


Class to handle variable length histograms added in NAMIC sandbox
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...  
NAMICSandBox/RefactoringITKStatisticsClasses/src/itkVariableDimensionHistogram.h, .txx
NAMICSandBox/RefactoringITKStatisticsClasses/Tests/itkVariableDimensionHistogramTest.cxx


The class is similar to itk::Histogram with modifications to allow the dimension of the
  typedef itk::Vector< float, 2 > MeasurementVectorType;
histogram (which is dependent on the size of each measurement vector) to be set at run-time.
  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;




2. VariableSizeMatrix
3. <b style="color:red">DensityFunctions</b>
NAMICSandBox/RefactoringITKStatisticsClasses/src/itkVariableSizeMatrix
Similar to itk::Matrix with a similar API


3. MeasurementVectorTraits
The density functions also contain the MeasurementVector length as an ivar.  
To have consistent API, we've created traits for measurement vectors. The traits are templated over the MeasurementVectorType (which was earlier constrained to be of type FixedArray or its subclasses.). For run-time size capability, we need to support itk::Array and possibly other containers like vnl_vector. To have a consistent way of dealing with GetSize(), SetSize calls etc, traits are used.
This class is templated over the MeasurementVectorType. [From the doxygen headers for the class]
* For instance, the developer can create a measurement vector as
*
* typename SampleType:: MeasurementVectorType m_MeasurementVector
* = MeasurementVectorTraits< typename
*    SampleType::MeasurementVectorType >::SetSize( s ) );
*
* This will create a measurement vector of length s if it is a FixedArray or
* a vnl_vector_fixed, itkVector etc.. If not it returns an array of length 0
* for the appropriate type. Other useful typedefs are defined to get the
* length of the vector, for the MeanType, RealType for compuatations etc
*
* To get the length of a measurement vector, the user would
*
* MeasurementVectorTraits< MeasurementVectorType >::GetSize( &mv )
*
* This calls the appropriate functions for the MeasurementVectorType to return
* the size of the measurement vector mv.
*
* MeasurementVectorTraits< MeasurementVectorType >::GetSize()
*
* This returns the length of MeasurementVectorType, which will be the true
* length of a FixedArray, Vector, vnl_vector_fixed, Point etc and 0 otherwise


NAMICSandBox/RefactoringITKStatisticsClasses/src/itkMeasurementVectorTraits.h
  densityfunction->SetMeasurementVectorSize( length );




== API changes / additions ==
4. <b style="color:red">SampleAlgorithms</b>


1. itk::Sample now supports a method to set/get the MeasurementVector length .
Several statistics algorithms derive from <tt>SampleAlgorithmBase</tt>. They generally take an <tt>itk::Sample</tt> as an input and produce some statistically relevant information or another <tt>sample</tt>. These classes also contain the MeasurementVectorLength as an iVar and contain <tt>public:</tt> 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 < double > > SampleType;
  typedef itk::Sample< Array< float > > SampleType;
SampleType::Pointer sample = SampleType::New();
  typedef itk::Statistics::WeightedCovarianceCalculator< SampleType > CalculatorType;
sample->SetMeasurementVectorSize( length );
  CalculatorType::MeanType mean( 3 );
SampleType::MeasurementVectorType m(length);
  CalculatorType::Pointer calculator = CalculatorType::New();
m.Fill( 3 );
  calculator->SetMean( mean );
sample->PushBack( m );
  calculator->SetInputSample( sample ); // queried from sample.. length must be 3 or an exception
  calculator->SetWeightFunction(weightFunction.GetPointer()) ;


1. FixedArrays as measurement vectors are still supported, All the macros such as SampleType::MeasurementVectorSize are still available (thanks to traits). This convention of getting the length of a measurement vector will be deprecated in future versions. The rationale is inconsistency. For instance,
A few classes return <tt>Array</tt> and <tt>VariableSizeMatrix</tt>, for instance the co-variance matrix, but their API is largely the same as itk::Matrix, unless you try to access static const ivars in the returned matrix... surprise!


typedef itk::Sample< FixedArray< double, 3 > > SampleType;
std::cout << SampleType::MeasurementVectorSize << std::endl;


When the length of the measurement vector is a variable
5. <b style="color:red">itk::Histogram </b>


typedef itk::Sample< Array< double > > SampleType
The existing histogram class is untouched. The <tt>itk::VariableDimensionHistogram</tt> 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. <b style="color:red">Others </b>
 
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.
 
{{ITK/Template/Footer}}

Latest revision as of 20:40, 20 December 2005

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 for the user

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()) ;

A few classes return Array and VariableSizeMatrix, for instance the co-variance matrix, but their API is largely the same as itk::Matrix, unless you try to access static const ivars in the returned matrix... surprise!


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.



ITK: [Welcome | Site Map]