Class for running a seemingly-unrelated regressions model. More...

#include <creativity/data/SUR.hpp>

Public Member Functions
template<class... Eqns>
	SUR (Eqns... eqns)
	Constructs an SUR solver with one or more models. More...

template<class... MoreEqns>
void	add (const Equation &eq1, MoreEqns... eqns)
	Adds one or more equations to the SUR system. More...

template<class... MoreEqns>
void	add (Equation &&eq1, MoreEqns... eqns)
	Adds one or more equations to the SUR system. More...

const std::vector< Equation > &	equations () const
	Accesses the equations used for this SUR object.

unsigned int	n () const
	Returns the number of observations for this SUR object. More...

void	gather ()
	Calculates and stores the final numerical values from the model. More...

void	solve ()
	Attempts to solve the model, if not already done. More...

void	clear ()
	Resets any values obtained or calculated by gather() or solve(), forcing the next gather() or solve() call to recalculate. More...

Eigen::VectorBlock< const Eigen::VectorXd >	beta (unsigned i) const
	Returns the vector of beta values for equation `i`

std::vector< std::string >	varNames (unsigned i) const
	Returns a vector of strings of the variable names associated with the `beta(i)` elements.

const unsigned &	k (unsigned i) const
	Returns the number of variables for equation `i` in this SUR object. More...

int	df (unsigned i) const
	Returns the degrees of freedom for equation `i`. More...

Eigen::Block< const Eigen::MatrixXd >	covariance (unsigned i) const
	Returns the covariance estimate of the beta estimators for equation `i`

Eigen::VectorBlock< const Eigen::VectorXd >	se (unsigned i) const
	Returns the standard errors (the square roots of the diagonal of covariance()) of the beta estimates for equation `i`. More...

Eigen::VectorBlock< const Eigen::VectorXd >	tRatios (unsigned i) const
	Returns the t-ratios for =0 tests for equation `i`, i.e. More...

Eigen::VectorBlock< const Eigen::VectorXd >	pValues (unsigned i) const
	Returns the p-values of the t-ratios returned by tRatios(`i`) More...

std::vector< std::string >	pStars (unsigned i, const std::map< double, std::string > &threshold=default_pstar_threshold) const
	Returns a vector of star values associated with p-value thresholds. More...

const double &	s2 (unsigned i) const
	Returns \(s^2\), the square of the regression standard error, for equation `i`. More...

Eigen::VectorBlock< const Eigen::VectorXd >	residuals (unsigned i) const
	Returns the residuals for equation `i`

const double &	ssr (unsigned i) const
	Returns the sum-of-squared residuals for equation `i`

const double &	Rsq (unsigned i) const
	Returns the \(R^2\) value for the regression for equation `i`. More...

const Eigen::VectorXd &	y () const
	Returns the y data (without solving the model); `gather()` must have been called either explicitly or by calling `solve()`. More...

Eigen::VectorBlock< const Eigen::VectorXd >	y (unsigned i) const
	Returns the sub-vector of y associated with equation `i`. More...

const std::vector< Eigen::MatrixXd > &	X () const
	Returns the X data (without solving the model); `gather()` must have been called either explicitly or by calling `solve()`. More...

Eigen::MatrixX4d	summary (unsigned i) const
	Constructs and returns a matrix of estimation results for equation `i`. More...

Static Public Attributes
static const std::map< double, std::string >	default_pstar_threshold
	Specifies the default threshold/string map for pStars, to be used if pStars is called without an explicit map. More...

Protected Member Functions
void	add ()
	Terminating recursive version of add(), not publically callable.

void	requireGathered () const
	Throws a std::logic_error if the model hasn't been gathered.

void	requireSolved () const
	Throws a std::logic_error if the model hasn't been solved.

void	requireEquation (unsigned i) const
	Throws an std::out_of_range error if the model does not have an equation with index `i`

void	requireGathered (unsigned i) const
	Shortcut for `requiredGathered(); requireEquation(i);`

void	requireSolved (unsigned i) const
	Shortcut for `requiredSolved(); requireEquation(i);`

Protected Attributes
std::vector< Equation >	eqs_
	The model, given during construction.

