update naming to be row and column stochastic matrices

SteveBronder · SteveBronder · commit d819287bdbf5 · 2024-02-29T13:46:28.000-05:00
diff --git a/stan/math/prim/fun.hpp b/stan/math/prim/fun.hpp
@@ -315,12 +315,8 @@
 #include <stan/math/prim/fun/select.hpp>
 #include <stan/math/prim/fun/sign.hpp>
 #include <stan/math/prim/fun/signbit.hpp>
-#include <stan/math/prim/fun/simplex_column_constrain.hpp>
-#include <stan/math/prim/fun/simplex_column_free.hpp>
 #include <stan/math/prim/fun/simplex_constrain.hpp>
 #include <stan/math/prim/fun/simplex_free.hpp>
-#include <stan/math/prim/fun/simplex_row_constrain.hpp>
-#include <stan/math/prim/fun/simplex_row_free.hpp>
 #include <stan/math/prim/fun/sin.hpp>
 #include <stan/math/prim/fun/singular_values.hpp>
 #include <stan/math/prim/fun/sinh.hpp>
@@ -338,6 +334,10 @@
 #include <stan/math/prim/fun/squared_distance.hpp>
 #include <stan/math/prim/fun/stan_print.hpp>
 #include <stan/math/prim/fun/step.hpp>
+#include <stan/math/prim/fun/stochastic_column_constrain.hpp>
+#include <stan/math/prim/fun/stochastic_column_free.hpp>
+#include <stan/math/prim/fun/stochastic_row_constrain.hpp>
+#include <stan/math/prim/fun/stochastic_row_free.hpp>
 #include <stan/math/prim/fun/sub_col.hpp>
 #include <stan/math/prim/fun/sub_row.hpp>
 #include <stan/math/prim/fun/subtract.hpp>
