transform.hpp

Go to the documentation of this file.

#ifndef STAN__PROB__TRANSFORM_HPP
#define STAN__PROB__TRANSFORM_HPP

#include <cmath>
#include <cstddef>
#include <limits>
#include <stdexcept>
#include <sstream>
#include <vector>

#include <boost/throw_exception.hpp>
#include <boost/math/tools/promotion.hpp>

#include <stan/agrad/rev/matrix.hpp>

#include <stan/math.hpp>
#include <stan/math/error_handling.hpp>
#include <stan/math/error_handling/matrix/check_square.hpp>
#include <stan/math/matrix.hpp>

#include <stan/math/matrix/sum.hpp>
#include <stan/math/matrix_error_handling.hpp>
#include <stan/math/matrix/multiply_lower_tri_self_transpose.hpp>
#include <stan/math/matrix/meta/index_type.hpp>


namespace stan {
  
  namespace prob {


    const double CONSTRAINT_TOLERANCE = 1E-8;

    template<typename T>
    void    
    factor_U(const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& U,
             Eigen::Array<T,Eigen::Dynamic,1>& CPCs) { 

      size_t K = U.rows();
      size_t position = 0;
      size_t pull = K - 1;

      if (K == 2) {
        CPCs(0) = atanh(U(0,1));
        return;
      }

      Eigen::Array<T,1,Eigen::Dynamic> temp = U.row(0).tail(pull);

      CPCs.head(pull) = temp;

      Eigen::Array<T,Eigen::Dynamic,1> acc(K);
      acc(0) = -0.0;
      acc.tail(pull) = 1.0 - temp.square();
      for(size_t i = 1; i < (K - 1); i++) {
        position += pull;
        pull--;
        temp = U.row(i).tail(pull);
        temp /= sqrt(acc.tail(pull) / acc(i));
        CPCs.segment(position, pull) = temp;
        acc.tail(pull) *= 1.0 - temp.square();
      }
      CPCs = 0.5 * ( (1.0 + CPCs) / (1.0 - CPCs) ).log(); // now unbounded
    }
    

    template<typename T>
    bool
    factor_cov_matrix(const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& Sigma,
                      Eigen::Array<T,Eigen::Dynamic,1>& CPCs,
                      Eigen::Array<T,Eigen::Dynamic,1>& sds) {

      size_t K = sds.rows();

      sds = Sigma.diagonal().array();
      if( (sds <= 0.0).any() ) return false;
      sds = sds.sqrt();

      Eigen::DiagonalMatrix<T,Eigen::Dynamic> D(K);
      D.diagonal() = sds.inverse();
      sds = sds.log(); // now unbounded

      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> R = D * Sigma * D;
      // to hopefully prevent pivoting due to floating point error
      R.diagonal().setOnes(); 
      Eigen::LDLT<Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> > ldlt;
      ldlt = R.ldlt();
      if (!ldlt.isPositive()) 
        return false;
      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> U = ldlt.matrixU();
      factor_U(U, CPCs);
      return true;
    }

