Merge branch 'master' of https://github.com/stan-dev/docs

mitzimorris · mitzimorris · commit 79b28e91c83e · 2025-03-21T17:50:21.000-04:00
diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ Repository for the sources and published documentation set, versioned for each S
     + `src/functions-reference` - Stan Functions Reference
     + `src/reference-manual` - Stan Reference Manual
     + `src/stan-users-guide` - Stan Users Guide
+    + `src/quarto-config` - A submodule of the [stan-dev/quarto-config](https://github.com/stan-dev/quarto-config) repository for shared files between the docs and Stan website
 
 * `docs`: the directory `docs` on branch `master` is the [publishing source](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) for the project pages site.  Whenever a verified member of the Stan organization pushes to `docs` on branch `master`,
 GitHub (re)builds and (re)deploys the website.
@@ -34,15 +35,19 @@ the repository [quarto-config](https://github.com/stan-dev/quarto-config).
 
 ## Scripts to build and maintain the docset
 
-### Check out submodule `quarto-config` into the `src` subdirectory
+**Checking out the repository**
 
-To build the docs locally,  you must first clone the quarto-config repo into the `src` subdirectory.
+In order to ensure the `quarto-config` folder is present, when cloning the repository, use the `--recursive` flag
 
-```sh
-cd src
-git clone https://github.com/stan-dev/quarto-config
+```shell
+git clone --recursive https://github.com/stan-dev/docs.git
 ```
 
+If you already have a clone without this submodule, or if it falls out of date, you can run
+```shell
+git submodule update --init --recursive
+```
+To initialize or refresh it.
 
 **`build.py`**
 
diff --git a/src/cmdstan-guide/command_line_options.qmd b/src/cmdstan-guide/command_line_options.qmd
@@ -79,7 +79,7 @@ The keyword value pair `sig_figs=<int>` specifies the
 number of significant digits for all numerical values in the output files.
 Allowable values are between 1 and 18, which is the maximum amount of precision
 available for 64-bit floating point arithmetic.
-The default value is 6. &nbsp;
+The default value is 8. &nbsp;
 ***Note:*** increasing `sig_figs` above the default will increase the size of
 the output CSV files accordingly.
 
diff --git a/src/cmdstan-guide/laplace_sample_config.qmd b/src/cmdstan-guide/laplace_sample_config.qmd
@@ -93,11 +93,6 @@ In comparison, running the NUTS-HMC sampler results in mean 2.6 and standard dev
 The header and first few data rows of the output sample are shown below.
 
 ```
-# stan_version_major = 2
-# stan_version_minor = 35
-# stan_version_patch = 0
-# model = bernoulli_model
-# start_datetime = 2022-12-20 01:01:14 UTC
 # method = laplace
 #   laplace
 #     mode = bernoulli_lbfgs.csv
@@ -114,11 +109,9 @@ The header and first few data rows of the output sample are shown below.
 #   file = output.csv (Default)
 #   diagnostic_file =  (Default)
 #   refresh = 100 (Default)
-#   sig_figs = -1 (Default)
+#   sig_figs = 8 (Default)
 #   profile_file = profile.csv (Default)
 # num_threads = 1 (Default)
-# stanc_version = stanc3 v2.31.0-7-g20444266
-# stancflags =
 log_p__,log_q__,theta
 -9.4562,-2.33997,0.0498545
 -6.9144,-0.0117349,0.182898
diff --git a/src/cmdstan-guide/log_prob_config.qmd b/src/cmdstan-guide/log_prob_config.qmd
@@ -72,11 +72,6 @@ This yields
 
 
 ```
-# stan_version_major = 2
-# stan_version_minor = 31
-# stan_version_patch = 0
-# model = bernoulli_model
-# start_datetime = 2022-11-17 20:46:06 UTC
 # method = log_prob
 #   log_prob
 #     unconstrained_params =  (Default)
@@ -92,11 +87,9 @@ This yields
 #   file = output.csv (Default)
 #   diagnostic_file =  (Default)
 #   refresh = 100 (Default)
-#   sig_figs = -1 (Default)
+#   sig_figs = 8 (Default)
 #   profile_file = profile.csv (Default)
 # num_threads = 1 (Default)
-# stanc_version = stanc3 2.31.0 (Linux)
-# stancflags =
 lp_,theta
 -7.856,1.8
 ```
diff --git a/src/cmdstan-guide/optimize_config.qmd b/src/cmdstan-guide/optimize_config.qmd
@@ -58,7 +58,7 @@ output
   file = output.csv (Default)
   diagnostic_file =  (Default)
   refresh = 100 (Default)
-  sig_figs = -1 (Default)
+  sig_figs = 8 (Default)
   profile_file = profile.csv (Default)
   save_cmdstan_config = false (Default)
 num_threads = 1 (Default)
diff --git a/src/cmdstan-guide/pathfinder_config.qmd b/src/cmdstan-guide/pathfinder_config.qmd
@@ -62,7 +62,7 @@ output
   file = output.csv (Default)
   diagnostic_file =  (Default)
   refresh = 100 (Default)
-  sig_figs = -1 (Default)
+  sig_figs = 8 (Default)
   profile_file = profile.csv (Default)
   save_cmdstan_config = false (Default)
 num_threads = 1 (Default)
diff --git a/src/cmdstan-guide/stan_csv_apdx.qmd b/src/cmdstan-guide/stan_csv_apdx.qmd
@@ -14,8 +14,8 @@ however, possible values include both positive and negative
 infinity and "Not-a-Number" which are represented as
 the strings `NaN`, `inf`, `+inf`, `-inf`.
 All other values are written in decimal notation by default with
-at most 6 digits of precision. The number of significant digits 
-written can be controlled with argument `sig_figs=<int>`. See more 
+at most 8 digits of precision. The number of significant digits
+written can be controlled with argument `sig_figs=<int>`. See more
 in [Output control arguments section](command_line_options.qmd#output-control.section).
 
 Stan CSV files have a header row containing the column names.
diff --git a/src/cmdstan-guide/stansummary.qmd b/src/cmdstan-guide/stansummary.qmd
@@ -186,5 +186,5 @@ results in no percentiles being displayed in the output of the command.
 The amount of precision
 in the sampler output limits the amount of real precision in the summary report.
 CmdStan's command line interface also has output argument `sig_figs`.
-The default sampler output precision is 6.
+The default sampler output precision is 8.
 The `--sig_figs` argument to the stansummary program should not exceed the `sig_figs` argument to the sampler.
diff --git a/src/cmdstan-guide/variational_config.qmd b/src/cmdstan-guide/variational_config.qmd
@@ -66,7 +66,7 @@ output
   file = output.csv (Default)
   diagnostic_file =  (Default)
   refresh = 100 (Default)
-  sig_figs = -1 (Default)
+  sig_figs = 8 (Default)
   profile_file = profile.csv (Default)
   save_cmdstan_config = false (Default)
 num_threads = 1 (Default)
diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd
diff --git a/src/functions-reference/matrix_operations.qmd b/src/functions-reference/matrix_operations.qmd
@@ -746,10 +746,17 @@ A is symmetric and ensures that the result is also symmetric.
 The trace of the quadratic form, i.e., `trace(B' * A * B)`.
 {{< since 2.0 >}}
 
-<!-- real; trace_gen_quad_form; (matrix D,matrix A, matrix B); -->
-\index{{\tt \bfseries trace\_gen\_quad\_form }!{\tt (matrix D,matrix A, matrix B): real}|hyperpage}
+<!-- real; trace_quad_form; (matrix A, vector B); -->
+\index{{\tt \bfseries trace\_quad\_form }!{\tt (matrix A, vector B): real}|hyperpage}
 
-`real` **`trace_gen_quad_form`**`(matrix D,matrix A, matrix B)`<br>\newline
+`real` **`trace_quad_form`**`(matrix A, vector B)`<br>\newline
+The trace of the quadratic form, i.e., `trace(B' * A * B)`.
+{{< since 2.0 >}}
+
+<!-- real; trace_gen_quad_form; (matrix D ,matrix A, matrix B); -->
+\index{{\tt \bfseries trace\_gen\_quad\_form }!{\tt (matrix D, matrix A, matrix B): real}|hyperpage}
+
+`real` **`trace_gen_quad_form`**`(matrix D, matrix A, matrix B)`<br>\newline
 The trace of a generalized quadratic form, i.e., `trace(D * B' * A *
 B).`
 {{< since 2.0 >}}
diff --git a/src/quarto-config b/src/quarto-config
@@ -1 +1 @@
-Subproject commit ba78aa0e61a7fb47970171a005e61d91b48b8a3b
+Subproject commit 12e4c0771ba11de259bf9298dc9f56fc9dc3e0f0
diff --git a/src/reference-manual/transforms.qmd b/src/reference-manual/transforms.qmd
@@ -28,30 +28,27 @@ apply the appropriate Jacobians.
 ## Limitations due to finite accuracy presentation
 
 In this section the transformations are described mathematically.
-There are two cases where the observed behavior can be different from
-the exact arithmetic:
-  - Stan’s arithmetic is implemented using double-precision
-    floating-point arithmetic, which may cause computation to behave
-    differently than mathematics. For example, lower bound constraint
-    is defined with logarithm constraint which mathematically excludes
-    the lower bound, but if the closest floating-point number for the
-    inverse transformed value is the boundary, then the value is
-    rounded to the boundary. This may cause unexpected warnings or
-    errors, if in other parts of the code the boundary value is
-    invalid. For example, we may observe floating-point value 0 for
-    a variance parameter that has been declared to be larger than 0.
-	See more about [Floating point Arithmetic in Stan user's guide](../stan-users-guide/floating-point.qmd)).
-  - CmdStan stores the output to CSV files with 6 significant digits
-    accuracy by default, but the constraints are checked with 8
-    decimal digit accuracy. Due to this, there can be errors if CSV
-    output is further used, for example, to run generated
-    quantities. For example, simplex constraint requires the values to
-    sum up to 1, but when writing the values to CSV they are rounded
-    to 6 significant digits and the sum of those rounded values can be
-    smaller or larger than 1 by more than 8 decimal digits. The
-    solution for CmdStan is to increase the number of significant
-    digits stored as discussed in [CmdStan Command-Line Interface
-    Overview](../cmdstan-guide/command_line_options.qmd).
+However, observed behavior can be different from the exact arithmetic.
+
+Stan’s arithmetic is implemented using double-precision
+floating-point numbers, which may cause computation to behave
+differently than mathematics. For example, the lower bound constraint
+is defined above by an exponential inverse transform which mathematically excludes
+the lower bound, but if the closest floating-point number for the
+inverse transformed value is the boundary, then the value is
+rounded to the boundary. This may cause unexpected warnings or
+errors, if in other parts of the code the boundary value is
+invalid. For example, we may observe floating-point value 0 for
+a variance parameter that has been declared with `lower=0`.
+In general, double-precision floating-point numbers cannot reliably store
+more than 16 digits of a number in decimal.
+See more about [floating point arithmetic](../stan-users-guide/floating-point.qmd)
+in the *Stan User's Guide*.
+
+These issues are exacerbated by the fact that CmdStan stores the output to
+CSV files with 8 digits precision by default. More digits can be requested by the user
+at the cost of additional disk usage, as discussed in the
+[CmdStan Command-Line Interface Overview](../cmdstan-guide/command_line_options.qmd).
 
 ## Changes of variables {#change-of-variables.section}
 
diff --git a/src/stan-users-guide/gaussian-processes.qmd b/src/stan-users-guide/gaussian-processes.qmd
@@ -547,33 +547,11 @@ of $x_1$ is higher [@RasmussenWilliams:2006, page 80].
 The collection of $\rho_d$ (or $1/\rho_d$) parameters can also be
 modeled hierarchically.
 
-The implementation of automatic relevance determination in Stan is
-straightforward, though it currently requires the user to directly code the
-covariance matrix. We'll write a function to generate the Cholesky of the
-covariance matrix called `L_gp_exp_quad_cov_ARD`.
+The implementation of automatic relevance determination is a straightforward
+extension of the one-dimensional case by modifying `rho` to be an array.
 
 
 ```stan
-functions {
-  matrix L_gp_exp_quad_cov_ARD(array[] vector x,
-                            real alpha,
-                            vector rho,
-                            real delta) {
-    int N = size(x);
-    matrix[N, N] K;
-    real sq_alpha = square(alpha);
-    for (i in 1:(N-1)) {
-      K[i, i] = sq_alpha + delta;
-      for (j in (i + 1):N) {
-        K[i, j] = sq_alpha
-                      * exp(-0.5 * dot_self((x[i] - x[j]) ./ rho));
-        K[j, i] = K[i, j];
-      }
-    }
-    K[N, N] = sq_alpha + delta;
-    return cholesky_decompose(K);
-  }
-}
 data {
   int<lower=1> N;
   int<lower=1> D;
@@ -584,15 +562,20 @@ transformed data {
   real delta = 1e-9;
 }
 parameters {
-  vector<lower=0>[D] rho;
+  array[D] real<lower=0> rho;
   real<lower=0> alpha;
   real<lower=0> sigma;
   vector[N] eta;
 }
 model {
   vector[N] f;
   {
-    matrix[N, N] L_K = L_gp_exp_quad_cov_ARD(x, alpha, rho, delta);
+    matrix[N, N] L_K;
+    matrix[N, N] K = gp_exp_quad_cov(x, alpha, rho);
+    for (n in 1:N) {
+      K[n, n] = K[n, n] + delta;
+    }
+    L_K = cholesky_decompose(K);
     f = L_K * eta;
   }
 
diff --git a/src/stan-users-guide/problematic-posteriors.qmd b/src/stan-users-guide/problematic-posteriors.qmd
@@ -188,7 +188,7 @@ interpretable relative to student 1's ability to answer them.
 
 This solution is not sufficient to deal with the multiplicative
 invariance introduced by the question discrimination parameters
-$\delta_i$.  To solve this problem, one of the difficulty parameters,
+$\delta_i$.  To solve this problem, one of the discrimination parameters,
 say $\delta_1$, must also be constrained.  Because it's a
 multiplicative and not an additive invariance, it must be constrained
 to a non-zero value, with 1 being a convenient choice.  Now all of the
