ENH: Replace "SubtractMean" with "UseZeroAverageDisplacementConstraint"

Sets its default "true". (For the affected elastix metrics (`PCAMetric`, `PCAMetric2`, `SumOfPairwiseCorrelationCoefficients`, `VarianceOverLastDimension`), the SubtractMean parameter originally had "false" as default.)

The term "UseZeroAverageDisplacementConstraint" is more specific than "SubtractMean", so it appears preferably. Discussed with Marius Staring and Stefan Klein.

Added a warning about this change to the `Initialize()` member functions of the affected elastix metrics.

If "SubtractMean" is specified, now using its value as default for "UseZeroAverageDisplacementConstraint", for backward compatibility.

Components/Metrics/PCAMetric/elxPCAMetric.h

@@ -49,9 +49,10 @@ namespace elastix
  *    be set with parameter NumSamplesLastDimension. \n
  * \parameter NumSamplesLastDimension: the number of random samples to take in the time
  *    time direction of the data when SampleLastDimensionRandomly is set to true.
- * \parameter SubtractMean: subtract the over time computed mean parameter value from
+ * \parameter UseZeroAverageDisplacementConstraint: subtract the over time computed mean parameter value from
  *    each parameter. This should be used when registration is performed directly on the moving
- *    image, without using a fixed image. Possible values are "true" or "false".
+ *    image, without using a fixed image. Possible values are "true" or "false".\n
+ *    Default is "true".
  * \parameter NumEigenValues: number of eigenvalues used in the metric: sum(e) - e, where sum(e)
  *  is the sum of all eigenvalues and e is the sum of the first highest NumEigenValues eigenvalues.
  *

Components/Metrics/PCAMetric/elxPCAMetric.hxx

@@ -36,6 +36,17 @@ PCAMetric<TElastix>::Initialize()
   itk::TimeProbe timer;
   timer.Start();
   this->Superclass1::Initialize();
+
+  const Configuration & configuration = itk::Deref(Superclass2::GetConfiguration());
+
+  if (configuration.HasParameter("SubtractMean"))
+  {
+    log::warn(std::string("WARNING: From elastix version 5.2, the ") + elxGetClassNameStatic() +
+              " parameter `SubtractMean` (default \"false\") is "
+              "replaced with `UseZeroAverageDisplacementConstraint` "
+              "(default \"true\").");
+  }
+
   timer.Stop();
   log::info(std::ostringstream{} << "Initialization of PCAMetric metric took: "
                                  << static_cast<long>(timer.GetMean() * 1000) << " ms.");
@@ -62,9 +73,12 @@ PCAMetric<TElastix>::BeforeEachResolution()
   this->SetNumEigenValues(NumEigenValues);
 
   /** Get and set if we want to subtract the mean from the derivative. */
-  bool subtractMean = false;
-  configuration.ReadParameter(subtractMean, "SubtractMean", componentLabel, 0, 0);
-  this->SetSubtractMean(subtractMean);
+  bool useZeroAverageDisplacementConstraint = true;
+  // The parameter name "SubtractMean" is obsolete, so just use it as initial value, for backward compatibility.
+  configuration.ReadParameter(useZeroAverageDisplacementConstraint, "SubtractMean", componentLabel, 0, 0);
+  configuration.ReadParameter(
+    useZeroAverageDisplacementConstraint, "UseZeroAverageDisplacementConstraint", componentLabel, 0, 0);
+  this->SetUseZeroAverageDisplacementConstraint(useZeroAverageDisplacementConstraint);
 
   /** Get and set the number of additional samples sampled at the fixed timepoint.  */
   //    unsigned int numAdditionalSamplesFixed = 0;

Components/Metrics/PCAMetric/itkPCAMetric.h

@@ -53,7 +53,7 @@ class ITK_TEMPLATE_EXPORT PCAMetric : public AdvancedImageToImageMetric<TFixedIm
   itkSetMacro(NumSamplesLastDimension, unsigned int);
   itkSetMacro(NumAdditionalSamplesFixed, unsigned int);
   itkSetMacro(ReducedDimensionIndex, unsigned int);
-  itkSetMacro(SubtractMean, bool);
+  itkSetMacro(UseZeroAverageDisplacementConstraint, bool);
   itkSetMacro(GridSize, FixedImageSizeType);
   itkSetMacro(TransformIsStackTransform, bool);
   itkSetMacro(NumEigenValues, unsigned int);