    // MATRIX TRANSFORMS +/- JACOBIANS

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_corr_L(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs, // on (-1,1)
                const size_t K) {
      Eigen::Array<T,Eigen::Dynamic,1> temp;         
      Eigen::Array<T,Eigen::Dynamic,1> acc(K-1);  
      acc.setOnes();
      // Cholesky factor of correlation matrix
      Eigen::Array<T,Eigen::Dynamic,Eigen::Dynamic> L(K,K); 
      L.setZero();

      size_t position = 0;
      size_t pull = K - 1;

      L(0,0) = 1.0;
      L.col(0).tail(pull) = temp = CPCs.head(pull);
      acc.tail(pull) = 1.0 - temp.square();
      for(size_t i = 1; i < (K - 1); i++) {
        position += pull;
        pull--;
        temp = CPCs.segment(position, pull);
        L(i,i) = sqrt(acc(i-1));
        L.col(i).tail(pull) = temp * acc.tail(pull).sqrt();
        acc.tail(pull) *= 1.0 - temp.square();
      }
      L(K-1,K-1) = sqrt(acc(K-2));
      return L.matrix();
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_corr_matrix(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs, 
                     const size_t K) {
      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> L 
        = read_corr_L(CPCs, K);
      using stan::math::multiply_lower_tri_self_transpose;
      return multiply_lower_tri_self_transpose(L);
    }
    
    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_corr_L(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs,
                const size_t K,
                T& log_prob) {

      using stan::math::log1m;
      using stan::math::square;
      using stan::math::sum;

      Eigen::Matrix<T,Eigen::Dynamic,1> values(CPCs.rows() - 1);
      size_t pos = 0;
      // no need to abs() because this Jacobian determinant 
      // is strictly positive (and triangular)
      // see inverse of Jacobian in equation 11 of LKJ paper
      for (size_t k = 1; k <= (K - 2); k++)
        for (size_t i = k + 1; i <= K; i++) {
          values(pos) = (K - k - 1) * log1m(square(CPCs(pos)));
          pos++;
        }

      log_prob += 0.5 * sum(values);
      return read_corr_L(CPCs,K);
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_corr_matrix(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs,
                     const size_t K,
                     T& log_prob) {

      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> L 
        = read_corr_L(CPCs, K, log_prob);
      using stan::math::multiply_lower_tri_self_transpose;
      return multiply_lower_tri_self_transpose(L);
    }
    
    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_cov_L(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs,
               const Eigen::Array<T,Eigen::Dynamic,1>& sds, 
               T& log_prob) {
      size_t K = sds.rows();
      // adjust due to transformation from correlations to covariances
      log_prob += (sds.log().sum() + stan::math::LOG_2) * K;
      return sds.matrix().asDiagonal() * read_corr_L(CPCs, K, log_prob);
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_cov_matrix(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs,
                    const Eigen::Array<T,Eigen::Dynamic,1>& sds, 
                    T& log_prob) {

      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> L 
        = read_cov_L(CPCs, sds, log_prob);
      using stan::math::multiply_lower_tri_self_transpose;
      return multiply_lower_tri_self_transpose(L);
    }

    template<typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    read_cov_matrix(const Eigen::Array<T,Eigen::Dynamic,1>& CPCs, 
                    const Eigen::Array<T,Eigen::Dynamic,1>& sds) {

      size_t K = sds.rows();
      Eigen::DiagonalMatrix<T,Eigen::Dynamic> D(K);
      D.diagonal() = sds;
      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> L 
        = D * read_corr_L(CPCs, K);
      using stan::math::multiply_lower_tri_self_transpose;
      return multiply_lower_tri_self_transpose(L);
    }


    template<typename T>
    const Eigen::Array<T,Eigen::Dynamic,1>
    make_nu(const T eta, const size_t K) {
      using Eigen::Array;
      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;
  
      Array<T,Dynamic,1> nu(K * (K - 1) / 2);
  
      T alpha = eta + (K - 2.0) / 2.0; // from Lewandowski et. al.

      // Best (1978) implies nu = 2 * alpha for the dof in a t 
      // distribution that generates a beta variate on (-1,1)
      T alpha2 = 2.0 * alpha; 
      for (size_type j = 0; j < (K - 1); j++) {
        nu(j) = alpha2;
      }
      size_t counter = K - 1;
      for (size_type i = 1; i < (K - 1); i++) {
        alpha -= 0.5;
        alpha2 = 2.0 * alpha;
        for (size_type j = i + 1; j < K; j++) {
          nu(counter) = alpha2;
          counter++;
        }
      }
      return nu;
    }




    // IDENTITY

    template <typename T>
    inline 
    T identity_constrain(T x) {
      return x;
    }

    template <typename T>
    inline 
    T identity_constrain(const T x, T& /*lp*/) {
      return x;
    }
    
    template <typename T> 
    inline
    T identity_free(const T y) {
      return y;
    }


    // POSITIVE

    template <typename T> 
    inline
    T positive_constrain(const T x) {
      return exp(x);
    }

    template <typename T>
    inline
    T positive_constrain(const T x, T& lp) {
      lp += x;
      return exp(x); 
    }

    template <typename T>
    inline
    T positive_free(const T y) {
      stan::math::check_positive("stan::prob::positive_free(%1%)", y, 
                                 "Positive variable", (double*)0);
      return log(y);
    }

    // LOWER BOUND

    template <typename T, typename TL>
    inline
    T lb_constrain(const T x, const TL lb) {
      if (lb == -std::numeric_limits<double>::infinity())
        return identity_constrain(x);
      return exp(x) + lb;
    }

    template <typename T, typename TL>
    inline
    typename boost::math::tools::promote_args<T,TL>::type
    lb_constrain(const T x, const TL lb, T& lp) {
      if (lb == -std::numeric_limits<double>::infinity())
        return identity_constrain(x,lp);
      lp += x;
      return exp(x) + lb;
    }

    template <typename T, typename TL>
    inline
    typename boost::math::tools::promote_args<T,TL>::type
    lb_free(const T y, const TL lb) {
      if (lb == -std::numeric_limits<double>::infinity())
        return identity_free(y);
      stan::math::check_greater_or_equal("stan::prob::lb_free(%1%)",
                                         y, lb, "Lower bounded variable",
                                         (double*)0);
      return log(y - lb);
    }
    

    // UPPER BOUND

    template <typename T, typename TU>
    inline
    typename boost::math::tools::promote_args<T,TU>::type
    ub_constrain(const T x, const TU ub) {
      if (ub == std::numeric_limits<double>::infinity())
        return identity_constrain(x);
      return ub - exp(x);
    }

    template <typename T, typename TU>
    inline
    typename boost::math::tools::promote_args<T,TU>::type
    ub_constrain(const T x, const TU ub, T& lp) {
      if (ub == std::numeric_limits<double>::infinity())
        return identity_constrain(x,lp);
      lp += x;
      return ub - exp(x);
    }

    template <typename T, typename TU>
    inline
    typename boost::math::tools::promote_args<T,TU>::type
    ub_free(const T y, const TU ub) {
      if (ub == std::numeric_limits<double>::infinity())
        return identity_free(y);
      stan::math::check_less_or_equal("stan::prob::ub_free(%1%)",
                                      y, ub, "Upper bounded variable",
                                      (double*)0);
      return log(ub - y);
    }


    // LOWER & UPPER BOUNDS

    template <typename T, typename TL, typename TU>
    inline
    typename boost::math::tools::promote_args<T,TL,TU>::type
    lub_constrain(const T x, TL lb, TU ub) {
      stan::math::check_less("lub_constrain(%1%)",lb,ub,"lb",(double*)0);

      if (lb == -std::numeric_limits<double>::infinity())
        return ub_constrain(x,ub);
      if (ub == std::numeric_limits<double>::infinity())
        return lb_constrain(x,lb);

      T inv_logit_x;
      if (x > 0) {
        T exp_minus_x = exp(-x);
        inv_logit_x = 1.0 / (1.0 + exp_minus_x);
        // Prevent x from reaching one unless it really really should.
        if ((x < std::numeric_limits<double>::infinity()) 
            && (inv_logit_x == 1))
            inv_logit_x = 1 - 1e-15;
      } else {
        T exp_x = exp(x);
        inv_logit_x = 1.0 - 1.0 / (1.0 + exp_x);
        // Prevent x from reaching zero unless it really really should.
        if ((x > -std::numeric_limits<double>::infinity()) 
            && (inv_logit_x== 0))
            inv_logit_x = 1e-15;
      }
      return lb + (ub - lb) * inv_logit_x;
    }

    template <typename T, typename TL, typename TU>
    typename boost::math::tools::promote_args<T,TL,TU>::type
    lub_constrain(const T x, const TL lb, const TU ub, T& lp) {
      if (!(lb < ub)) {
        std::stringstream s;
        s << "domain error in lub_constrain;  lower bound = " << lb
          << " must be strictly less than upper bound = " << ub;
        throw std::domain_error(s.str());
      }
      if (lb == -std::numeric_limits<double>::infinity())
        return ub_constrain(x,ub,lp);
      if (ub == std::numeric_limits<double>::infinity())
        return lb_constrain(x,lb,lp);
      T inv_logit_x;
      if (x > 0) {
        T exp_minus_x = exp(-x);
        inv_logit_x = 1.0 / (1.0 + exp_minus_x);
        lp += log(ub - lb) - x - 2 * log1p(exp_minus_x);
        // Prevent x from reaching one unless it really really should.
        if ((x < std::numeric_limits<double>::infinity()) 
            && (inv_logit_x == 1))
            inv_logit_x = 1 - 1e-15;
      } else {
        T exp_x = exp(x);
        inv_logit_x = 1.0 - 1.0 / (1.0 + exp_x);
        lp += log(ub - lb) + x - 2 * log1p(exp_x);
        // Prevent x from reaching zero unless it really really should.
        if ((x > -std::numeric_limits<double>::infinity()) 
            && (inv_logit_x== 0))
            inv_logit_x = 1e-15;
      }
      return lb + (ub - lb) * inv_logit_x;
    }

    template <typename T, typename TL, typename TU>
    inline
    typename boost::math::tools::promote_args<T,TL,TU>::type
    lub_free(const T y, TL lb, TU ub) {
      using stan::math::logit;
      stan::math::check_bounded<T, TL, TU, typename scalar_type<T>::type>
        ("stan::prob::lub_free(%1%)",
         y, lb, ub, "Bounded variable", (double*)0);
      if (lb == -std::numeric_limits<double>::infinity())
        return ub_free(y,ub);
      if (ub == std::numeric_limits<double>::infinity())
        return lb_free(y,lb);
      return logit((y - lb) / (ub - lb));
    }

    
    // PROBABILITY

    template <typename T>
    inline
    T prob_constrain(const T x) {
      using stan::math::inv_logit;
      return inv_logit(x);
    }

    template <typename T>
    inline
    T prob_constrain(const T x, T& lp) {
      using stan::math::inv_logit;
      using stan::math::log1m;
      T inv_logit_x = inv_logit(x);
      lp += log(inv_logit_x) + log1m(inv_logit_x);
      return inv_logit_x;
    }

    template <typename T>
    inline
    T prob_free(const T y) {
      using stan::math::logit;
      stan::math::check_bounded<T,double,double,T>
        ("stan::prob::prob_free(%1%)",
         y, 0, 1, "Probability variable",(double*)0);
      return logit(y);
    }
    
    
    // CORRELATION

    template <typename T>
    inline
    T corr_constrain(const T x) {
      return tanh(x);
    }

    template <typename T>
    inline
    T corr_constrain(const T x, T& lp) {
      using stan::math::log1m;
      T tanh_x = tanh(x);
      lp += log1m(tanh_x * tanh_x);
      return tanh_x;
    }

    template <typename T>
    inline
    T corr_free(const T y) {
      stan::math::check_bounded<T,double,double,double>
        ("stan::prob::lub_free(%1%)",
         y, -1, 1, "Correlation variable", (double*)0);
      return atanh(y);
    }


    // Unit vector   

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    unit_vector_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& y) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;
      int Km1 = y.size();
      Matrix<T,Dynamic,1> x(Km1 + 1);
      x(0) = 1.0;
      const T half_pi = T(M_PI/2.0);
      for (size_type k = 1; k <= Km1; ++k) {
        T yk_1 = y(k-1) + half_pi;
        T sin_yk_1 = sin(yk_1);
        x(k) = x(k-1)*sin_yk_1; 
        x(k-1) *= cos(yk_1);
      }
      return x;
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    unit_vector_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& y, T &lp) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      int Km1 = y.size();
      Matrix<T,Dynamic,1> x(Km1 + 1);
      x(0) = 1.0;
      const T half_pi = T(0.5 * M_PI);
      for (size_type k = 1; k <= Km1; ++k) {
        T yk_1 = y(k-1) + half_pi;
        T sin_yk_1 = sin(yk_1);
        x(k) = x(k-1) * sin_yk_1; 
        x(k-1) *= cos(yk_1);
        if (k < Km1)
          lp += (Km1 - k) * log(fabs(sin_yk_1));
      }
      return x;
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    unit_vector_free(const Eigen::Matrix<T,Eigen::Dynamic,1>& x) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      stan::math::check_unit_vector("stan::prob::unit_vector_free(%1%)", 
                                    x, "Unit vector variable", (double*)0);
      int Km1 = x.size() - 1;
      Matrix<T,Dynamic,1> y(Km1);
      T sumSq = x(Km1)*x(Km1);
      const T half_pi = T(M_PI/2.0);
      for (size_type k = Km1; --k >= 0; ) {
        y(k) = atan2(sqrt(sumSq),x(k)) - half_pi;
        sumSq += x(k)*x(k);
      }
      return y;
    }