diff --git a/stan/math/prim/fun/stochastic_column_constrain.hpp b/stan/math/prim/fun/stochastic_column_constrain.hpp
@@ -14,10 +14,7 @@ namespace stan {
 namespace math {
 
 /**
- * Return a matrix with columns as simplex vectors.
- * A simplex is a vector containing values greater than or equal
- * to 0 that sum to 1.  A vector with (K-1) unconstrained values
- * will produce a simplex of size K.
+ * Return a column stochastic matrix.
  *
  * The transform is based on a centered stick-breaking process.
  *
@@ -27,8 +24,7 @@ namespace math {
  */
 template <typename Mat, require_eigen_matrix_dynamic_t<Mat>* = nullptr,
           require_not_st_var<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_column_constrain(const Mat& y) {
-  // cut & paste simplex_column_constrain(Eigen::Matrix, T) w/o Jacobian
+inline plain_type_t<Mat> stochastic_column_constrain(const Mat& y) {
   auto&& y_ref = to_ref(y);
   const Eigen::Index M = y_ref.cols();
   plain_type_t<Mat> ret(y_ref.rows() + 1, M);
@@ -39,7 +35,7 @@ inline plain_type_t<Mat> simplex_column_constrain(const Mat& y) {
 }
 
 /**
- * Return a matrix with columns as simplex vectors
+ * Return a column stochastic matrix
  * and increment the specified log probability reference with
  * the log absolute Jacobian determinant of the transform.
  *
@@ -49,11 +45,11 @@ inline plain_type_t<Mat> simplex_column_constrain(const Mat& y) {
  * @tparam Mat type of the Matrix
  * @param y Free Matrix input of dimensionality (K - 1, M)
  * @param lp Log probability reference to increment.
- * @return Matrix with simplex columns of dimensionality (K, M)
+ * @return Matrix with stochastic columns of dimensionality (K, M)
  */
 template <typename Mat, require_eigen_matrix_dynamic_t<Mat>* = nullptr,
           require_not_st_var<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_column_constrain(const Mat& y,
+inline plain_type_t<Mat> stochastic_column_constrain(const Mat& y,
                                                   value_type_t<Mat>& lp) {
   auto&& y_ref = to_ref(y);
   const Eigen::Index M = y_ref.cols();
@@ -65,7 +61,7 @@ inline plain_type_t<Mat> simplex_column_constrain(const Mat& y,
 }
 
 /**
- * Return a matrix with columns as simplex vectors. If the
+ * Return a column stochastic matrix. If the
  * `Jacobian` parameter is `true`, the log density accumulator is incremented
  * with the log absolute Jacobian determinant of the transform.  All of the
  * transforms are specified with their Jacobians in the *Stan Reference Manual*
@@ -79,17 +75,17 @@ inline plain_type_t<Mat> simplex_column_constrain(const Mat& y,
  * @return Matrix with simplex columns of dimensionality (K, M).
  */
 template <bool Jacobian, typename Mat, require_not_std_vector_t<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_column_constrain(const Mat& y,
+inline plain_type_t<Mat> stochastic_column_constrain(const Mat& y,
                                                   return_type_t<Mat>& lp) {
   if (Jacobian) {
-    return simplex_column_constrain(y, lp);
+    return stochastic_column_constrain(y, lp);
   } else {
-    return simplex_column_constrain(y);
+    return stochastic_column_constrain(y);
   }
 }
 
 /**
- * Return a standard vector of matrices with columns as simplex vectors. If the
+ * Return a vector of column stochastic matrices. If the
  * `Jacobian` parameter is `true`, the log density accumulator is incremented
  * with the log absolute Jacobian determinant of the transform.  All of the
  * transforms are specified with their Jacobians in the *Stan Reference Manual*
@@ -106,9 +102,9 @@ inline plain_type_t<Mat> simplex_column_constrain(const Mat& y,
  * dimensionality (K, M).
  */
 template <bool Jacobian, typename T, require_std_vector_t<T>* = nullptr>
-inline auto simplex_column_constrain(const T& y, return_type_t<T>& lp) {
+inline auto stochastic_column_constrain(const T& y, return_type_t<T>& lp) {
   return apply_vector_unary<T>::apply(
-      y, [&lp](auto&& v) { return simplex_column_constrain<Jacobian>(v, lp); });
+      y, [&lp](auto&& v) { return stochastic_column_constrain<Jacobian>(v, lp); });
 }
 
 }  // namespace math
diff --git a/stan/math/prim/fun/stochastic_column_free.hpp b/stan/math/prim/fun/stochastic_column_free.hpp
@@ -1,5 +1,5 @@
-#ifndef STAN_MATH_PRIM_FUN_SIMPLEX_COLUMN_FREE_HPP
-#define STAN_MATH_PRIM_FUN_SIMPLEX_COLUMN_FREE_HPP
+#ifndef STAN_MATH_PRIM_FUN_STOCHASTIC_COLUMN_FREE_HPP
+#define STAN_MATH_PRIM_FUN_STOCHASTIC_COLUMN_FREE_HPP
 
 #include <stan/math/prim/meta.hpp>
 #include <stan/math/prim/fun/Eigen.hpp>
@@ -10,16 +10,16 @@ namespace math {
 
 /**
  * Return an unconstrained matrix that when transformed produces
- * the specified columnwise simplex matrix.  It applies to a simplex of
+ * the specified columnwise stochastic matrix.  It applies to a stochastic matrix of
  * dimensionality (N, K) and produces an unconstrained vector of dimensionality
  * (N - 1, K).
  *
  * @tparam Mat type of the Matrix
- * @param y Columnwise simplex matrix input of dimensionality (N, K)
+ * @param y Columnwise stochastic matrix input of dimensionality (N, K)
  */
 template <typename Mat, require_eigen_matrix_dynamic_t<Mat>* = nullptr,
           require_not_st_var<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_column_free(const Mat& y) {
+inline plain_type_t<Mat> stochastic_column_free(const Mat& y) {
   auto&& y_ref = to_ref(y);
   const Eigen::Index M = y_ref.cols();
   plain_type_t<Mat> ret(y_ref.rows() - 1, M);
@@ -34,12 +34,12 @@ inline plain_type_t<Mat> simplex_column_free(const Mat& y) {
  *
  * @tparam T A standard vector with inner type inheriting from
  * `Eigen::DenseBase` with compile time dynamic rows and dynamic rows
- * @param[in] y vector of columnwise simplex matrix of size (N, K)
+ * @param[in] y vector of columnwise stochastic matrix of size (N, K)
  */
 template <typename T, require_std_vector_t<T>* = nullptr>
-inline auto simplex_column_free(const T& y) {
+inline auto stochastic_column_free(const T& y) {
   return apply_vector_unary<T>::apply(
-      y, [](auto&& v) { return simplex_column_free(v); });
+      y, [](auto&& v) { return stochastic_column_free(v); });
 }
 
 }  // namespace math
diff --git a/stan/math/prim/fun/stochastic_row_constrain.hpp b/stan/math/prim/fun/stochastic_row_constrain.hpp
@@ -1,5 +1,5 @@
-#ifndef STAN_MATH_PRIM_FUN_SIMPLEX_ROW_CONSTRAIN_HPP
-#define STAN_MATH_PRIM_FUN_SIMPLEX_ROW_CONSTRAIN_HPP
+#ifndef STAN_MATH_PRIM_FUN_STOCHASTIC_ROW_CONSTRAIN_HPP
+#define STAN_MATH_PRIM_FUN_STOCHASTIC_ROW_CONSTRAIN_HPP
 
 #include <stan/math/prim/meta.hpp>
 #include <stan/math/prim/fun/Eigen.hpp>
@@ -14,10 +14,7 @@ namespace stan {
 namespace math {
 
 /**
- * Return the simplex corresponding to the specified free vector.
- * A simplex is a vector containing values greater than or equal
- * to 0 that sum to 1.  A vector with (K-1) unconstrained values
- * will produce a simplex of size K.
+ * Return a row stochastic matrix.
  *
  * The transform is based on a centered stick-breaking process.
  *
@@ -27,7 +24,7 @@ namespace math {
  */
 template <typename Mat, require_eigen_matrix_dynamic_t<Mat>* = nullptr,
           require_not_st_var<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_row_constrain(const Mat& y) {
+inline plain_type_t<Mat> stochastic_row_constrain(const Mat& y) {
   auto&& y_ref = to_ref(y);
   const Eigen::Index N = y_ref.rows();
   int Km1 = y_ref.cols();
@@ -44,10 +41,7 @@ inline plain_type_t<Mat> simplex_row_constrain(const Mat& y) {
 }
 
 /**
- * Return a matrix with simplex rows corresponding to the specified free matrix
- * and increment the specified log probability reference with
- * the log absolute Jacobian determinant of the transform.
- *
+ * Return a row stochastic matrix.
  * The simplex transform is defined through a centered
  * stick-breaking process.
  *
@@ -58,7 +52,7 @@ inline plain_type_t<Mat> simplex_row_constrain(const Mat& y) {
  */
 template <typename Mat, require_eigen_matrix_dynamic_t<Mat>* = nullptr,
           require_not_st_var<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_row_constrain(const Mat& y,
+inline plain_type_t<Mat> stochastic_row_constrain(const Mat& y,
                                                value_type_t<Mat>& lp) {
   auto&& y_ref = to_ref(y);
   const Eigen::Index N = y_ref.rows();
@@ -80,7 +74,7 @@ inline plain_type_t<Mat> simplex_row_constrain(const Mat& y,
 }
 
 /**
- * Return a matrix with simplex rows corresponding to the specified free matrix.
+ * Return a row stochastic matrix.
  * If the `Jacobian` parameter is `true`, the log density accumulator is
  * incremented with the log absolute Jacobian determinant of the transform.  All
  * of the transforms are specified with their Jacobians in the *Stan Reference
@@ -96,18 +90,18 @@ inline plain_type_t<Mat> simplex_row_constrain(const Mat& y,
  * @return Matrix with simplexes along the rows of dimensionality (N, K).
  */
 template <bool Jacobian, typename Mat, require_not_std_vector_t<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_row_constrain(const Mat& y,
+inline plain_type_t<Mat> stochastic_row_constrain(const Mat& y,
                                                return_type_t<Mat>& lp) {
   if (Jacobian) {
-    return simplex_row_constrain(y, lp);
+    return stochastic_row_constrain(y, lp);
   } else {
-    return simplex_row_constrain(y);
+    return stochastic_row_constrain(y);
   }
 }
 
 /**
- * Return the simplex corresponding to the specified free vector. If the
- * `Jacobian` parameter is `true`, the log density accumulator is incremented
+ * Return a row stochastic matrix. 
+ * If the `Jacobian` parameter is `true`, the log density accumulator is incremented
  * with the log absolute Jacobian determinant of the transform.  All of the
  * transforms are specified with their Jacobians in the *Stan Reference Manual*
  * chapter Constraint Transforms.
@@ -122,9 +116,9 @@ inline plain_type_t<Mat> simplex_row_constrain(const Mat& y,
  * @return vector of matrices with simplex rows of dimensionality (N, K)
  */
 template <bool Jacobian, typename T, require_std_vector_t<T>* = nullptr>
-inline auto simplex_row_constrain(const T& y, return_type_t<T>& lp) {
+inline auto stochastic_row_constrain(const T& y, return_type_t<T>& lp) {
   return apply_vector_unary<T>::apply(
-      y, [&lp](auto&& v) { return simplex_row_constrain<Jacobian>(v, lp); });
+      y, [&lp](auto&& v) { return stochastic_row_constrain<Jacobian>(v, lp); });
 }
 
 }  // namespace math
diff --git a/stan/math/prim/fun/stochastic_row_free.hpp b/stan/math/prim/fun/stochastic_row_free.hpp
@@ -1,5 +1,5 @@
-#ifndef STAN_MATH_PRIM_FUN_SIMPLEX_ROW_FREE_HPP
-#define STAN_MATH_PRIM_FUN_SIMPLEX_ROW_FREE_HPP
+#ifndef STAN_MATH_PRIM_FUN_STOCHASTIC_ROW_FREE_HPP
+#define STAN_MATH_PRIM_FUN_STOCHASTIC_ROW_FREE_HPP
 
 #include <stan/math/prim/meta.hpp>
 #include <stan/math/prim/fun/Eigen.hpp>
@@ -18,7 +18,7 @@ namespace math {
  */
 template <typename Mat, require_eigen_matrix_dynamic_t<Mat>* = nullptr,
           require_not_st_var<Mat>* = nullptr>
-inline plain_type_t<Mat> simplex_row_free(const Mat& y) {
+inline plain_type_t<Mat> stochastic_row_free(const Mat& y) {
   auto&& y_ref = to_ref(y);
   const Eigen::Index N = y_ref.rows();
   plain_type_t<Mat> ret(N, y_ref.cols() - 1);
@@ -36,9 +36,9 @@ inline plain_type_t<Mat> simplex_row_free(const Mat& y) {
  * @param[in] y vector of rowwise simplex matrices each of size (N, K)
  */
 template <typename T, require_std_vector_t<T>* = nullptr>
-inline auto simplex_row_free(const T& y) {
+inline auto stochastic_row_free(const T& y) {
   return apply_vector_unary<T>::apply(
-      y, [](auto&& v) { return simplex_row_free(v); });
+      y, [](auto&& v) { return stochastic_row_free(v); });
 }
 
 }  // namespace math
diff --git a/stan/math/rev/fun.hpp b/stan/math/rev/fun.hpp
@@ -160,11 +160,11 @@
 #include <stan/math/rev/fun/rows_dot_product.hpp>
 #include <stan/math/rev/fun/rows_dot_self.hpp>
 #include <stan/math/rev/fun/sd.hpp>
-#include <stan/math/rev/fun/simplex_column_constrain.hpp>
 #include <stan/math/rev/fun/simplex_constrain.hpp>
-#include <stan/math/rev/fun/simplex_row_constrain.hpp>
 #include <stan/math/rev/fun/sin.hpp>
 #include <stan/math/rev/fun/singular_values.hpp>
+#include <stan/math/rev/fun/stochastic_column_constrain.hpp>
+#include <stan/math/rev/fun/stochastic_row_constrain.hpp>
 #include <stan/math/rev/fun/svd.hpp>
 #include <stan/math/rev/fun/svd_U.hpp>
 #include <stan/math/rev/fun/svd_V.hpp>
diff --git a/stan/math/rev/fun/stochastic_column_constrain.hpp b/stan/math/rev/fun/stochastic_column_constrain.hpp
@@ -1,5 +1,5 @@
-#ifndef STAN_MATH_REV_FUN_SIMPLEX_COLUMN_CONSTRAIN_HPP
-#define STAN_MATH_REV_FUN_SIMPLEX_COLUMN_CONSTRAIN_HPP
+#ifndef STAN_MATH_REV_FUN_STOCHASTIC_COLUMN_CONSTRAIN_HPP
+#define STAN_MATH_REV_FUN_STOCHASTIC_COLUMN_CONSTRAIN_HPP
 
 #include <stan/math/rev/meta.hpp>
 #include <stan/math/rev/core/reverse_pass_callback.hpp>
@@ -16,19 +16,15 @@ namespace stan {
 namespace math {
 
 /**
- * Return a matrix with columns as simplex vectors.
- * A simplex is a vector containing values greater than or equal
- * to 0 that sum to 1.  A matrix (K-1, M) unconstrained values
- * will produce a matrix of simplex vectors of size (K, M).
- *
+ * Return a column stochastic matrix.
  * The transform is based on a centered stick-breaking process.
  *
  * @tparam T Type of matrix to constrain
  * @param y Free matrix input of dimensionality (K - 1, M)
  * @return matrix of column simplexes of dimensionality (K, M)
  */
 template <typename T, require_rev_matrix_t<T>* = nullptr>
-inline plain_type_t<T> simplex_column_constrain(const T& y) {
+inline plain_type_t<T> stochastic_column_constrain(const T& y) {
   using ret_type = plain_type_t<T>;
   const Eigen::Index N = y.rows();
   const Eigen::Index M = y.cols();
@@ -71,7 +67,7 @@ inline plain_type_t<T> simplex_column_constrain(const T& y) {
 }
 
 /**
- * Return a matrix with columns as simplex vectors
+ * Return a column stochastic matrix
  * and increment the specified log probability reference with
  * the log absolute Jacobian determinant of the transform.
  *
@@ -81,10 +77,10 @@ inline plain_type_t<T> simplex_column_constrain(const T& y) {
  * @tparam T type of the matrix to constrain
  * @param y Free matrix input of dimensionality N, K.
  * @param lp Log probability reference to increment.
- * @return Matrix of simplex columns of dimensionality (N + 1, K).
+ * @return Matrix of stochastic columns of dimensionality (N + 1, K).
  */
 template <typename T, require_rev_matrix_t<T>* = nullptr>
-inline plain_type_t<T> simplex_column_constrain(const T& y,
+inline plain_type_t<T> stochastic_column_constrain(const T& y,
                                                 scalar_type_t<T>& lp) {
   using ret_type = plain_type_t<T>;
   const Eigen::Index N = y.rows();
diff --git a/stan/math/rev/fun/stochastic_row_constrain.hpp b/stan/math/rev/fun/stochastic_row_constrain.hpp
@@ -1,5 +1,5 @@
-#ifndef STAN_MATH_REV_FUN_SIMPLEX_ROW_CONSTRAIN_HPP
-#define STAN_MATH_REV_FUN_SIMPLEX_ROW_CONSTRAIN_HPP
+#ifndef STAN_MATH_REV_FUN_STOCHASTIC_ROW_CONSTRAIN_HPP
+#define STAN_MATH_REV_FUN_STOCHASTIC_ROW_CONSTRAIN_HPP
 
 #include <stan/math/rev/meta.hpp>
 #include <stan/math/rev/core/reverse_pass_callback.hpp>
@@ -16,19 +16,14 @@ namespace stan {
 namespace math {
 
 /**
- * Return a matrix of simplex columns corresponding to the specified free
- * matrix. A simplex is a vector containing values greater than or equal to 0
- * that sum to 1.  A matrix with (N, K - 1) unconstrained values will produce a
- * matrix with simplexes on the rows of size (N, K).
- *
- * The transform is based on a centered stick-breaking process.
+ * Return a row stochastic matrix.
  *
  * @tparam T Type of matrix to constrain
  * @param y Free vector input of dimensionality (N, K - 1)
  * @return Matrix with Simplexes along the rows of dimensionality (N, K)
  */
 template <typename T, require_rev_matrix_t<T>* = nullptr>
-inline plain_type_t<T> simplex_row_constrain(const T& y) {
+inline plain_type_t<T> stochastic_row_constrain(const T& y) {
   using ret_type = plain_type_t<T>;
   const Eigen::Index N = y.rows();
   const Eigen::Index M = y.cols();
@@ -68,7 +63,7 @@ inline plain_type_t<T> simplex_row_constrain(const T& y) {
 }
 
 /**
- * Return a matrix of simplex columns corresponding to the specified free matrix
+ * Return a row stochastic matrix
  * and increment the specified log probability reference with
  * the log absolute Jacobian determinant of the transform.
  *
@@ -81,7 +76,7 @@ inline plain_type_t<T> simplex_row_constrain(const T& y) {
  * @return Matrix with simplexes along the rows of dimensionality (N, K + 1).
  */
 template <typename T, require_rev_matrix_t<T>* = nullptr>
-inline plain_type_t<T> simplex_row_constrain(const T& y, scalar_type_t<T>& lp) {
+inline plain_type_t<T> stochastic_row_constrain(const T& y, scalar_type_t<T>& lp) {
   using ret_type = plain_type_t<T>;
   const Eigen::Index N = y.rows();
   const Eigen::Index M = y.cols();
diff --git a/test/unit/math/mix/fun/stochastic_column_constrain_test.cpp b/test/unit/math/mix/fun/stochastic_column_constrain_test.cpp
diff --git a/test/unit/math/mix/fun/stochastic_row_constrain_test.cpp b/test/unit/math/mix/fun/stochastic_row_constrain_test.cpp
diff --git a/test/unit/math/prim/fun/stochastic_column_constrain_test.cpp b/test/unit/math/prim/fun/stochastic_column_constrain_test.cpp
diff --git a/test/unit/math/prim/fun/stochastic_row_constrain_test.cpp b/test/unit/math/prim/fun/stochastic_row_constrain_test.cpp