@@ -187,7 +187,7 @@ class ITK_TEMPLATE_EXPORT PCAMetric : public AdvancedImageToImageMetric<TFixedIm
   double m_VarNoise{ 0.0 };
 
   /** Bool to determine if we want to subtract the mean derivate from the derivative elements. */
-  bool m_SubtractMean{ false };
+  bool m_UseZeroAverageDisplacementConstraint{ true };
 
   /** GridSize of B-spline transform. */
   FixedImageSizeType m_GridSize{};

Components/Metrics/PCAMetric/itkPCAMetric.hxx

@@ -738,7 +738,7 @@ PCAMetric<TFixedImage, TMovingImage>::GetValueAndDerivative(const TransformParam
   derivative = -tracevKvdmu;
 
   /** Subtract mean from derivative elements. */
-  if (m_SubtractMean)
+  if (m_UseZeroAverageDisplacementConstraint)
   {
     if (!m_TransformIsStackTransform)
     {

Components/Metrics/PCAMetric/itkPCAMetric_F_multithreaded.h

@@ -50,7 +50,7 @@ class ITK_TEMPLATE_EXPORT PCAMetric : public AdvancedImageToImageMetric<TFixedIm
   itkTypeMacro(PCAMetric, AdvancedImageToImageMetric);
 
   /** Set functions. */
-  itkSetMacro(SubtractMean, bool);
+  itkSetMacro(UseZeroAverageDisplacementConstraint, bool);
   itkSetMacro(GridSize, FixedImageSizeType);
   itkSetMacro(TransformIsStackTransform, bool);
   itkSetMacro(NumEigenValues, unsigned int);
@@ -222,7 +222,7 @@ class ITK_TEMPLATE_EXPORT PCAMetric : public AdvancedImageToImageMetric<TFixedIm
   unsigned int m_LastDimIndex{};
 
   /** Bool to determine if we want to subtract the mean derivate from the derivative elements. */
-  bool m_SubtractMean{ false };
+  bool m_UseZeroAverageDisplacementConstraint{ true };
 
   /** GridSize of B-spline transform. */
   FixedImageSizeType m_GridSize{};

Components/Metrics/PCAMetric/itkPCAMetric_F_multithreaded.hxx

@@ -525,7 +525,7 @@ PCAMetric<TFixedImage, TMovingImage>::GetValueAndDerivativeSingleThreaded(const
   measure = m_G - sumEigenValuesUsed;
 
   /** Subtract mean from derivative elements. */
-  if (m_SubtractMean)
+  if (m_UseZeroAverageDisplacementConstraint)
   {
     if (!m_TransformIsStackTransform)
     {
@@ -958,7 +958,7 @@ PCAMetric<TFixedImage, TMovingImage>::AfterThreadedComputeDerivative(DerivativeT
   derivative *= -(2.0 / (DerivativeValueType(Superclass::m_NumberOfPixelsCounted) - 1.0)); // normalize
 
   /** Subtract mean from derivative elements. */
-  if (m_SubtractMean)
+  if (m_UseZeroAverageDisplacementConstraint)
   {
     if (!m_TransformIsStackTransform)
     {

Components/Metrics/PCAMetric2/elxPCAMetric2.h

@@ -49,9 +49,10 @@ namespace elastix
  *    be set with parameter NumSamplesLastDimension. \n
  * \parameter NumSamplesLastDimension: the number of random samples to take in the time
  *    time direction of the data when SampleLastDimensionRandomly is set to true.
- * \parameter SubtractMean: subtract the over time computed mean parameter value from
+ * \parameter UseZeroAverageDisplacementConstraint: subtract the over time computed mean parameter value from
  *    each parameter. This should be used when registration is performed directly on the moving
- *    image, without using a fixed image. Possible values are "true" or "false".
+ *    image, without using a fixed image. Possible values are "true" or "false".\n
+ *    Default is "true".
  * \parameter NumEigenValues: number of eigenvalues used in the metric: sum(e) - e, where sum(e)
  *  is the sum of all eigenvalues and e is the sum of the first highest NumEigenValues eigenvalues.
  *

Components/Metrics/PCAMetric2/elxPCAMetric2.hxx

@@ -36,6 +36,17 @@ PCAMetric2<TElastix>::Initialize()
   itk::TimeProbe timer;
   timer.Start();
   this->Superclass1::Initialize();
+
+  const Configuration & configuration = itk::Deref(Superclass2::GetConfiguration());
+
+  if (configuration.HasParameter("SubtractMean"))
+  {
+    log::warn(std::string("WARNING: From elastix version 5.2, the ") + elxGetClassNameStatic() +
+              " parameter `SubtractMean` (default \"false\") is "
+              "replaced with `UseZeroAverageDisplacementConstraint` "
+              "(default \"true\").");
+  }
+
   timer.Stop();
   log::info(std::ostringstream{} << "Initialization of PCAMetric2 metric took: "
                                  << static_cast<long>(timer.GetMean() * 1000) << " ms.");
@@ -58,9 +69,12 @@ PCAMetric2<TElastix>::BeforeEachResolution()
   unsigned int level = (this->m_Registration->GetAsITKBaseType())->GetCurrentLevel();
 
   /** Get and set if we want to subtract the mean from the derivative. */
-  bool subtractMean = false;
-  configuration.ReadParameter(subtractMean, "SubtractMean", componentLabel, 0, 0);
-  this->SetSubtractMean(subtractMean);
+  bool useZeroAverageDisplacementConstraint = true;
+  // The parameter name "SubtractMean" is obsolete, so just use it as initial value, for backward compatibility.
+  configuration.ReadParameter(useZeroAverageDisplacementConstraint, "SubtractMean", componentLabel, 0, 0);
+  configuration.ReadParameter(
+    useZeroAverageDisplacementConstraint, "UseZeroAverageDisplacementConstraint", componentLabel, 0, 0);
+  this->SetUseZeroAverageDisplacementConstraint(useZeroAverageDisplacementConstraint);
 
   /** Get and set the number of additional samples sampled at the fixed timepoint.  */
   unsigned int numAdditionalSamplesFixed = 0;

Components/Metrics/PCAMetric2/itkPCAMetric2.h

@@ -51,7 +51,7 @@ class ITK_TEMPLATE_EXPORT PCAMetric2 : public AdvancedImageToImageMetric<TFixedI
   /** Set functions. */
   itkSetMacro(NumAdditionalSamplesFixed, unsigned int);
   itkSetMacro(ReducedDimensionIndex, unsigned int);
-  itkSetMacro(SubtractMean, bool);
+  itkSetMacro(UseZeroAverageDisplacementConstraint, bool);
   itkSetMacro(GridSize, FixedImageSizeType);
   itkSetMacro(TransformIsStackTransform, bool);
 
@@ -161,7 +161,7 @@ class ITK_TEMPLATE_EXPORT PCAMetric2 : public AdvancedImageToImageMetric<TFixedI
   unsigned int m_ReducedDimensionIndex{};
 
   /** Bool to determine if we want to subtract the mean derivate from the derivative elements. */
-  bool m_SubtractMean{ false };
+  bool m_UseZeroAverageDisplacementConstraint{ true };
 
   /** GridSize of B-spline transform. */
   FixedImageSizeType m_GridSize{};

Components/Metrics/PCAMetric2/itkPCAMetric2.hxx

@@ -558,7 +558,7 @@ PCAMetric2<TFixedImage, TMovingImage>::GetValueAndDerivative(const TransformPara
   measure = sumWeightedEigenValues;
 
   /** Subtract mean from derivative elements. */
-  if (m_SubtractMean)
+  if (m_UseZeroAverageDisplacementConstraint)
   {
     if (!m_TransformIsStackTransform)
     {

Components/Metrics/SumOfPairwiseCorrelationsMetric/elxSumOfPairwiseCorrelationCoefficientsMetric.h

@@ -51,9 +51,10 @@ namespace elastix
  *    be set with parameter NumSamplesLastDimension. \n
  * \parameter NumSamplesLastDimension: the number of random samples to take in the time
  *    time direction of the data when SampleLastDimensionRandomly is set to true.
- * \parameter SubtractMean: subtract the over time computed mean parameter value from
+ * \parameter UseZeroAverageDisplacementConstraint: subtract the over time computed mean parameter value from
  *    each parameter. This should be used when registration is performed directly on the moving
- *    image, without using a fixed image. Possible values are "true" or "false".
+ *    image, without using a fixed image. Possible values are "true" or "false".\n
+ *    Default is "true".
  *
  * \ingroup RegistrationMetrics
  * \ingroup Metrics

Components/Metrics/SumOfPairwiseCorrelationsMetric/elxSumOfPairwiseCorrelationCoefficientsMetric.hxx

@@ -37,6 +37,17 @@ SumOfPairwiseCorrelationCoefficientsMetric<TElastix>::Initialize()
   itk::TimeProbe timer;
   timer.Start();
   this->Superclass1::Initialize();
+
+  const Configuration & configuration = itk::Deref(Superclass2::GetConfiguration());
+
+  if (configuration.HasParameter("SubtractMean"))
+  {
+    log::warn(std::string("WARNING: From elastix version 5.2, the ") + elxGetClassNameStatic() +
+              " parameter `SubtractMean` (default \"false\") is "
+              "replaced with `UseZeroAverageDisplacementConstraint` "
+              "(default \"true\").");
+  }
+
   timer.Stop();
   log::info(std::ostringstream{} << "Initialization of SumOfPairwiseCorrelationCoefficientsMetric metric took: "
                                  << static_cast<long>(timer.GetMean() * 1000) << " ms.");
@@ -59,9 +70,12 @@ SumOfPairwiseCorrelationCoefficientsMetric<TElastix>::BeforeEachResolution()
   unsigned int level = (this->m_Registration->GetAsITKBaseType())->GetCurrentLevel();
 
   /** Get and set if we want to subtract the mean from the derivative. */
-  bool subtractMean = false;
-  configuration.ReadParameter(subtractMean, "SubtractMean", componentLabel, 0, 0);
-  this->SetSubtractMean(subtractMean);
+  bool useZeroAverageDisplacementConstraint = true;
+  // The parameter name "SubtractMean" is obsolete, so just use it as initial value, for backward compatibility.
+  configuration.ReadParameter(useZeroAverageDisplacementConstraint, "SubtractMean", componentLabel, 0, 0);
+  configuration.ReadParameter(
+    useZeroAverageDisplacementConstraint, "UseZeroAverageDisplacementConstraint", componentLabel, 0, 0);
+  this->SetUseZeroAverageDisplacementConstraint(useZeroAverageDisplacementConstraint);
 
   /** Get and set the number of additional samples sampled at the fixed timepoint.  */
   unsigned int numAdditionalSamplesFixed = 0;

Components/Metrics/SumOfPairwiseCorrelationsMetric/itkSumOfPairwiseCorrelationCoefficientsMetric.h

@@ -52,7 +52,7 @@ class ITK_TEMPLATE_EXPORT SumOfPairwiseCorrelationCoefficientsMetric
   /** Set functions. */
   itkSetMacro(NumAdditionalSamplesFixed, unsigned int);
   itkSetMacro(ReducedDimensionIndex, unsigned int);
-  itkSetMacro(SubtractMean, bool);
+  itkSetMacro(UseZeroAverageDisplacementConstraint, bool);
   itkSetMacro(GridSize, FixedImageSizeType);
   itkSetMacro(TransformIsStackTransform, bool);
 
@@ -161,7 +161,7 @@ class ITK_TEMPLATE_EXPORT SumOfPairwiseCorrelationCoefficientsMetric
   unsigned int m_ReducedDimensionIndex{};
 
   /** Bool to determine if we want to subtract the mean derivate from the derivative elements. */
-  bool m_SubtractMean{ true };
+  bool m_UseZeroAverageDisplacementConstraint{ true };
 
   /** GridSize of B-spline transform. */
   FixedImageSizeType m_GridSize{};

Components/Metrics/SumOfPairwiseCorrelationsMetric/itkSumOfPairwiseCorrelationCoefficientsMetric.hxx

@@ -481,7 +481,7 @@ SumOfPairwiseCorrelationCoefficientsMetric<TFixedImage, TMovingImage>::GetValueA
   measure = RealType(1.0 - (K.fro_norm() / RealType(G)));
 
   /** Subtract mean from derivative elements. */
-  if (m_SubtractMean)
+  if (m_UseZeroAverageDisplacementConstraint)
   {
     if (!m_TransformIsStackTransform)
     {

Components/Metrics/VarianceOverLastDimension/elxVarianceOverLastDimensionMetric.h

@@ -55,9 +55,10 @@ namespace elastix
  *    be set with parameter NumSamplesLastDimension. \n
  * \parameter NumSamplesLastDimension: the number of random samples to take in the time
  *    time direction of the data when SampleLastDimensionRandomly is set to true.
- * \parameter SubtractMean: subtract the over time computed mean parameter value from
+ * \parameter UseZeroAverageDisplacementConstraint: subtract the over time computed mean parameter value from
  *    each parameter. This should be used when registration is performed directly on the moving
- *    image, without using a fixed image. Possible values are "true" or "false".
+ *    image, without using a fixed image. Possible values are "true" or "false".\n
+ *    Default is "true".
  *
  * \ingroup RegistrationMetrics
  * \ingroup Metrics

Components/Metrics/VarianceOverLastDimension/elxVarianceOverLastDimensionMetric.hxx

@@ -36,6 +36,17 @@ VarianceOverLastDimensionMetric<TElastix>::Initialize()
   itk::TimeProbe timer;
   timer.Start();
   this->Superclass1::Initialize();
+
+  const Configuration & configuration = itk::Deref(Superclass2::GetConfiguration());
+
+  if (configuration.HasParameter("SubtractMean"))
+  {
+    log::warn(std::string("WARNING: From elastix version 5.2, the ") + elxGetClassNameStatic() +
+              " parameter `SubtractMean` (default \"false\") is "
+              "replaced with `UseZeroAverageDisplacementConstraint` "
+              "(default \"true\").");
+  }
+
   timer.Stop();
   log::info(std::ostringstream{} << "Initialization of VarianceOverLastDimensionMetric metric took: "
                                  << static_cast<long>(timer.GetMean() * 1000) << " ms.");
@@ -100,9 +111,12 @@ VarianceOverLastDimensionMetric<TElastix>::BeforeEachResolution()
   this->SetSampleLastDimensionRandomly(useRandomSampling);
 
   /** Get and set if we want to subtract the mean from the derivative. */
-  bool subtractMean = false;
-  configuration.ReadParameter(subtractMean, "SubtractMean", componentLabel, 0, 0);
-  this->SetSubtractMean(subtractMean);
+  bool useZeroAverageDisplacementConstraint = true;
+  // The parameter name "SubtractMean" is obsolete, so just use it as initial value, for backward compatibility.
+  configuration.ReadParameter(useZeroAverageDisplacementConstraint, "SubtractMean", componentLabel, 0, 0);
+  configuration.ReadParameter(
+    useZeroAverageDisplacementConstraint, "UseZeroAverageDisplacementConstraint", componentLabel, 0, 0);
+  this->SetUseZeroAverageDisplacementConstraint(useZeroAverageDisplacementConstraint);
 
   /** Get and set the number of random samples for the last dimension. */
   int numSamplesLastDimension = 10;

Components/Metrics/VarianceOverLastDimension/itkVarianceOverLastDimensionImageMetric.h

@@ -75,7 +75,7 @@ class ITK_TEMPLATE_EXPORT VarianceOverLastDimensionImageMetric
   itkSetMacro(NumSamplesLastDimension, unsigned int);
   itkSetMacro(NumAdditionalSamplesFixed, unsigned int);
   itkSetMacro(ReducedDimensionIndex, unsigned int);
-  itkSetMacro(SubtractMean, bool);
+  itkSetMacro(UseZeroAverageDisplacementConstraint, bool);
   itkSetMacro(GridSize, FixedImageSizeType);
   itkSetMacro(TransformIsStackTransform, bool);
 
@@ -189,7 +189,7 @@ class ITK_TEMPLATE_EXPORT VarianceOverLastDimensionImageMetric
   unsigned int m_ReducedDimensionIndex{};
 
   /** Bool to determine if we want to subtract the mean derivate from the derivative elements. */
-  bool m_SubtractMean{ false };
+  bool m_UseZeroAverageDisplacementConstraint{ true };
 
   /** Initial variance in last dimension, used as normalization factor. */
   float m_InitialVariance{};

Components/Metrics/VarianceOverLastDimension/itkVarianceOverLastDimensionImageMetric.hxx

@@ -490,7 +490,7 @@ VarianceOverLastDimensionImageMetric<TFixedImage, TMovingImage>::GetValueAndDeri
   derivative /= static_cast<float>(Superclass::m_NumberOfPixelsCounted * m_InitialVariance);
 
   /** Subtract mean from derivative elements. */
-  if (m_SubtractMean)
+  if (m_UseZeroAverageDisplacementConstraint)
   {
     if (!m_TransformIsStackTransform)
     {