    // SIMPLEX

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    simplex_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& y) {

      // cut & paste simplex_constrain(Eigen::Matrix,T) w/o Jacobian
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      using stan::math::inv_logit;
      using stan::math::logit;
      using stan::math::log1m;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;


      int Km1 = y.size();
      Matrix<T,Dynamic,1> x(Km1 + 1);
      T stick_len(1.0);
      for (size_type k = 0; k < Km1; ++k) {
        T z_k(inv_logit(y(k) - log(Km1 - k))); 
        x(k) = stick_len * z_k;
        stick_len -= x(k); 
      }
      x(Km1) = stick_len;
      return x;
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    simplex_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& y, 
                      T& lp) {

      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      using stan::math::inv_logit;
      using stan::math::logit;
      using stan::math::log1m;
      using stan::math::log1p_exp;

      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      int Km1 = y.size(); // K = Km1 + 1
      Matrix<T,Dynamic,1> x(Km1 + 1);
      T stick_len(1.0);
      for (size_type k = 0; k < Km1; ++k) {
        double eq_share = -log(Km1 - k); // = logit(1.0/(Km1 + 1 - k));
        T adj_y_k(y(k) + eq_share);
        T z_k(inv_logit(adj_y_k));
        x(k) = stick_len * z_k;
        lp += log(stick_len);
        lp -= log1p_exp(-adj_y_k);
        lp -= log1p_exp(adj_y_k);
        stick_len -= x(k); // equivalently *= (1 - z_k);
      }
      x(Km1) = stick_len; // no Jacobian contrib for last dim
      return x;
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    simplex_free(const Eigen::Matrix<T,Eigen::Dynamic,1>& x) {
      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      using stan::math::logit;

      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      stan::math::check_simplex("stan::prob::simplex_free(%1%)", x, "Simplex variable",
                                (double*)0);
      int Km1 = x.size() - 1;
      Eigen::Matrix<T,Eigen::Dynamic,1> y(Km1);
      T stick_len(x(Km1));
      for (size_type k = Km1; --k >= 0; ) {
        stick_len += x(k);
        T z_k(x(k) / stick_len);
        y(k) = logit(z_k) + log(Km1 - k); 
        // note: log(Km1 - k) = logit(1.0 / (Km1 + 1 - k));
      }
      return y;
    }


    // ORDERED 
    
    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    ordered_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;

      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      size_type k = x.size();
      Matrix<T,Dynamic,1> y(k);
      if (k == 0)
        return y;
      y[0] = x[0];
      for (size_type i = 1; i < k; ++i)
        y[i] = y[i-1] + exp(x[i]);
      return y;
    }

    template <typename T>
    inline
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    ordered_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, T& lp) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;

      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      for (size_type i = 1; i < x.size(); ++i)
        lp += x(i);
      return ordered_constrain(x);
    }



    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    ordered_free(const Eigen::Matrix<T,Eigen::Dynamic,1>& y) {
      stan::math::check_ordered("stan::prob::ordered_free(%1%)", 
                                y, "Ordered variable");
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      size_type k = y.size();
      Matrix<T,Dynamic,1> x(k);
      if (k == 0) 
        return x;
      x[0] = y[0];
      for (size_type i = 1; i < k; ++i)
        x[i] = log(y[i] - y[i-1]);
      return x;
    }
    

    // POSITIVE ORDERED 
    
    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    positive_ordered_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      size_type k = x.size();
      Matrix<T,Dynamic,1> y(k);
      if (k == 0)
        return y;
      y[0] = exp(x[0]);
      for (size_type i = 1; i < k; ++i)
        y[i] = y[i-1] + exp(x[i]);
      return y;
    }

    template <typename T>
    inline
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    positive_ordered_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, T& lp) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      for (size_type i = 0; i < x.size(); ++i)
        lp += x(i);
      return positive_ordered_constrain(x);
    }



    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    positive_ordered_free(const Eigen::Matrix<T,Eigen::Dynamic,1>& y) {
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::index_type;

      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      stan::math::check_positive_ordered("stan::prob::positive_ordered_free(%1%)", 
                                         y, "Positive ordered variable", (double*)0);

      size_type k = y.size();
      Matrix<T,Dynamic,1> x(k);
      if (k == 0) 
        return x;
      x[0] = log(y[0]);
      for (size_type i = 1; i < k; ++i)
        x[i] = log(y[i] - y[i-1]);
      return x;
    }
    

    // CHOLESKY FACTOR

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    cholesky_factor_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x,
                              int M,
                              int N) {
      using std::exp;
      if (M < N)
        throw std::domain_error("cholesky_factor_constrain: num rows must be >= num cols");
      if (x.size() != ((N * (N + 1)) / 2 + (M - N) * N))
        throw std::domain_error("cholesky_factor_constrain: x.size() must"
                                " be (N * (N + 1)) / 2 + (M - N) * N");
      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> y(M,N);
      T zero(0);
      int pos = 0;
      // upper square
      for (int m = 0; m < N; ++m) {
        for (int n = 0; n < m; ++n)
          y(m,n) = x(pos++);
        y(m,m) = exp(x(pos++));
        for (int n = m + 1; n < N; ++n)
          y(m,n) = zero;
      }
      // lower rectangle
      for (int m = N; m < M; ++m)
        for (int n = 0; n < N; ++n)
          y(m,n) = x(pos++);
      return y;
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    cholesky_factor_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x,
                              int M,
                              int N,
                              T& lp) {
      // cut-and-paste from above, so checks twice

      using stan::math::sum;
      if (x.size() != ((N * (N + 1)) / 2 + (M - N) * N))
        throw std::domain_error("cholesky_factor_constrain: x.size() must be (k choose 2) + k");
      int pos = 0;
      std::vector<T> log_jacobians(N);
      for (int n = 0; n < N; ++n) {
        pos += n;
        log_jacobians[n] = x(pos++);
      }
      lp += sum(log_jacobians);  // optimized for autodiff vs. direct lp += 
      return cholesky_factor_constrain(x,M,N);
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1>
    cholesky_factor_free(const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& y) {
      using std::log;
      double result;
      if (!stan::math::check_cholesky_factor("cholesky_factor_free(%1%)",y,"y",&result))
        throw std::domain_error("cholesky_factor_free: y is not a Cholesky factor");
      int M = y.rows();
      int N = y.cols();
      Eigen::Matrix<T,Eigen::Dynamic,1> x((N * (N + 1)) / 2 + (M - N) * N);
      int pos = 0;
      // lower triangle of upper square
      for (int m = 0; m < N; ++m) {
        for (int n = 0; n < m; ++n)
          x(pos++) = y(m,n);
        // diagonal of upper square
        x(pos++) = log(y(m,m));
      }
      // lower rectangle
      for (int m = N; m < M; ++m)
        for (int n = 0; n < N; ++n)
          x(pos++) = y(m,n);
      return x;
    }

    // CHOLESKY CORRELATION MATRIX

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    cholesky_corr_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& y,
                            int K) {
      using std::sqrt;
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::square;
      int k_choose_2 = (K * (K - 1)) / 2;
      if (k_choose_2 != y.size()) {
        std::cout << "k_choose_2 = " << k_choose_2 << " y.size()=" << y.size() << std::endl;
        throw std::domain_error("y is not a valid unconstrained cholesky correlation matrix."
                                "Require (K choose 2) elements in y.");
      }
      Matrix<T,Dynamic,1> z(k_choose_2);
      for (int i = 0; i < k_choose_2; ++i)
        z(i) = corr_constrain(y(i));
      Matrix<T,Dynamic,Dynamic> x(K,K);
      if (K == 0) return x;
      T zero(0);
      for (int j = 1; j < K; ++j)
        for (int i = 0; i < j; ++i)
          x(i,j) = zero;
      x(0,0) = 1;
      int k = 0;
      for (int i = 1; i < K; ++i) {
        x(i,0) = z(k++);
        T sum_sqs(square(x(i,0)));
        for (int j = 1; j < i; ++j) {
          x(i,j) = z(k++) * sqrt(1.0 - sum_sqs);
          sum_sqs += square(x(i,j));
        }
        x(i,i) = sqrt(1.0 - sum_sqs);
      }
      return x;
    }

    // FIXME to match above after debugged
    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>
    cholesky_corr_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& y,
                            int K,
                            T& lp) {
      using std::sqrt;
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::log1m;
      using stan::math::square;
      int k_choose_2 = (K * (K - 1)) / 2;
      if (k_choose_2 != y.size()) {
        std::cout << "k_choose_2 = " << k_choose_2 << " y.size()=" << y.size() << std::endl;
        throw std::domain_error("y is not a valid unconstrained cholesky correlation matrix."
                                " Require (K choose 2) elements in y.");
      }
      Matrix<T,Dynamic,1> z(k_choose_2);
      for (int i = 0; i < k_choose_2; ++i)
        z(i) = corr_constrain(y(i),lp);
      Matrix<T,Dynamic,Dynamic> x(K,K);
      if (K == 0) return x;
      T zero(0);
      for (int j = 1; j < K; ++j)
        for (int i = 0; i < j; ++i)
          x(i,j) = zero;
      x(0,0) = 1;
      int k = 0;
      for (int i = 1; i < K; ++i) {
        x(i,0) = z(k++);
        T sum_sqs = square(x(i,0));
        for (int j = 1; j < i; ++j) {
          lp += 0.5 * log1m(sum_sqs);
          x(i,j) = z(k++) * sqrt(1.0 - sum_sqs);
          sum_sqs += square(x(i,j));
        }
        x(i,i) = sqrt(1.0 - sum_sqs);
      }
      return x;
    }

    

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1>
    cholesky_corr_free(const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& x) {
      using std::sqrt;
      using Eigen::Matrix;
      using Eigen::Dynamic;
      using stan::math::square;

      double bad_result; // won't be used
      stan::math::check_square("cholesky_corr_free",x,"x",&bad_result);
      // should validate lower-triangular, unit lengths

      int K = (x.rows() * (x.rows() - 1)) / 2;
      Matrix<T,Dynamic,1> z(K);
      int k = 0;
      for (int i = 1; i < x.rows(); ++i) {
        z(k++) = corr_free(x(i,0));
        double sum_sqs = square(x(i,0));
        for (int j = 1; j < i; ++j) {
          z(k++) = corr_free(x(i,j) / sqrt(1.0 - sum_sqs));
          sum_sqs += square(x(i,j));
        }
      }
      return z;
    }

    // CORRELATION MATRIX

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> 
    corr_matrix_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x,
                  typename math::index_type<Eigen::Matrix<T,Eigen::Dynamic,1> >::type k) {

      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      size_type k_choose_2 = (k * (k - 1)) / 2;
      if (k_choose_2 != x.size())
        throw std::invalid_argument ("x is not a valid correlation matrix");
      Eigen::Array<T,Eigen::Dynamic,1> cpcs(k_choose_2);
      for (size_type i = 0; i < k_choose_2; ++i)
        cpcs[i] = corr_constrain(x[i]);
      return read_corr_matrix(cpcs,k); 
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> 
    corr_matrix_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, 
                  typename math::index_type<Eigen::Matrix<T,Eigen::Dynamic,1> >::type k,
                  T& lp) {
      using Eigen::Array;
      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;
  
      size_type k_choose_2 = (k * (k - 1)) / 2;
      if (k_choose_2 != x.size())
        throw std::invalid_argument ("x is not a valid correlation matrix");
      Array<T,Dynamic,1> cpcs(k_choose_2);
      for (size_type i = 0; i < k_choose_2; ++i)
        cpcs[i] = corr_constrain(x[i],lp);
      return read_corr_matrix(cpcs,k,lp);
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    corr_matrix_free(const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& y) {
      using Eigen::Array;
      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,1> >::type size_type;

      size_type k = y.rows();
      if (y.cols() != k)
        throw std::domain_error("y is not a square matrix");
      if (k == 0)
        throw std::domain_error("y has no elements");
      size_type k_choose_2 = (k * (k-1)) / 2;
      Array<T,Dynamic,1> x(k_choose_2);
      Array<T,Dynamic,1> sds(k);
      bool successful = factor_cov_matrix(y,x,sds);
      if (!successful)
        throw std::runtime_error("factor_cov_matrix failed on y");
      for (size_type i = 0; i < k; ++i) {
        // sds on log scale unconstrained
        if (fabs(sds[i] - 0.0) >= CONSTRAINT_TOLERANCE) {
          std::stringstream s;
          s << "all standard deviations must be zero."
            << " found log(sd[" << i << "])=" << sds[i] << std::endl;
          BOOST_THROW_EXCEPTION(std::runtime_error(s.str()));
        }
      }
      return x.matrix();
    }


    // COVARIANCE MATRIX

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> 
    cov_matrix_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, 
                 typename math::index_type<Eigen::Matrix<T,Eigen::Dynamic,1> >::type K) {
      using std::exp;

      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      using stan::math::multiply_lower_tri_self_transpose;
      typedef typename index_type<Matrix<T,Dynamic,Dynamic> >::type size_type;

      Matrix<T,Dynamic,Dynamic> L(K,K);
      if (x.size() != (K * (K + 1)) / 2) 
        throw std::domain_error("x.size() != K + (K choose 2)");
      int i = 0;
      for (size_type m = 0; m < K; ++m) {
        for (int n = 0; n < m; ++n)
          L(m,n) = x(i++);
        L(m,m) = exp(x(i++));
        for (size_type n = m + 1; n < K; ++n) 
          L(m,n) = 0.0;
      }
      return multiply_lower_tri_self_transpose(L); 
    }

    
    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> 
    cov_matrix_constrain(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, 
         typename math::index_type<Eigen::Matrix<T,
                                                 Eigen::Dynamic,
                                                 Eigen::Dynamic> >::type K,
         T& lp) {
      using std::exp;

      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,Dynamic> >::type size_type;

      if (x.size() != (K * (K + 1)) / 2) 
        throw std::domain_error("x.size() != K + (K choose 2)");
      Matrix<T,Dynamic,Dynamic> L(K,K);
      int i = 0;
      for (size_type m = 0; m < K; ++m) {
        for (size_type n = 0; n < m; ++n)
          L(m,n) = x(i++);
        L(m,m) = exp(x(i++));
        for (size_type n = m + 1; n < K; ++n) 
          L(m,n) = 0.0;
      }
      // Jacobian for complete transform, including exp() above
      lp += (K * stan::math::LOG_2); // needless constant; want propto
      for (int k = 0; k < K; ++k)
        lp += (K - k + 1) * log(L(k,k)); // only +1 because index from 0
      return L * L.transpose();
      // return tri_multiply_transpose(L); 
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    cov_matrix_free(const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& y) {
      using std::log;
      int K = y.rows();
      if (y.cols() != K)
        throw std::domain_error("y is not a square matrix");
      if (K == 0)
        throw std::domain_error("y has no elements");
      for (int k = 0; k < K; ++k)
        if (!(y(k,k) > 0.0)) 
          throw std::domain_error("y has non-positive diagonal");
      Eigen::Matrix<T,Eigen::Dynamic,1> x((K * (K + 1)) / 2);
      // FIXME: see Eigen LDLT for rank-revealing version -- use that
      // even if less efficient?
      Eigen::LLT<Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> > 
        llt(y.rows());
      llt.compute(y);
      Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> L = llt.matrixL();
      int i = 0;
      for (int m = 0; m < K; ++m) {
        for (int n = 0; n < m; ++n)
          x(i++) = L(m,n);
        x(i++) = log(L(m,m));
      }
      return x;
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> 
    cov_matrix_constrain_lkj(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, 
                         size_t k) {
      size_t k_choose_2 = (k * (k - 1)) / 2;
      Eigen::Array<T,Eigen::Dynamic,1> cpcs(k_choose_2);
      int pos = 0;
      for (size_t i = 0; i < k_choose_2; ++i)
        cpcs[i] = corr_constrain(x[pos++]);
      Eigen::Array<T,Eigen::Dynamic,1> sds(k);
      for (size_t i = 0; i < k; ++i)
        sds[i] = positive_constrain(x[pos++]);
      return read_cov_matrix(cpcs, sds);
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic> 
    cov_matrix_constrain_lkj(const Eigen::Matrix<T,Eigen::Dynamic,1>& x, 
                         size_t k, 
                         T& lp) {
      size_t k_choose_2 = (k * (k - 1)) / 2;
      Eigen::Array<T,Eigen::Dynamic,1> cpcs(k_choose_2);
      int pos = 0;
      for (size_t i = 0; i < k_choose_2; ++i)
        cpcs[i] = corr_constrain(x[pos++], lp);
      Eigen::Array<T,Eigen::Dynamic,1> sds(k);
      for (size_t i = 0; i < k; ++i)
        sds[i] = positive_constrain(x[pos++],lp);
      return read_cov_matrix(cpcs, sds, lp);
    }

    template <typename T>
    Eigen::Matrix<T,Eigen::Dynamic,1> 
    cov_matrix_free_lkj(
            const Eigen::Matrix<T,Eigen::Dynamic,Eigen::Dynamic>& y) {

      using Eigen::Array;
      using Eigen::Dynamic;
      using Eigen::Matrix;
      using stan::math::index_type;
      typedef typename index_type<Matrix<T,Dynamic,Dynamic> >::type size_type;

      size_type k = y.rows();
      if (y.cols() != k)
        throw std::domain_error("y is not a square matrix");
      if (k == 0)
        throw std::domain_error("y has no elements");
      size_type k_choose_2 = (k * (k-1)) / 2;
      Array<T,Dynamic,1> cpcs(k_choose_2);
      Array<T,Dynamic,1> sds(k);
      bool successful = factor_cov_matrix(y,cpcs,sds);
      if (!successful)
        throw std::runtime_error ("factor_cov_matrix failed on y");
      Matrix<T,Dynamic,1> x(k_choose_2 + k);
      size_type pos = 0;
      for (size_type i = 0; i < k_choose_2; ++i)
        x[pos++] = cpcs[i];
      for (size_type i = 0; i < k; ++i)
        x[pos++] = sds[i];
      return x;
    }

  }

}

#endif