Chi-square goodness-of-fit test on the sphere. More...

#include <mitsuba/core/chisquare.h>

Inheritance diagram for mitsuba::ChiSquare:

Public Types
enum	ETestResult { EReject = 0, EAccept = 1, ELowDoF = 2 }
	Possible outcomes in runTest() More...

Public Member Functions
	ChiSquare (int thetaBins=10, int phiBins=0, int numTests=1, size_t sampleCount=0)
	Create a new Chi-square test instance with the given resolution and sample count. More...

ELogLevel	getLogLevel () const
	Get the log level. More...

void	setLogLevel (ELogLevel logLevel)
	Set the log level. More...

void	setTolerance (Float tolerance)
	Set the tolerance threshold for bins with very low aggregate probabilities. More...

void	fill (const boost::function< boost::tuple< Vector, Float, EMeasure >()> &sampleFn, const boost::function< Float(const Vector &, EMeasure)> &pdfFn)
	Fill the actual and reference bin counts. More...

void	dumpTables (const fs::path &filename)
	Dump the bin counts to a file using MATLAB format. More...

ETestResult	runTest (Float pvalThresh=0.01f)
	Perform the actual chi-square test. More...

virtual const Class *	getClass () const
	Retrieve this object's class. More...

Public Member Functions inherited from Object
	Object ()
	Construct a new object. More...

int	getRefCount () const
	Return the current reference count. More...

void	incRef () const
	Increase the reference count of the object by one. More...

void	decRef (bool autoDeallocate=true) const
	Decrease the reference count of the object and possibly deallocate it. More...

virtual std::string	toString () const
	Return a human-readable string representation of the object's contents. More...

Static Public Attributes
static Class *	m_theClass

Static Public Attributes inherited from Object
static Class *	m_theClass
	Pointer to the object's class descriptor. More...

Protected Member Functions
virtual	~ChiSquare ()
	Release all memory. More...

Protected Member Functions inherited from Object
virtual	~Object ()
	Virtual private deconstructor. (Will only be called by ref) More...

Static Protected Member Functions
static void	integrand (const boost::function< Float(const Vector &, EMeasure)> &pdfFn, size_t nPts, const Float in, Float out)
	Functor to evaluate the pdf values in parallel using OpenMP. More...

Additional Inherited Members
Static Public Member Functions inherited from Object
static void	staticInitialization ()
	Initializes the built-in reference count debugger (if enabled) More...

static void	staticShutdown ()
	Free the memory taken by staticInitialization() More...

Detailed Description

Chi-square goodness-of-fit test on the sphere.

This class performs a chi-square goodness-of-fit test of the null hypothesis that a specified sampling procedure produces samples that are distributed according to a supplied density function. This is very useful to verify BRDF and phase function sampling codes for their correctness. Currently, it supports both 2D and discrete sampling methods and mixtures thereof.

This implementation works by generating a large batch of samples, which are then accumulated into rectangular bins in spherical coordinates. To obtain reference bin counts, the provided density function is numerically integrated over the area of each bin. Comparing the actual and reference bin counts yields the desired test statistic.

Given a probability distribution with the following interface

class MyDistribution {
    // Sample a (optionally weighted) direction. A non-unity weight
    // in the return value is needed when the sampling distribution
    // doesn't exactly match the implementation in pdf()
    boost::tuple<Vector, Float, EMeasure> generateSample() const;
    /// Compute the probability density for the specified direction and measure
    Float pdf(const Vector &direction, EMeasure) const;
};

the code in this class might be used as follows

MyDistribution myDistrInstance;
ChiSquare chiSqr;
// Initialize the tables used by the chi-square test
chiSqr.fill(
   boost::bind(&MyDistribution::generateSample, myDistrInstance),
   boost::bind(&MyDistribution::pdf, myDistrInstance, _1, _2)
);
// Optional: dump the tables to a MATLAB file for external analysis
chiSqr.dumpTables("debug.m");
if (!chiSqr.runTest())
   Log(EError, "Uh oh -- test failed, the implementation is probably incorrect!");

Member Enumeration Documentation

enum mitsuba::ChiSquare::ETestResult

Possible outcomes in runTest()

Enumerator
EReject	The null hypothesis was rejected.
EAccept	The null hypothesis was accepted.
ELowDoF	The degrees of freedom were too low.

Constructor & Destructor Documentation

mitsuba::ChiSquare::ChiSquare	(	int	thetaBins = `10`,
		int	phiBins = `0`,
		int	numTests = `1`,
		size_t	sampleCount = `0`
	)

Create a new Chi-square test instance with the given resolution and sample count.

Parameters

thetaBins	Number of bins wrt. latitude. The default is 10
phiBins	Number of bins wrt. azimuth. The default is to use twice the number of `thetaBins`
numTests	Number of independent tests that will be performed. This is used to compute the Sidak-correction factor.
sampleCount	Number of samples to be used when computing the bin values. The default is `thetaBinsphiBins5000`

virtual mitsuba::ChiSquare::~ChiSquare ( )

protectedvirtual

Release all memory.

Member Function Documentation

void mitsuba::ChiSquare::dumpTables ( const fs::path & filename )

Dump the bin counts to a file using MATLAB format.

void mitsuba::ChiSquare::fill	(	const boost::function< boost::tuple< Vector, Float, EMeasure >()> &	sampleFn,
		const boost::function< Float(const Vector &, EMeasure)> &	pdfFn
	)

Fill the actual and reference bin counts.

Please see the class documentation for a description on how to invoke this function

virtual const Class* mitsuba::ChiSquare::getClass ( ) const

virtual

Retrieve this object's class.

Reimplemented from Object.

ELogLevel mitsuba::ChiSquare::getLogLevel ( ) const

inline

Get the log level.

static void mitsuba::ChiSquare::integrand	(	const boost::function< Float(const Vector &, EMeasure)> &	pdfFn,
		size_t	nPts,
		const Float *	in,
		Float *	out
	)

inlinestaticprotected

Functor to evaluate the pdf values in parallel using OpenMP.

ETestResult mitsuba::ChiSquare::runTest ( Float pvalThresh = 0.01f )

Perform the actual chi-square test.

Parameters

pvalThresh The implementation will reject the null hypothesis when the computed p-value lies below this parameter (default: 0.01f)

Returns: A status value of type ETestResult

void mitsuba::ChiSquare::setLogLevel ( ELogLevel logLevel )

inline

Set the log level.

void mitsuba::ChiSquare::setTolerance ( Float tolerance )

inline

Set the tolerance threshold for bins with very low aggregate probabilities.

When the Chi-square test integrates the supplied probability density function over the support of a bin and determines that the aggregate bin probability is zero, the test would ordinarily fail if as much as one sample is placed in that bin in the subsequent sampling step. However, due to various numerical errors in a system based on finite-precision arithmetic, it may be a good idea to tolerate at least a few samples without immediately rejecting the null hypothesis. This parameter sets this threshold. The default value is number-of-samples*1e-4f

Member Data Documentation

Class* mitsuba::ChiSquare::m_theClass

static

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

include/mitsuba/core/chisquare.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation