Mitsuba Renderer  0.5.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
mitsuba::ChiSquare Class Reference

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 ClassgetClass () 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 Classm_theClass
 
- Static Public Attributes inherited from Object
static Classm_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

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
thetaBinsNumber of bins wrt. latitude. The default is 10
phiBinsNumber of bins wrt. azimuth. The default is to use twice the number of thetaBins
numTestsNumber of independent tests that will be performed. This is used to compute the Sidak-correction factor.
sampleCountNumber of samples to be used when computing the bin values. The default is thetaBins*phiBins*5000
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
pvalThreshThe 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: