This is an old version, view current version.

33.4 Automatic updating and formatting of Stan programs

In addition to compiling Stan programs, stanc3 features several flags which can be used to format Stan programs and update them to the most recent Stan syntax by removing any deprecation features which can be automatically replaced.

33.4.1 Automatic formatting

Invoking stanc --auto-format <model_file> will print a version of your model which has been re-formatted. The goal is to have this automatic formatting stay as close as possible to the Stan Program Style Guide. This means spacing, identation, and line length are all regularized. Some deprecated features, like the use of # for line comments, are replaced, but the goal is mainly to preserve the program while formatting it.

33.4.2 Canonicalizing

Invoking stanc --print-canonical <model_file> will also print a formatted version of your program, but it will first make several changes to the code to reflect changes in syntax and deprecations to the language. This can be a great tool for updating older Stan models and silencing deprecation warnings.

Some of the changes made are:

• Removing unnecessary extra parenthesis

  y = ((x-1)) \(\to\) y = x - 1

• Replacing deprecated assignment operators

  y <- 0 \(\to\) y = 0

• Updating the suffix of (included or user-defined) distributions

  my_distribution_cdf_log \(\to\) my_distribution_lcdf

• Replacing inline conditionals with the ternary if operator

  if_else(a,b,c) \(\to\) a ? b : c

• Replacing some deprecated functions with their drop-in replacements

  abs(2.4) \(\to\) fabs(2.4)

• Replacing increment_log_prob calls with target+= statements

33.4.3 Known issues

The formatting and canonicalizing features of stanc3 are still under development. The following are some known issues one should be aware of before using either:

• Oddly placed comments

  If your Stan program features comments in unexpected places, such as inside an expression, they may be moved in the process of formatting. Moved comments are prefixed with the string ^^^: to indicate they originally appeared higher in the program.

  For example, the following program

  generated quantities {
    real x = 2;
    real y = x /* comment */ - 1;
  }

  will be formatted as follows

  generated quantities {
    real x = 2;
    real y = x - 1;
  
    /* ^^^: comment */
  }

  One can avoid this by not placing comments directly inside an expression, and we hope to improve this functionality in future versions.