bool	gathered_ = false
	Whether gather() has been called, to populate y_ and X_.

Eigen::VectorXd	y_
	The y vector generated from the model.

std::vector< Eigen::MatrixXd >	X_
	The X matrix generated from the model.

std::vector< unsigned >	k_
	The model sizes.

std::vector< unsigned >	offset_
	Model beginning offsets (in beta_, var_beta_, etc.)

bool	solved_ = false
	Whether solve() has been called, to populate the below.

Eigen::VectorXd	beta_
	The whole beta vector (all equations)

Eigen::MatrixXd	var_beta_
	The estimated covariance of the beta estimators (all equations)

Eigen::VectorXd	se_
	The standard errors of the betas (all equations)

Eigen::VectorXd	t_ratios_
	t-ratios

Eigen::VectorXd	p_values_
	p-values

Eigen::VectorXd	residuals_
	Residuals (all equations)

std::vector< double >	ssr_
	SSR for each equation.

std::vector< double >	s2_
	sigma^2 estimates for each equation

std::vector< double >	R2_
	R^2 value for each equation.

Friends
std::ostream &	operator<< (std::ostream &os, const SUR &ols)
	Overloaded so that an SUR object can be sent to an output stream; the output consists of the model followed by the model results if the model has been solved; just the model itself if the model hasn't been solved.

Detailed Description

Class for running a seemingly-unrelated regressions model.

Constructor & Destructor Documentation

§ SUR()

template<class... Eqns>

creativity::data::SUR::SUR ( Eqns... eqns )

explicit

Constructs an SUR solver with one or more models.

Given arguments must be accepted by add(...) and are moved (if temporary) or copied.

See also: add()

Member Function Documentation

§ add() [1/2]

template<class... MoreEqns>

void creativity::data::SUR::add	(	const Equation &	eq1,
		MoreEqns...	eqns
	)

Adds one or more equations to the SUR system.

The first equation is copied; subsequent equations are moved (if temporary) or copied via recursive calls to add().

If the existing model has been gathered or solved, any gathered or solved values are discarded.

§ add() [2/2]

template<class... MoreEqns>

void creativity::data::SUR::add	(	Equation &&	eq1,
		MoreEqns...	eqns
	)

Adds one or more equations to the SUR system.

The first equation is moved; subsequent equations are moved (if temporary) or copied via recursive calls to add().

If the existing model has been gathered or solved, any gathered or solved values are discarded.

§ clear()

void creativity::data::SUR::clear ( )

Resets any values obtained or calculated by gather() or solve(), forcing the next gather() or solve() call to recalculate.

This method is called implicitly when adding an equation to a previously-gathered or -solved model.

§ df()

int creativity::data::SUR::df ( unsigned i ) const

Returns the degrees of freedom for equation i.

sur.df(i) is the degrees of freedom value for equation sur.equations()[i].

§ gather()

void creativity::data::SUR::gather ( )

Calculates and stores the final numerical values from the model.

This is called when needed, and does not typically need to be called explicitly.

Exceptions

Variable::SizeError if the sizes of the variables in the model do not match.

§ k()

const unsigned& creativity::data::SUR::k ( unsigned i ) const

Returns the number of variables for equation i in this SUR object.

sur.k(i) is the number of variables in equation sur.equations()[i].

§ n()

unsigned int creativity::data::SUR::n ( ) const

inline

Returns the number of observations for this SUR object.

Note that this is not the number of rows of the X matrix as returned by X(): that will generally be n() * equations().size().

Note that if an invalid SUR is constructed with multiple models of different sizes, it is undefined which equation's size will be returned (but such a model will throw an exception when attempting to gather the data to solve the model).

§ pStars()

std::vector<std::string> creativity::data::SUR::pStars	(	unsigned	i,
		const std::map< double, std::string > &	threshold = `default_pstar_threshold`
	)		const

Returns a vector of star values associated with p-value thresholds.

Takes a map of thresholds to string values: the default threshold is default_pstar_threshold.

To produce, for example, the pattern:

*** <= 0.01 < ** <= 0.05 < * <= 0.1

