Detailed Description

Implementation of the "Geman-McClure" robust error model (Zhang97ivc).

Note that Geman-McClure weight function uses the parameter c == 1.0, but here it's allowed to use different values, so we actually have the generalized Geman-McClure from (Agarwal15phd).

Loss \rho(x) = 0.5 (c²x²)/(c²+x²)
Derivative \phi(x) = xc⁴/(c²+x²)²
Weight w(x) = \phi(x)/x = c⁴/(c²+x²)²

Geman-McClure loss has two graduated forms

STANDARD [1] is the normalized form of the Yang GNC-GM surrogate. It relaxes the shape parameter by the historical \lambda = 1 / \mu, i.e. it evaluates the Geman-McClure loss above with c² replaced by c²/\mu.

Loss \rho(x,\mu) = 0.5 ((c²/\mu)x²)/((c²/\mu)+x²)
Derivative \phi(x,\mu) = x(c²/\mu)²/((c²/\mu)+x²)²
Weight w(x,\mu) = \phi(x)/x = (c²/\mu)²/((c²/\mu)+x²)² Both endpoints are exact: \mu = 1 is Geman-McClure, and \mu = 0 is the least-squares limit (\rho = 0.5x², w = 1), evaluated directly rather than by letting c²/\mu diverge.

SCALE_INVARIANT [2] is graduated according to the following form.

Loss \rho(x) = 0.5 (c²x²)/(c²+(x²)^\mu)
Derivative \phi(x) = x(c²(c²+(x²)^\mu * (1-\mu)))/(c²+(x²)^\mu)²
Weight w(x) = \phi(x)/x = (c²(c²+(x²)^\mu * (1-\mu)))/(c²+(x²)^\mu)²

Inheritance diagram for gtsam::noiseModel::mEstimator::GemanMcClure:

Public Member Functions
	GemanMcClure (double c=1.0, const ReweightScheme reweight=Block)
	Construct standard GemanMcClure loss.
	GemanMcClure (double c, const GradScheme graduation, const ReweightScheme reweight=Block)
	Constructor for a loss with an explicit graduation scheme.
double	weight (double distance) const override
	This method is responsible for returning the weight function for a given amount of error.
double	loss (double distance) const override
	This method is responsible for returning the total penalty for a given amount of error.
double	graduatedWeight (double distance, double mu) const override
	This method is responsible for returning the weight for a given amount of error and the current control parameter \(\mu\).
double	graduatedLoss (double distance, double mu) const override
	This method is responsible for returning the total penalty for a given amount of error and the current control parameter \(\mu\).
void	print (const std::string &s) const override
bool	equals (const Base &expected, double tol=1e-8) const override
double	modelParameter () const
GradScheme	gradScheme () const
	Returns the graduation scheme used by this loss.
Public Member Functions inherited from gtsam::noiseModel::mEstimator::Base
	Base (const ReweightScheme reweight=Block)
ReweightScheme	reweightScheme () const
	Returns the reweight scheme, as explained in ReweightScheme.
double	sqrtWeight (double distance) const
Vector	weight (const Vector &error) const
	produce a weight vector according to an error vector and the implemented robust function
Vector	sqrtWeight (const Vector &error) const
	square root version of the weight function
void	reweight (Vector &error) const
	reweight block matrices and a vector according to their weight implementation
void	reweight (std::vector< Matrix > &A, Vector &error) const
void	reweight (Matrix &A, Vector &error) const
void	reweight (Matrix &A1, Matrix &A2, Vector &error) const
void	reweight (Matrix &A1, Matrix &A2, Matrix &A3, Vector &error) const

Static Public Member Functions
static shared_ptr	Create (double k, const ReweightScheme reweight=Block)
static shared_ptr	Create (double k, const GradScheme graduation, const ReweightScheme reweight=Block)
	Factory for a loss with an explicit graduation scheme.
static double	Weight (double distance2, double c2)
	A static helper function to compute the Geman-McClure robust weight.
static double	Loss (double distance2, double c2)
	Static implementation of GemanMcClure Loss.
static double	GraduatedWeight (double distance2, double c2, double mu, GradScheme graduation)
	Static implementation of GemanMcClure Graduated Weight.
static double	GraduatedLoss (double distance2, double c2, double mu, GradScheme graduation)
	Static implementation of GemanMcClure Graduated Loss.
static double	ShapeParameterFromInfluenceThreshold (double influenceThreshold, size_t dof, double chiSquaredOutlierThreshold)
	Static helper to compute shape param (c) using outlier influence.

