Update docs and tests for Stan 2.32 syntax changes

[riddell-stan]

Address this kind of warning:

Declaration of arrays by placing brackets after a variable name is deprecated and
    will be removed in Stan 2.32.0. Instead use the array keyword before the
    type. This can be changed automatically using the auto-format flag to
    stanc

Documentation and tests must be updated.

[knappa]

I just ran into this as well, while trying to get started with stan/pystan using the documentation at https://pystan.readthedocs.io/en/latest/ This is what is there now:

import stan

schools_code = """
data {
  int<lower=0> J;         // number of schools
  real y[J];              // estimated treatment effects
  real<lower=0> sigma[J]; // standard error of effect estimates
}
parameters {
  real mu;                // population treatment effect
  real<lower=0> tau;      // standard deviation in treatment effects
  vector[J] eta;          // unscaled deviation from mu by school
}
transformed parameters {
  vector[J] theta = mu + tau * eta;        // school treatment effects
}
model {
  target += normal_lpdf(eta | 0, 1);       // prior log-density
  target += normal_lpdf(y | theta, sigma); // log-likelihood
}
"""

schools_data = {"J": 8,
                "y": [28,  8, -3,  7, -1,  1, 18, 12],
                "sigma": [15, 10, 16, 11,  9, 11, 10, 18]}

posterior = stan.build(schools_code, data=schools_data)
fit = posterior.sample(num_chains=4, num_samples=1000)
eta = fit["eta"]  # array with shape (8, 4000)
df = fit.to_frame()  # pandas `DataFrame, requires pandas

Running the above, we get the following messages from the stan.build function:

Messages from stanc:
Warning in '/tmp/httpstan_yl4pxs0i/model_zzhabz4t.stan', line 4, column 2: Declaration
    of arrays by placing brackets after a variable name is deprecated and
    will be removed in Stan 2.32.0. Instead use the array keyword before the
    type. This can be changed automatically using the auto-format flag to
    stanc
Warning in '/tmp/httpstan_yl4pxs0i/model_zzhabz4t.stan', line 5, column 2: Declaration
    of arrays by placing brackets after a variable name is deprecated and
    will be removed in Stan 2.32.0. Instead use the array keyword before the
    type. This can be changed automatically using the auto-format flag to
    stanc
Warning: The parameter tau has no priors. This means either no prior is
    provided, or the prior(s) depend on data variables. In the later case,
    this may be a false positive.
Warning: The parameter mu has no priors. This means either no prior is
    provided, or the prior(s) depend on data variables. In the later case,
    this may be a false positive.

Then posterior.sample fails with:

---------------------------------------------------------------------------
RuntimeError                              Traceback (most recent call last)
Cell In [3], line 1
----> 1 fit = posterior.sample(num_chains=4, num_samples=1000)

File ~/.local/lib/python3.10/site-packages/stan/model.py:89, in Model.sample(self, num_chains, **kwargs)
     61 def sample(self, *, num_chains=4, **kwargs) -> stan.fit.Fit:
     62     """Draw samples from the model.
     63 
     64     Parameters in ``kwargs`` will be passed to the default sample function.
   (...)
     87 
     88     """
---> 89     return self.hmc_nuts_diag_e_adapt(num_chains=num_chains, **kwargs)

File ~/.local/lib/python3.10/site-packages/stan/model.py:108, in Model.hmc_nuts_diag_e_adapt(self, num_chains, **kwargs)
     92 """Draw samples from the model using ``stan::services::sample::hmc_nuts_diag_e_adapt``.
     93 
     94 Parameters in ``kwargs`` will be passed to the (Python wrapper of)
   (...)
    105 
    106 """
    107 function = "stan::services::sample::hmc_nuts_diag_e_adapt"
--> 108 return self._create_fit(function=function, num_chains=num_chains, **kwargs)

File ~/.local/lib/python3.10/site-packages/stan/model.py:312, in Model._create_fit(self, function, num_chains, **kwargs)
    309     return fit
    311 try:
--> 312     return asyncio.run(go())
    313 except KeyboardInterrupt:
    314     return

File /usr/local/lib/python3.10/asyncio/runners.py:44, in run(main, debug)
     42     if debug is not None:
     43         loop.set_debug(debug)
---> 44     return loop.run_until_complete(main)
     45 finally:
     46     try:

File /usr/local/lib/python3.10/asyncio/base_events.py:646, in BaseEventLoop.run_until_complete(self, future)
    643 if not future.done():
    644     raise RuntimeError('Event loop stopped before Future completed.')
--> 646 return future.result()

File ~/.local/lib/python3.10/site-packages/stan/model.py:236, in Model._create_fit.<locals>.go()
    234         sampling_output.write_line("<info>Sampling:</info> <error>Initialization failed.</error>")
    235         raise RuntimeError("Initialization failed.")
--> 236     raise RuntimeError(message)
    238 resp = await client.get(f"/{fit_name}")
    239 if resp.status != 200:

RuntimeError: Exception during call to services function: `BrokenProcessPool('A child process terminated abruptly, the process pool is not usable anymore')`, traceback: `['  File "/home/knappa/.local/lib/python3.10/site-packages/httpstan/services_stub.py", line 112, in call\n    future = asyncio.get_running_loop().run_in_executor(executor, lazy_function_wrapper_partial)  # type: ignore\n', '  File "/usr/local/lib/python3.10/asyncio/base_events.py", line 818, in run_in_executor\n    executor.submit(func, *args), loop=self)\n', '  File "/usr/local/lib/python3.10/concurrent/futures/process.py", line 715, in submit\n    raise BrokenProcessPool(self._broken)\n']`

This is on a debian box, running pystan 3.5.0, installed through pip.

[riddell-stan]

This looks like a different issue. Warnings should not stop sample from succeeding. Can you create a new issue? You shouldn't be encountering problems on Debian 11.

[riddell-stan]

For the issue proper, this is what CmdStanPy uses:

data {
  int<lower=0> J; // number of schools
  array[J] real y; // estimated treatment effect (school j)
  array[J] real<lower=0> sigma; // std err of effect estimate (school j)
}
parameters {
  real mu;
  array[J] real theta;
  real<lower=0> tau;
}
model {
  theta ~ normal(mu, tau);
  y ~ normal(theta, sigma);
}