you would typically call pStars(i, {{0.01, "***"}, {0.05, "**"}, {0.1, "*"}})

If a p-value is larger than any given threshold value, the associated element will be an empty string.

§ pValues()

Eigen::VectorBlock<const Eigen::VectorXd> creativity::data::SUR::pValues ( unsigned i ) const

Returns the p-values of the t-ratios returned by tRatios(i)

Exceptions

std::logic_error if the model has not been solved yet by calling solve().

§ Rsq()

const double& creativity::data::SUR::Rsq ( unsigned i ) const

Returns the \(R^2\) value for the regression for equation i.

This is centered if the model contains a constant, uncentered if it does not. Note that this constant detection depends on the model's hasConstant() method; a model constructed without a constant but with a SimpleVariable that only takes on a single value will not be considered a constant for the purposes of using centering here.

§ s2()

const double& creativity::data::SUR::s2 ( unsigned i ) const

Returns \(s^2\), the square of the regression standard error, for equation i.

Exceptions

std::logic_error if the model has not been solved yet by calling solve().

§ se()

Eigen::VectorBlock<const Eigen::VectorXd> creativity::data::SUR::se ( unsigned i ) const

Returns the standard errors (the square roots of the diagonal of covariance()) of the beta estimates for equation i.

Exceptions

std::logic_error if the model has not been solved yet by calling solve().

§ solve()

void creativity::data::SUR::solve ( )

Attempts to solve the model, if not already done.

This method is called automatically by the various other methods when the solution is needed, and rarely needs to be called explicitly.

Exceptions

RankError if X has too few rows, or has non-full-rank columns.

§ summary()

Eigen::MatrixX4d creativity::data::SUR::summary ( unsigned i ) const

Constructs and returns a matrix of estimation results for equation i.

The returned matrix has the following columns, in order:

Coefficient estimate
Coefficient estimate standard error
t-ratio (for a coefficient-equals-0 test)
p-value associated with the t-ratio with one row per estimate coefficient in equation i.

This is designed to be combined, once per equation, with the tabulate() function to output an estimation summary (and is used as such if an SUR is sent to an output stream).

§ tRatios()

Eigen::VectorBlock<const Eigen::VectorXd> creativity::data::SUR::tRatios ( unsigned i ) const

Returns the t-ratios for =0 tests for equation i, i.e.

beta(i).array() / se(i).array()

Exceptions

std::logic_error if the model has not been solved yet by calling solve().

§ X()

const std::vector<Eigen::MatrixXd>& creativity::data::SUR::X ( ) const

Returns the X data (without solving the model); gather() must have been called either explicitly or by calling solve().

This is the vector of X data blocks for the entire model, that is, element [i] contains the data for equation i.

Exceptions

std::logic_error if neither gather() nor solve() has been called.

§ y() [1/2]

const Eigen::VectorXd& creativity::data::SUR::y ( ) const

Returns the y data (without solving the model); gather() must have been called either explicitly or by calling solve().

This is the y data for the entire model, that is, the y data for each equation stacked together.

Exceptions

std::logic_error if neither gather() nor solve() has been called.

§ y() [2/2]

Eigen::VectorBlock<const Eigen::VectorXd> creativity::data::SUR::y ( unsigned i ) const

Returns the sub-vector of y associated with equation i.

Exceptions

std::logic_error if neither gather() nor solve() has been called.

Member Data Documentation

§ default_pstar_threshold

const std::map<double, std::string> creativity::data::SUR::default_pstar_threshold

static

Specifies the default threshold/string map for pStars, to be used if pStars is called without an explicit map.

The default produces:

*** <= 0.001 < ** <= 0.01 < * <= 0.05 < . <= 0.1

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

creativity/data/SUR.hpp

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

§ SUR()

Member Function Documentation

§ add() [1/2]

§ add() [2/2]

§ clear()

§ df()

§ gather()

§ k()

§ n()

§ pStars()

§ pValues()

§ Rsq()

§ s2()

§ se()

§ solve()

§ summary()

§ tRatios()

§ X()

§ y() [1/2]

§ y() [2/2]

Member Data Documentation

§ default_pstar_threshold