Public Types
enum	GradScheme { STANDARD , SCALE_INVARIANT }
typedef std::shared_ptr< GemanMcClure >	shared_ptr
Public Types inherited from gtsam::noiseModel::mEstimator::Base
enum	ReweightScheme { Scalar , Block }
	the rows can be weighted independently according to the error or uniformly with the norm of the right hand side
typedef std::shared_ptr< Base >	shared_ptr

Protected Attributes
double	c_
double	csquared_
GradScheme	graduation_
Protected Attributes inherited from gtsam::noiseModel::mEstimator::Base
ReweightScheme	reweight_
	Strategy for reweighting.

Member Function Documentation

◆ equals()

bool gtsam::noiseModel::mEstimator::GemanMcClure::equals	(	const Base &	expected,
		double	tol = 1e-8 ) const

overridevirtual

Implements gtsam::noiseModel::mEstimator::Base.

◆ graduatedLoss()

double gtsam::noiseModel::mEstimator::GemanMcClure::graduatedLoss	(	double	distance,
		double	mu ) const

overridevirtual

This method is responsible for returning the total penalty for a given amount of error and the current control parameter \(\mu\).

This returns \(\rho(x, \mu)\) in mEstimator

Implements gtsam::noiseModel::mEstimator::Base.

◆ graduatedWeight()

double gtsam::noiseModel::mEstimator::GemanMcClure::graduatedWeight	(	double	distance,
		double	mu ) const

overridevirtual

This method is responsible for returning the weight for a given amount of error and the current control parameter \(\mu\).

This returns \(w(x, \mu)\) in mEstimator

Implements gtsam::noiseModel::mEstimator::Base.

◆ loss()

double gtsam::noiseModel::mEstimator::GemanMcClure::loss ( double distance ) const

overridevirtual

This method is responsible for returning the total penalty for a given amount of error.

For example, this method is responsible for implementing the quadratic function for an L2 penalty, the absolute value function for an L1 penalty, etc.

TODO(mikebosse): When the loss function has as input the norm of the error vector, then it prevents implementations of asymmeric loss functions. It would be better for this function to accept the vector and internally call the norm if necessary.

This returns \(\rho(x)\) in mEstimator

Reimplemented from gtsam::noiseModel::mEstimator::Base.

◆ print()

void gtsam::noiseModel::mEstimator::GemanMcClure::print ( const std::string & s = "" ) const

overridevirtual

Implements gtsam::noiseModel::mEstimator::Base.

◆ ShapeParameterFromInfluenceThreshold()

double gtsam::noiseModel::mEstimator::GemanMcClure::ShapeParameterFromInfluenceThreshold	(	double	influenceThreshold,
		size_t	dof,
		double	chiSquaredOutlierThreshold )

static

Static helper to compute shape param (c) using outlier influence.

Computes a shape param such that an outlier will have: d/dx(\rho(x)) <= influenceThreshold

Parameters

influenceThreshold	- The max influence permited by an outlier. Must be in (0, sqrt(chi2 quantile))
dof	- The degrees of freedom of the corresponding measurement
chiSquaredOutlierThreshold	- The threshold for outlier (i.e. 0.95). Must be in [0,1]

Exceptions

std::invalid_argument if influenceThreshold is outside that range.

Returns: The shape param

◆ weight()

double gtsam::noiseModel::mEstimator::GemanMcClure::weight ( double distance ) const

overridevirtual

This method is responsible for returning the weight function for a given amount of error.

The weight function is related to the analytic derivative of the loss function. See https://members.loria.fr/MOBerger/Enseignement/Master2/Documents/ZhangIVC-97-01.pdf for details. This method is required when optimizing cost functions with robust penalties using iteratively re-weighted least squares.

This returns w(x) in mEstimator

Implements gtsam::noiseModel::mEstimator::Base.

The documentation for this class was generated from the following files:

/tmp/gtsam-4.3.0-doxygen.rsXPUS/source/gtsam/linear/LossFunctions.h
/tmp/gtsam-4.3.0-doxygen.rsXPUS/source/gtsam/linear/LossFunctions.cpp

Detailed Description

Public Member Functions

Static Public Member Functions

Public Types

Protected Attributes

Member Function Documentation

◆ equals()

◆ graduatedLoss()

◆ graduatedWeight()

◆ loss()

◆ print()

◆ ShapeParameterFromInfluenceThreshold()

◆ weight()