chibarsq
=========

Purpose
-------
Computes the chi-bar-statistic and its probability for an hypothesis regarding parameters under constraints.

Format
------
.. function:: { chibar, chibarprob } = chibarsq(out, ..., c1, psi)

    :param out: instance of a :class:`cmlmtResults` structure. This structure must contain the results from a :func:`cmlmt` estimation in which the a subset of parameters is set equal to zero using c1.active -- start values for those parameters are set to zero, and c1.active is set equal to a vector of zeros and ones in which zeros correspond to the parameters in the hypothesis and ones to the remaining parameters.
    :type out: struct

    :param ...: optional arguments in the :func:`cmlmt` estimation generating out.
    :type ...: various

    :param c1: instance of a :class:`cmlmtControl` structure. It must contain the constraint specifications under the alternate hypothesis.
    :type c1: struct

    :param psi: indices of the set of parameters in the hypothesis. The indices can be determined from the list of the parameters generated by calling :func:`pvGetParnames` on the instance of the PV structure in out.
    :type psi: vector

    :return chibar: Chi-bar-square statistic of hypothesis.
    :rtype chibar: scalar

    :return chibarprob: probability of chibar.
    :rtype chibarprob: scalar

Remarks
-------
:func:`chibarsq` computes the chi-bar-square statistic for the hypothesis :math:`H(\theta) = 0 vs. H(\theta) \geq 0`, where theta is the vector of estimated parameters, and H() is a constraint function of the parameters.

First, the model with :math:`H(\theta) = 0` is estimated by calling :func:`cmlmt`. The simplest way to do this is to use the active member of the :class:`cmlmtControl` structure. The *covParType* member must also be set to 2 so that the Jacobian or score, i.e., the matrix of first derivatives by observation, is generated.

Next :func:`chibarsq` is called with the first argument being the instance of the :class:`cmlmtResults` structure output by the call to :func:`cmlmt`, the second argument the DS data structure, and the third argument the :class:`cmlmtControl` structure containing the specification of the alternate hypothesis, :math:`H(\theta) \geq 0`.