Merge pull request #862 from stan-dev/sig-figs-changes

Update docs for new sig_figs default in CmdStan

Author: bob-carpenter

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.
 

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

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
 ```

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)

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)

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.

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.

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)

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}