arvinds-ds/stanmagic

Stan Jupyter Magic

stanmagic

An %%stan magic extension for Jupyter Notebook that helps to author/run Stan code within your notebook interactive session. After iterating with your model code and post succesful compile, an object is returned in your namespace [_stan_model or an <object_name> specified in -v option] that can be used to pass the file/code further to pystan for model execution.

The model_object has rich formatted html output with syntax highlighting for stan code (via Stan pygments lexer). See below for example

For code

Installation

Install stanmagic using pip

$ pip install git+https://github.com/Arvinds-ds/stanmagic.git

Optional - Specifying compiler path [else defaults to pystan.stanc]

Ensure you have the STAN compiler (stanc) installed on your platform. Instructions can be found at https://github.com/stan-dev/cmdstan

Ensure that stanc is in your path or you can pass the compiler path manually via the -- stanc <compiler path>

Usage

See sample notebook https://github.com/Arvinds-ds/stanmagic/blob/master/StanMagic-Help.ipynb for usage details

%%stan [-v <object_name>]

Saves the cell code to a string. The code string can be accessed via _stan_model.model_code or <object_name>.model_code (if you specified [-v <object_name>] option)

%%stan -f <stan_file_name> [-v <object_name>]

Saves the cell code to a file specified in <stan_file_name>. The file name can be accessed via _stan_model.model_file or via <object_name>.model_file (if you specified [-v <object_name>] option)

%%stan -f <stan_file_name> --save_only Saves the cell code to a file specified in <stan_file_name>. Skips the compile step

%%stan -f <stan_file_name> -o <cpp_file_name>

Saves the cell code to a file specified in <stan_file_name> and outputs the compiled cpp file to the file name specified by <cpp_file_name>

%% stan -f <stan_file_name> --allow_undefined

passes the --allow_undefined argument to stanc compiler (not valid for pystan.stanc)

%%stan -f <stan_file_name> --stanc <stanc_compiler>

Saves the cell code to a file specified in <stan_file_name> and compiles using the stan compiler specified in <stanc_compiler>. By default, it uses stanc compiler in your path. If your path does not have the stanc compiler, use this option (e.g %%stan binom.stan --stanc "~/cmdstan-2.16.0/bin/stanc") or to specifically use pystan use %%stan -f binom.stan --stanc pystan

Note: %%stan magic currently outputs a StanMagicOutput object as default _stan_model object in your name_space

The -v option allows you to specify an alternate compile output object name, so that you can use specified object name instead of _stan_model.

This is useful if you have multiple %%stan model cells. Currently the output object exposes 3 attributes (model_name, model_code, model_file)

[_stan_model | <object_name>].model_file -> Name of stan_file

[_stan_model | <object_name>].model_name -> Name of stan model [None]

[_stan_model | <object_name>].model_code -> Model code

Example

Example 1

In [1]: %load_ext stanmagic

In [2]: %%stan -f eight_schools.stan
        data {
            int<lower=0> J; // number of schools
            real y[J]; // estimated treatment effects
            real<lower=0> sigma[J]; // s.e. of effect estimates
          }
          parameters {
            real mu;
            real<lower=0> tau
            real eta[J];
          }
          transformed parameters {
            real theta[J];
            for (j in 1:J)
            theta[j] = mu + tau * eta[j];
          }
          model {
            target += normal_lpdf(eta | 0, 1);
            target += normal_lpdf(y | theta, sigma);
          }

In [3]: model = pystan.StanModel(file='eight_schools.stan')

Example 2

    In [1]: %load_ext stanmagic

    In [2]: %%stan -f eight_schools.stan
            data {
                int<lower=0> J; // number of schools
                real y[J]; // estimated treatment effects
                real<lower=0> sigma[J]; // s.e. of effect estimates
              }
              parameters {
                real mu;
                real<lower=0> tau;
                real eta[J];
              }
              transformed parameters {
                real theta[J];
                for (j in 1:J)
                theta[j] = mu + tau * eta[j];
              }
              model {
                target += normal_lpdf(eta | 0, 1);
                target += normal_lpdf(y | theta, sigma);
              }

In [3]: _stan_model

   In [4]: model = pystan.StanModel(file=_stan_model.model_file)

Example 3

    In [1]: %load_ext stanmagic

    In [2]: %%stan  -v model_test
            data {
                int<lower=0> J; // number of schools
                real y[J]; // estimated treatment effects
                real<lower=0> sigma[J]; // s.e. of effect estimates
              }
              parameters {
                real mu;
                real<lower=0> tau;
                real eta[J];
              }
              transformed parameters {
                real theta[J];
                for (j in 1:J)
                theta[j] = mu + tau * eta[j];
              }
              model {
                target += normal_lpdf(eta | 0, 1);
                target += normal_lpdf(y | theta, sigma);
              }




   In [3]: model = pystan.StanModel(model_code=model_test.model_code)

Example 4

    In [1]: %load_ext stanmagic

    In [2]: %%stan 
            data {
                int<lower=0> J; // number of schools
                real y[J]; // estimated treatment effects
                real<lower=0> sigma[J]; // s.e. of effect estimates
              }
              parameters {
                real mu;
                real<lower=0> tau;
                real eta[J];
              }
              transformed parameters {
                real theta[J];
                for (j in 1:J)
                theta[j] = mu + tau * eta[j];
              }
              model {
                target += normal_lpdf(eta | 0, 1);
                target += normal_lpdf(y | theta, sigma);
              }




   In [3]: model = pystan.StanModel(model_code=_stan_model.model_code)

License

stan-jupyter-magic is licensed under the MIT license. See the license file for details.

stanmagic's Issues

Use pystan.stanc

If installed, it could use pystan.stanc function?

I don't always have CmdStan installed even if I have pystan.

Set variable option

If possible, there should be an option to put cell contents to variable.

e.g. -v

%%stan -v model_code
....

Does this work? setattr(model_code, cell)

Support latest PyStan3 and CmdStanPy

The latest version of PyStan uses a somewhat different syntax and overall model than previous and so stanmagic doesn't work with it directly, and because of the new model -- which requires data at compilation time -- it needs more than just a simple change of names. This is sufficiently non-obvious that I've posted a Pystan3 feature request to change this behaviour.

Also I understand that CmdStanPy is becoming a popular way to do much the same thing with a python front-end, albeit with a file-based interface to stan (but I haven't used it).

One simple fix might be to just allow the magic to create a string or file with no attempt at compilation (but with syntax highlighting!)

(I tried to post a something similar in the jupyterstan repo but issues are disabled there…)

(Apologies for the lack of links in the above; the original, prettier, version of this issue was unceremoniously deleted by a github iOS bug, and I don't have the strength to replace them all right now...)