{"id":19762746,"url":"https://github.com/stan-dev/mathematicastan","last_synced_at":"2026-02-05T12:33:26.297Z","repository":{"id":66088065,"uuid":"66637604","full_name":"stan-dev/MathematicaStan","owner":"stan-dev","description":"A Mathematica package to interact with CmdStan","archived":false,"fork":false,"pushed_at":"2024-08-15T11:48:10.000Z","size":1387,"stargazers_count":27,"open_issues_count":1,"forks_count":8,"subscribers_count":29,"default_branch":"master","last_synced_at":"2024-10-29T14:21:57.070Z","etag":null,"topics":["interface","mathematica","stan"],"latest_commit_sha":null,"homepage":null,"language":"Mathematica","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stan-dev.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"stan-dev","custom":"https://mc-stan.org/support/"}},"created_at":"2016-08-26T09:59:09.000Z","updated_at":"2024-08-13T12:12:33.000Z","dependencies_parsed_at":"2024-04-12T09:32:25.826Z","dependency_job_id":"727223d0-1ed1-4536-ab11-309a31af43c0","html_url":"https://github.com/stan-dev/MathematicaStan","commit_stats":{"total_commits":84,"total_committers":4,"mean_commits":21.0,"dds":"0.26190476190476186","last_synced_commit":"eb8bcea6dfc283b459f1c4d938433fbe3393c09f"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stan-dev%2FMathematicaStan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stan-dev%2FMathematicaStan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stan-dev%2FMathematicaStan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stan-dev%2FMathematicaStan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stan-dev","download_url":"https://codeload.github.com/stan-dev/MathematicaStan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241094678,"owners_count":19908683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interface","mathematica","stan"],"created_at":"2024-11-12T04:06:34.405Z","updated_at":"2026-02-05T12:33:26.256Z","avatar_url":"https://github.com/stan-dev.png","language":"Mathematica","funding_links":["https://github.com/sponsors/stan-dev","https://mc-stan.org/support/"],"categories":[],"sub_categories":[],"readme":"#+OPTIONS: toc:nil todo:nil pri:nil tags:nil ^:nil tex:t\n#+TITLE: MathematicaStan v2.2\n#+SUBTITLE: A Mathematica (v11+) package to interact with CmdStan\n#+AUTHOR: Picaud Vincent\n\n[[https://zenodo.org/doi/10.5281/zenodo.10810144][file:https://zenodo.org/badge/66637604.svg]]\n \n* Table of contents                                            :TOC_3:noexport:\n- [[#introduction][Introduction]]\n  - [[#news][News]]\n    - [[#2024-08-13][2024-08-13]]\n    - [[#2020-12-21][2020-12-21]]\n    - [[#2019-06-28][2019-06-28]]\n- [[#installation][Installation]]\n  - [[#the-stan-cmdstan-shell-interface][The Stan CmdStan shell interface]]\n  - [[#the-mathematica-cmdstan-package][The Mathematica CmdStan package]]\n  - [[#first-run][First run]]\n- [[#tutorial-1-linear-regression][Tutorial 1, linear regression]]\n  - [[#introduction-1][Introduction]]\n  - [[#stan-code][Stan code]]\n  - [[#code-compilation][Code compilation]]\n  - [[#simulated-data][Simulated data]]\n  - [[#create-the-datar-data-file][Create the =data.R= data file]]\n  - [[#run-stan-likelihood-maximization][Run Stan, likelihood maximization]]\n  - [[#load-the-csv-result-file][Load the CSV result file]]\n  - [[#run-stan-variational-bayes][Run Stan, Variational Bayes]]\n  - [[#more-about-option-management][More about Option management]]\n    - [[#overwriting-default-values][Overwriting default values]]\n    - [[#reading-customized-values][Reading customized values]]\n    - [[#erasing-customized-option-values][Erasing customized option values]]\n- [[#tutorial-2-linear-regression-with-more-than-one-predictor][Tutorial 2, linear regression with more than one predictor]]\n  - [[#parameter-arrays][Parameter arrays]]\n  - [[#simulated-data-1][Simulated data]]\n  - [[#exporting-data][Exporting data]]\n  - [[#run-stan-hmc-sampling][Run Stan, HMC sampling]]\n  - [[#load-the-csv-result-file-1][Load the CSV result file]]\n- [[#unit-tests][Unit tests]]\n\n* Introduction\n\n*MathematicaStan* is a package to interact with [[http://mc-stan.org/interfaces/cmdstan][CmdStan]] from\nMathematica. \n\nIt is developed under *Linux* and is compatible with *Mathematica v11+*\n\nIt should work under *MacOS* and also under *Windows*.\n\n*Author \u0026 contact:* picaud.vincent at gmail.com\n\n** News\n   \n*** 2024-08-13\n\n*New MathematicaStan version 2.2!*\n\n*Package test with last CmdStan v2.35.0, Mathematica 11.2, Linux*\n\n- Add some screenshots to the install procedure section\n  \n- CmdStan syntax changes have been included :\n  |----------------------------+-----------------------------------|\n  | old                        | current                           |\n  |----------------------------+-----------------------------------|\n  | \u003c-                         | =                                 |\n  | increment_log_prob(...)    | target += ...                     |\n  | int\u003clower=0,upper=1\u003e y[N]; | array[N] int\u003clower=0, upper=1\u003e y; |\n  |----------------------------+-----------------------------------|\n\n- Check that unit tests and examples work.\n\n*** 2020-12-21\n    \n*New MathematicaStan version 2.1!*\n\nThis version has been fixed and should now run under Windows.\n\nI would like to thank *Ali Ghaderi* who had the patience to help me to\ndebug the Windows version (I do not have access to this OS). Nothing\nwould have been possible without him. All possibly remaining bugs are\nmine.\n \nAs a remainder also note that one should not use path/filename with\nspaces (=Make= really does not like that). This consign is also true\nunder Linux or MacOS. See [[https://stackoverflow.com/questions/9838384/can-gnu-make-handle-filenames-with-spaces][SO:can-gnu-make-handle-filenames-with-spaces]]\nby example.\n\n*** 2019-06-28 \n\n*New MathematicaStan version 2.0!*\n\nThis version uses Mathematica v11 and has been completely refactored\n\n*Caveat:* breaking changes!\n\n*Note*: the \"old\" MathematicaStan version based on Mathematica v8.0 is now archived in\nthe [[https://github.com/stan-dev/MathematicaStan/tree/v1][v1 git branch]]. \n\n* Installation\n\n** The Stan CmdStan shell interface\n\nFirst you must install [[http://mc-stan.org/interfaces/cmdstan][CmdStan]]. Once this is done you get a directory containing stuff like:\n\n#+BEGIN_EXAMPLE\nbin  doc  examples  Jenkinsfile  LICENSE  make  makefile  README.md  runCmdStanTests.py  src  stan  test-all.sh\n#+END_EXAMPLE\n\nWith my configuration *CmdStan* is installed in:\n#+BEGIN_EXAMPLE\n~/ExternalSoftware/cmdstan-2.35.0\n#+END_EXAMPLE\n\nFor Windows users it is possibly something like:\n#+BEGIN_EXAMPLE\nC:\\\\Users\\\\USER_NAME\\\\Documents\\\\R\\\\cmdstan-?.??.?\n#+END_EXAMPLE\n\n** The Mathematica CmdStan package\n\nTo install the Mathematica CmdStan package:\n- open the =CmdStan.m= file with Mathematica.\n- install it using the Mathematica Notebook *File-\u003eInstall* menu.\n\nFill in the pop-up windows as follows:\n[[file:figures/install.png]]\n\n** First run\n\nThe first time the package is imported\n#+BEGIN_SRC mathematica :eval never\n\u003c\u003cCmdStan`\n#+END_SRC\nyou will get an error message:\n#+BEGIN_EXAMPLE\nCmdStan::cmdStanDirectoryNotDefined: CmdStan directory does not exist, use SetCmdStanDirectory[dir] to define it (with something like SetCmdStanDirectory[\"~/ExternalSoftware/cmdstan-2.35.0\"])\n#+END_EXAMPLE\n\nThis is normal as we must define the Stan StanCmd shell interface root directory. \n\nWith my configuration this is:\n#+BEGIN_SRC matheematica :eval never\nSetCmdStanDirectory[\"~/ExternalSoftware/cmdstan-2.35.0\"]\n#+END_SRC\n\nFor Windows user this is certainly something like:\n#+BEGIN_SRC matheematica :eval never\nSetCmdStanDirectory[\"C:\\\\Users\\\\USER_NAME\\\\Documents\\\\R\\\\cmdstan-?.??.?\"]\n#+END_SRC\n\n[[file:figures/Install_SetDir.png]]\n\n*Note:* this location is recorded in the =$CmdStanConfigurationFile= file\n and you will not have to redefine it every time you import the\n CmdStan package.\n\n\n* Tutorial 1, linear regression\n\n** Introduction\n\nYou can use the file =tutorial.wls= or manually follow the instruction\nbelow.\n\nImport the package as usual\n\n#+BEGIN_SRC mathematica :eval never\n\u003c\u003cCmdStan`\n#+END_SRC\n\nThis package defines these functions (and symbols):\n\n#+BEGIN_SRC mathematica :eval never\n?CmdStan`*\n#+END_SRC\n\n| CmdStan             | GetStanOption          | RemoveStanOption     | StanOptionExistsQ  | StanResultReducedKeys     |\n| CompileStanCode     | GetStanResult          | RunStan              | StanOptions        | StanResultReducedMetaKeys |\n| ExportStanCode      | GetStanResultMeta      | SampleDefaultOptions | StanResult         | StanVerbose               |\n| ExportStanData      | ImportStanResult       | SetCmdStanDirectory  | StanResultKeys     | VariationalDefaultOptions |\n| GetCmdStanDirectory | OptimizeDefaultOptions | SetStanOption        | StanResultMetaKeys | $CmdStanConfigurationFile |\n\nFor this tutorial we use a simple [[https://mc-stan.org/docs/2_19/stan-users-guide/linear-regression.html][linear regression]] example and we will work in a temporary location:\n\n#+BEGIN_SRC mathematica :eval never\nSetDirectory[$TemporaryDirectory]\n#+END_SRC\n#+BEGIN_EXAMPLE\n/tmp\n#+END_EXAMPLE\n\n** Stan code \n\nDefine the Stan code\n#+BEGIN_SRC mathematica :eval never\nstanCode = \"data\n  {\n    int\u003clower = 0\u003e N;\n    vector[N] x;\n    vector[N] y;\n  }\n  parameters\n  {\n    real alpha;\n    real beta;\n    real\u003clower = 0\u003e sigma;\n  }\n  model {\n    y ~normal(alpha + beta * x, sigma);\n  }\";\n#+END_SRC\n\nand export it\n\n#+BEGIN_SRC mathematica :eval never\nstanCodeFile = ExportStanCode[\"linear_regression.stan\", stanCode]\n#+END_SRC\n#+BEGIN_EXAMPLE\n/tmp/linear_regression.stan\n#+END_EXAMPLE\n\n** Code compilation\n\nStan code compilation is performed by \n #+BEGIN_SRC mathematica :eval never\nstanExeFile = CompileStanCode[stanCodeFile] (* Attention: this takes some time *)\n #+END_SRC\n\nWith my configuration I get\n #+BEGIN_EXAMPLE\nmake: Entering directory '/home/picaud/ExternalSoftware/cmdstan-2.35.0'\n\n--- Translating Stan model to C++ code ---\nbin/stanc  --o=/tmp/linear_regression.hpp /tmp/linear_regression.stan\nModel name=linear_regression_model\nInput file=/tmp/linear_regression.stan\nOutput file=/tmp/linear_regression.hpp\ng++ -std=c++1y -pthread -Wno-sign-compare     -O3 -I src -I stan/src -I stan/lib/stan_math/ -I stan/lib/stan_math/lib/eigen_3.3.3 -I stan/lib/stan_math/lib/boost_1.69.0 -I stan/lib/stan_math/lib/sundials_4.1.0/include    -DBOOST_RESULT_OF_USE_TR1 -DBOOST_NO_DECLTYPE -DBOOST_DISABLE_ASSERTS -DBOOST_PHOENIX_NO_VARIADIC_EXPRESSION     -c -MT /tmp/linear_regression.o -MT /tmp/linear_regression -include /tmp/linear_regression.hpp -include src/cmdstan/main.cpp -MM -E -MG -MP -MF /tmp/linear_regression.d /tmp/linear_regression.hpp\n\n--- Linking C++ model ---\ng++ -std=c++1y -pthread -Wno-sign-compare     -O3 -I src -I stan/src -I stan/lib/stan_math/ -I stan/lib/stan_math/lib/eigen_3.3.3 -I stan/lib/stan_math/lib/boost_1.69.0 -I stan/lib/stan_math/lib/sundials_4.1.0/include    -DBOOST_RESULT_OF_USE_TR1 -DBOOST_NO_DECLTYPE -DBOOST_DISABLE_ASSERTS -DBOOST_PHOENIX_NO_VARIADIC_EXPRESSION             -include /tmp/linear_regression.hpp src/cmdstan/main.cpp        stan/lib/stan_math/lib/sundials_4.1.0/lib/libsundials_nvecserial.a stan/lib/stan_math/lib/sundials_4.1.0/lib/libsundials_cvodes.a stan/lib/stan_math/lib/sundials_4.1.0/lib/libsundials_idas.a  -o /tmp/linear_regression\nmake: Leaving directory '/home/picaud/ExternalSoftware/cmdstan-2.35.0'\n #+END_EXAMPLE\n\n*Note:* if you do not want to have information printed you can use the =StanVerbose= option:\n\n #+BEGIN_SRC mathematica :eval never\nstanExeFile = CompileStanCode[stanCodeFile, StanVerbose -\u003e False]\n #+END_SRC\n\n** Simulated data\n\nLet's simulate some data:\n #+BEGIN_SRC mathematica :eval never\nσ = 3; α = 1; β = 2;\nn = 20;\nX = Range[n];\nY = α + β*X + RandomVariate[NormalDistribution[0, σ], n];\nShow[Plot[α + β*x, {x, Min[X], Max[X]}], \n     ListPlot[Transpose@{X, Y}, PlotStyle -\u003e Red]]\n #+END_SRC\n\n[[file:figures/linRegData.png][file:./figures/linRegData.png]]\n\n** Create the =data.R= data file \n\nThe data are stored in a =Association= and then exported thanks to the\n=ExportStanData= function.\n\n#+BEGIN_SRC mathematica :eval never\nstanData = \u003c|\"N\" -\u003e n, \"x\" -\u003e X, \"y\" -\u003e Y|\u003e;\nstanDataFile = ExportStanData[stanExeFile, stanData]\n#+END_SRC\n\n#+BEGIN_EXAMPLE\n/tmp/linear_regression.data.R\n#+END_EXAMPLE\n\n*Note:* this function returns the created file\nname =/tmp/linear_regression.data.R=. Its first argument, =stanExeFile=\nis simply the Stan executable file name with its path. The\n=ExportStanData[]= function modifies the file name extension and\nreplace it with \".data.R\", but you can use it with\nany file name:\n#+BEGIN_SRC mathematica :eval never\nExportStanData[\"my_custom_path/my_custom_filename.data.R\",stanData]\n#+END_SRC\n\n** Run Stan, likelihood maximization\n\nWe are now able to run the =stanExeFile= executable. \n\nLet's start by maximizing the likelihood\n#+BEGIN_SRC mathematica :eval never\nstanResultFile = RunStan[stanExeFile, OptimizeDefaultOptions]\n#+END_SRC\n\n#+BEGIN_EXAMPLE\nRunning: /tmp/linear_regression method=optimize data file=/tmp/linear_regression.data.R output file=/tmp/linear_regression.csv\n\nmethod = optimize\n  optimize\n    algorithm = lbfgs (Default)\n      lbfgs\n        init_alpha = 0.001 (Default)\n        tol_obj = 9.9999999999999998e-13 (Default)\n        tol_rel_obj = 10000 (Default)\n        tol_grad = 1e-08 (Default)\n        tol_rel_grad = 10000000 (Default)\n        tol_param = 1e-08 (Default)\n        history_size = 5 (Default)\n    iter = 2000 (Default)\n    save_iterations = 0 (Default)\nid = 0 (Default)\ndata\n  file = /tmp/linear_regression.data.R\ninit = 2 (Default)\nrandom\n  seed = 2775739062\noutput\n  file = /tmp/linear_regression.csv\n  diagnostic_file =  (Default)\n  refresh = 100 (Default)\n\nInitial log joint probability = -8459.75\n    Iter      log prob        ||dx||      ||grad||       alpha      alpha0  # evals  Notes \n      19      -32.5116    0.00318011    0.00121546      0.9563      0.9563       52   \nOptimization terminated normally: \n  Convergence detected: relative gradient magnitude is below tolerance\n#+END_EXAMPLE\n\nThe =stanResultFile= variable contains now the csv result file:\n#+BEGIN_EXAMPLE\n/tmp/linear_regression.csv\n#+END_EXAMPLE\n\n*Note:* again, if you do not want to have printed output, use the =StanVerbose-\u003eFalse= option.\n\n#+BEGIN_SRC mathematica :eval never\nstanResultFile = RunStan[stanExeFile, OptimizeDefaultOptions,StanVerbose-\u003eFalse]\n#+END_SRC\n\n*Note:* the method we use is defined by the second argument\n=OptimizeDefaultOptions.= If you want to use Variational Bayes or HMC\nsampling you must use\n\n#+BEGIN_SRC mathematica :eval never\nRunStan[stanExeFile, VariationalDefaultOptions]\n#+END_SRC\nor\n#+BEGIN_SRC mathematica :eval never\nRunStan[stanExeFile, SampleDefaultOptions]\n#+END_SRC\n\n*Note*: option management will be detailed later in this tutorial.\n\n** Load the CSV result file\n\nTo load CSV result file, do\n\n#+BEGIN_SRC mathematica :eval never\nstanResult = ImportStanResult[stanResultFile]\n#+END_SRC\n\nwhich prints\n#+BEGIN_EXAMPLE\n     file: /tmp/linear_regression.csv\n     meta: lp__ \nparameter: alpha , beta , sigma \n#+END_EXAMPLE\n\nTo access estimated variable α, β and σ, simply do:\n#+BEGIN_SRC mathematica :eval never\n\nGetStanResultMeta[stanResult, \"lp__\"]\nαe=GetStanResult[stanResult, \"alpha\"]\nβe=GetStanResult[stanResult, \"beta\"]\nσe=GetStanResult[stanResult, \"sigma\"]\n#+END_SRC\n\nwhich prints:\n\n#+BEGIN_EXAMPLE\n{-32.5116}\n{2.51749}\n{1.83654}\n{3.08191}\n#+END_EXAMPLE\n\n*Note*: as with likelihood maximization we only have a point estimation,\nthe returned values are lists of *one* number.\n\nYou can plot the estimated line:\n\n#+BEGIN_SRC mathematica :eval never\nShow[Plot[{αe + βe*x, α + β*x}, {x, Min[X],Max[X]}, PlotLegends -\u003e \"Expressions\"], \n     ListPlot[Transpose@{X, Y}, PlotStyle -\u003e Red]]\n#+END_SRC\n\n[[file:./figures/linRegEstimate.png]]\n\n** Run Stan, Variational Bayes\n\nWe want to solve the same problem but using variational inference. \n\nAs explained before we must use \n#+BEGIN_SRC mathematica :eval never\nstanResultFile = RunStan[stanExeFile, VariationalDefaultOptions]\n#+END_SRC\ninstead of \n#+BEGIN_SRC mathematica :eval never\nstanResultFile = RunStan[stanExeFile, OptimizeDefaultOptions]\n#+END_SRC\n\nHowever, please note that running this command will erase\n=stanResultFile= which is the file where result are exported. To avoid\nthis we can modify the output file name by modifying option values.\n\nThe default option values are stored in the write-protected\n=VariationalDefaultOptions= variable.\n\nTo modify them we must first copy this protected symbol:\n\n#+BEGIN_SRC mathematica :eval never\nmyOpt=VariationalDefaultOptions\n#+END_SRC\nwhich prints\n#+BEGIN_EXAMPLE\nmethod=variational\n#+END_EXAMPLE\n\nThe option values are printed when you run the =RunStan= command:\n\n#+BEGIN_EXAMPLE\nmethod = variational\n  variational\n    algorithm = meanfield (Default)\n      meanfield\n    iter = 10000 (Default)\n    grad_samples = 1 (Default)\n    elbo_samples = 100 (Default)\n    eta = 1 (Default)\n    adapt\n      engaged = 1 (Default)\n      iter = 50 (Default)\n    tol_rel_obj = 0.01 (Default)\n    eval_elbo = 100 (Default)\n    output_samples = 1000 (Default)\nid = 0 (Default)\ndata\n  file =  (Default)\ninit = 2 (Default)\nrandom\n  seed = 2784129612\noutput\n  file = output.csv (Default)\n  diagnostic_file =  (Default)\n  refresh = 100 (Default)\n#+END_EXAMPLE\n\nWe have to modify the =output file= option value. This can be done by:\n#+BEGIN_SRC mathematica :eval never\nmyOpt = SetStanOption[myOpt, \"output.file\", FileNameJoin[{Directory[], \"myOutputFile.csv\"}]]\n#+END_SRC\nwhich prints:\n#+BEGIN_EXAMPLE\nmethod=variational output file=/tmp/myOutputFile.csv\n#+END_EXAMPLE\n\nNow we can run Stan:\n\n#+BEGIN_SRC mathematica :eval never\nmyOutputFile=RunStan[stanExeFile, myOpt, StanVerbose -\u003e False]\n#+END_SRC\nwhich must print:\n#+BEGIN_EXAMPLE\n/tmp/myOutputFile.csv\n#+END_EXAMPLE\n\nNow import this CSV file:\n#+BEGIN_SRC mathematica :eval never\nmyResult = ImportStanResult[myOutputFile]\n#+END_SRC\nwhich prints:\n#+BEGIN_EXAMPLE\n     file: /tmp/myOutputFile.csv\n     meta: lp__ , log_p__ , log_g__ \nparameter: alpha , beta , sigma \n#+END_EXAMPLE\n\nAs before you can use:\n#+BEGIN_SRC mathematica :eval never\nGetStanResult[myResult,\"alpha\"]\n#+END_SRC\n\nto get =alpha= parameter value, but now you will get a list of 1000 sample:\n#+BEGIN_EXAMPLE\n{2.03816, 0.90637, ..., ..., 1.22068, 1.66392}\n#+END_EXAMPLE\n\nInstead of the full sample list we are often interested by sample\nmean, variance... You can get these quantities as follows:\n\n#+BEGIN_SRC mathematica :eval never\nGetStanResult[Mean, myResult, \"alpha\"]\nGetStanResult[Variance, myResult, \"alpha\"]\n#+END_SRC\n\nwhich prints:\n\n#+BEGIN_EXAMPLE\n2.0353\n0.317084\n#+END_EXAMPLE\n\nYou can also get the sample hstogram as simply as:\n\n#+BEGIN_SRC mathematica :eval never\nGetStanResult[Histogram, myResult, \"alpha\"]\n#+END_SRC\n\n[[file:figures/linRegHisto.png][file:./figures/linRegHisto.png]]\n\n** More about Option management\n\n*** Overwriting default values\n\nWe provide further details concerning option related functions.\n\nTo recap the first step is to perform a copy of the write-protected\ndefault option values. By example to modify default MCMC option values\nthe first step is:\n\n#+BEGIN_SRC mathematica :eval never\n  myOpt = SampleDefaultOptions\n#+END_SRC\n\nThe available option are:\n#+begin_example\nmethod = sample (Default)\n  sample\n    num_samples = 1000 (Default)\n    num_warmup = 1000 (Default)\n    save_warmup = 0 (Default)\n    thin = 1 (Default)\n    adapt\n      engaged = 1 (Default)\n      gamma = 0.050000000000000003 (Default)\n      delta = 0.80000000000000004 (Default)\n      kappa = 0.75 (Default)\n      t0 = 10 (Default)\n      init_buffer = 75 (Default)\n      term_buffer = 50 (Default)\n      window = 25 (Default)\n    algorithm = hmc (Default)\n      hmc\n        engine = nuts (Default)\n          nuts\n            max_depth = 10 (Default)\n        metric = diag_e (Default)\n        metric_file =  (Default)\n        stepsize = 1 (Default)\n        stepsize_jitter = 0 (Default)\nid = 0 (Default)\ndata\n  file = /tmp/linear_regression.data.R\ninit = 2 (Default)\nrandom\n  seed = 3714706817 (Default)\noutput\n  file = /tmp/linear_regression.csv\n  diagnostic_file =  (Default)\n  refresh = 100 (Default)\n  sig_figs = -1 (Default)\n#+end_example\n\nIf we want to modify:\n#+begin_example\nmethod = sample (Default)\n  sample\n    num_samples = 1000 (Default)\n    num_warmup = 1000 (Default)\n#+end_example\nand\n#+begin_example\nmethod = sample (Default)\n  sample\n    algorithm = hmc (Default)\n      hmc\n        engine = nuts (Default)\n          nuts\n            max_depth = 10 (Default)\n#+end_example\nyou must proceed as follows. For each hierarchy level use a \".\" as\nseparator and do not forget to rewrite \"=\" with the associated\nvalue. With our example this gives:\n\n#+BEGIN_SRC mathematica :eval never\nmyOpt = SetStanOption[myOpt, \"adapt.num_samples\", 2000]\nmyOpt = SetStanOption[myOpt, \"adapt.num_warmup\", 1500]\nmyOpt = SetStanOption[myOpt, \"algorithm=hmc.engine=nuts.max_depth\", 5]\n#+END_SRC\n\nNow you can run the sampler with these new option values:\n#+BEGIN_SRC mathematica :eval never\nstanResultFile = RunStan[stanExeFile, myOpt]\n#+END_SRC\nwhich should print:\n#+begin_example\nmethod = sample (Default)\n  sample\n    num_samples = 2000\n    num_warmup = 1500\n    save_warmup = 0 (Default)\n    thin = 1 (Default)\n    adapt\n      engaged = 1 (Default)\n      gamma = 0.050000000000000003 (Default)\n      delta = 0.80000000000000004 (Default)\n      kappa = 0.75 (Default)\n      t0 = 10 (Default)\n      init_buffer = 75 (Default)\n      term_buffer = 50 (Default)\n      window = 25 (Default)\n    algorithm = hmc (Default)\n      hmc\n        engine = nuts (Default)\n          nuts\n            max_depth = 5\n        metric = diag_e (Default)\n        metric_file =  (Default)\n        stepsize = 1 (Default)\n        stepsize_jitter = 0 (Default)\nid = 0 (Default)\ndata\n  file = /tmp/linear_regression.data.R\ninit = 2 (Default)\nrandom\n  seed = 3720771451 (Default)\noutput\n  file = /tmp/linear_regression.csv\n  diagnostic_file =  (Default)\n  refresh = 100 (Default)\n  sig_figs = -1 (Default)\nstanc_version = stanc3 b25c0b64\nstancflags = \n\n\nGradient evaluation took 1.3e-05 seconds\n1000 transitions using 10 leapfrog steps per transition would take 0.13 seconds.\nAdjust your expectations accordingly!\n\n\nIteration:    1 / 3500 [  0%]  (Warmup)\nIteration:  100 / 3500 [  2%]  (Warmup)\nIteration:  200 / 3500 [  5%]  (Warmup)\nIteration:  300 / 3500 [  8%]  (Warmup)\nIteration:  400 / 3500 [ 11%]  (Warmup)\nIteration:  500 / 3500 [ 14%]  (Warmup)\nIteration:  600 / 3500 [ 17%]  (Warmup)\nIteration:  700 / 3500 [ 20%]  (Warmup)\nIteration:  800 / 3500 [ 22%]  (Warmup)\nIteration:  900 / 3500 [ 25%]  (Warmup)\nIteration: 1000 / 3500 [ 28%]  (Warmup)\nIteration: 1100 / 3500 [ 31%]  (Warmup)\nIteration: 1200 / 3500 [ 34%]  (Warmup)\nIteration: 1300 / 3500 [ 37%]  (Warmup)\nIteration: 1400 / 3500 [ 40%]  (Warmup)\nIteration: 1500 / 3500 [ 42%]  (Warmup)\nIteration: 1501 / 3500 [ 42%]  (Sampling)\nIteration: 1600 / 3500 [ 45%]  (Sampling)\nIteration: 1700 / 3500 [ 48%]  (Sampling)\nIteration: 1800 / 3500 [ 51%]  (Sampling)\nIteration: 1900 / 3500 [ 54%]  (Sampling)\nIteration: 2000 / 3500 [ 57%]  (Sampling)\nIteration: 2100 / 3500 [ 60%]  (Sampling)\nIteration: 2200 / 3500 [ 62%]  (Sampling)\nIteration: 2300 / 3500 [ 65%]  (Sampling)\nIteration: 2400 / 3500 [ 68%]  (Sampling)\nIteration: 2500 / 3500 [ 71%]  (Sampling)\nIteration: 2600 / 3500 [ 74%]  (Sampling)\nIteration: 2700 / 3500 [ 77%]  (Sampling)\nIteration: 2800 / 3500 [ 80%]  (Sampling)\nIteration: 2900 / 3500 [ 82%]  (Sampling)\nIteration: 3000 / 3500 [ 85%]  (Sampling)\nIteration: 3100 / 3500 [ 88%]  (Sampling)\nIteration: 3200 / 3500 [ 91%]  (Sampling)\nIteration: 3300 / 3500 [ 94%]  (Sampling)\nIteration: 3400 / 3500 [ 97%]  (Sampling)\nIteration: 3500 / 3500 [100%]  (Sampling)\n\n Elapsed Time: 0.053 seconds (Warm-up)\n               0.094 seconds (Sampling)\n               0.147 seconds (Total)\n#+end_example\n\nYou can check than the new option values have been taken into account:\n#+begin_example\n    num_samples = 2000\n    num_warmup = 1500\n\n    algorithm = hmc (Default)\n      hmc\n        engine = nuts (Default)\n          nuts\n            max_depth = 5\n#+end_example\n\n*** Reading customized values\n\nYou can get back the modified values as follows:\n\n  #+BEGIN_SRC mathematica :eval never\nGetStanOption[myOpt, \"adapt.num_warmup\"]\nGetStanOption[myOpt, \"algorithm=hmc.engine=nuts.max_depth\"]\n  #+END_SRC\n  which prints\n  #+BEGIN_EXAMPLE\n  1500\n  5\n  #+END_EXAMPLE\n  *Caveat*: if the option was not defined (by =SetStanOption=) the function\n  returns =$Failed=.\n\n*** Erasing customized option values\n\nTo erase an option value (and use its default value) use:\n  #+BEGIN_SRC mathematica :eval never\n  myOpt = RemoveStanOption[myOpt, \"algorithm=hmc.engine=nuts.max_depth\"]\n  #+END_SRC\n  which prints\n  #+BEGIN_EXAMPLE\n  method=sample adapt num_samples=2000 num_warmup=1500 \n  #+END_EXAMPLE\n\n* Tutorial 2, linear regression with more than one predictor\n\n** Parameter arrays\n\nBy now the parameters alpha, beta, sigma, were *scalars*. We will see\nhow to handle parameters that are vectors or matrices. \n\nWe use second section of the [[https://mc-stan.org/docs/2_19/stan-users-guide/linear-regression.html][linear regression]] example, entitled\n\"Matrix notation and Vectorization\".\n\nThe β parameter is now a vector of size K. \n\n#+BEGIN_SRC mathematica :eval never \nstanCode = \"data {\n    int\u003clower=0\u003e N;   // number of data items\n    int\u003clower=0\u003e K;   // number of predictors\n    matrix[N, K] x;   // predictor matrix\n    vector[N] y;      // outcome vector\n  }\n  parameters {\n    real alpha;           // intercept\n    vector[K] beta;       // coefficients for predictors\n    real\u003clower=0\u003e sigma;  // error scale\n  }\n  model {\n    y ~ normal(x * beta + alpha, sigma);  // likelihood\n  }\";\n\nstanCodeFile = ExportStanCode[\"linear_regression_vect.stan\", stanCode];\nstanExeFile = CompileStanCode[stanCodeFile];\n#+END_SRC\n\n** Simulated data\n\nHere we use {x,x²,x³} as predictors, with their coefficients\nβ = {2,0.1,0.01} so that the model is \n\ny = α + β1 x + β2 x² + β3 x³ + ε\n\nwhere ε follows a normal distribution.\n\n#+BEGIN_SRC mathematica :eval never \nσ = 3; α = 1; β1 = 2; β2 = 0.1; β3 = 0.01;\nn = 20;\nX = Range[n];\nY = α + β1*X + β2*X^2 + β3*X^3 + RandomVariate[NormalDistribution[0, σ], n];\nShow[Plot[α + β1*x + β2*x^2 + β3*x^3, {x, Min[X], Max[X]}],\n     ListPlot[Transpose@{X, Y}, PlotStyle -\u003e Red]]\n#+END_SRC\n\n[[file:figures/linReg2Data.png][file:./figures/linReg2Data.png]]\n\n** Exporting data\n\nThe expression \n\ny = α + β1 x + β2 x² + β3 x³ + ε\n\nis convenient for random variable manipulations. However in practical\ncomputations where we have to evaluate:\n\ny[i] = α + β1 x[i] + β2 (x[i])² + β3 (x[i])³ + ε[i], for i = 1..N\n\nit is more convenient to rewrite this in a \"vectorized form\":\n\n*y* = *α* + *X.β* + *ε*\n\nwhere *X* is a KxN matrix of columns X[:,j] = j th-predictor = (x[:])^j\nand *α* a vector of size N with constant components = α.\n\nThus data is exported as follows:\n\n#+BEGIN_SRC mathematica :eval never \nstanData = \u003c|\"N\" -\u003e n, \"K\" -\u003e 3, \"x\" -\u003e Transpose[{X,X^2,X^3}], \"y\" -\u003e Y|\u003e;\nstanDataFile = ExportStanData[stanExeFile, stanData]\n#+END_SRC\n\n*Note:* as Mathematica stores its matrices rows by rows (the C\n language convention) we have to transpose ={X,X^2,X^3}= to get the\n right matrix X.\n\n** Run Stan, HMC sampling\n\nWe can now run Stan using the Hamiltonian Monte Carlo (HMC) method:\n\n#+BEGIN_SRC mathematica :eval never \nstanResultFile = RunStan[stanExeFile, SampleDefaultOptions]\n#+END_SRC\n\nwhich prints:\n\n#+BEGIN_EXAMPLE\nRunning: /tmp/linear_regression_vect method=sample data file=/tmp/linear_regression_vect.data.R output file=/tmp/linear_regression_vect.csv\n\nmethod = sample (Default)\n  sample\n    num_samples = 1000 (Default)\n    num_warmup = 1000 (Default)\n    save_warmup = 0 (Default)\n    thin = 1 (Default)\n    adapt\n      engaged = 1 (Default)\n      gamma = 0.050000000000000003 (Default)\n      delta = 0.80000000000000004 (Default)\n      kappa = 0.75 (Default)\n      t0 = 10 (Default)\n      init_buffer = 75 (Default)\n      term_buffer = 50 (Default)\n      window = 25 (Default)\n    algorithm = hmc (Default)\n      hmc\n        engine = nuts (Default)\n          nuts\n            max_depth = 10 (Default)\n        metric = diag_e (Default)\n        metric_file =  (Default)\n        stepsize = 1 (Default)\n        stepsize_jitter = 0 (Default)\nid = 0 (Default)\ndata\n  file = /tmp/linear_regression_vect.data.R\ninit = 2 (Default)\nrandom\n  seed = 3043713420\noutput\n  file = /tmp/linear_regression_vect.csv\n  diagnostic_file =  (Default)\n  refresh = 100 (Default)\n\n\nGradient evaluation took 4e-05 seconds\n1000 transitions using 10 leapfrog steps per transition would take 0.4 seconds.\nAdjust your expectations accordingly!\n\n\nIteration:    1 / 2000 [  0%]  (Warmup)\nIteration:  100 / 2000 [  5%]  (Warmup)\nIteration:  200 / 2000 [ 10%]  (Warmup)\nIteration:  300 / 2000 [ 15%]  (Warmup)\nIteration:  400 / 2000 [ 20%]  (Warmup)\nIteration:  500 / 2000 [ 25%]  (Warmup)\nIteration:  600 / 2000 [ 30%]  (Warmup)\nIteration:  700 / 2000 [ 35%]  (Warmup)\nIteration:  800 / 2000 [ 40%]  (Warmup)\nIteration:  900 / 2000 [ 45%]  (Warmup)\nIteration: 1000 / 2000 [ 50%]  (Warmup)\nIteration: 1001 / 2000 [ 50%]  (Sampling)\nIteration: 1100 / 2000 [ 55%]  (Sampling)\nIteration: 1200 / 2000 [ 60%]  (Sampling)\nIteration: 1300 / 2000 [ 65%]  (Sampling)\nIteration: 1400 / 2000 [ 70%]  (Sampling)\nIteration: 1500 / 2000 [ 75%]  (Sampling)\nIteration: 1600 / 2000 [ 80%]  (Sampling)\nIteration: 1700 / 2000 [ 85%]  (Sampling)\nIteration: 1800 / 2000 [ 90%]  (Sampling)\nIteration: 1900 / 2000 [ 95%]  (Sampling)\nIteration: 2000 / 2000 [100%]  (Sampling)\n\n Elapsed Time: 0.740037 seconds (Warm-up)\n               0.60785 seconds (Sampling)\n               1.34789 seconds (Total)\n#+END_EXAMPLE\n** Load the CSV result file\n\nAs before, \n\n#+BEGIN_SRC mathematica :eval never\nstanResult = ImportStanResult[stanResultFile]\n#+END_SRC\n\nload the generated CSV file and prints:\n\n#+BEGIN_EXAMPLE\n     file: /tmp/linear_regression_vect.csv\n     meta: lp__ , accept_stat__ , stepsize__ , treedepth__ , n_leapfrog__ , divergent__ , energy__ \nparameter: alpha , beta 3, sigma \n#+END_EXAMPLE\n\nCompared to the scalar case, the important thing to notice is the =beta 3=. That means that β is not a scalar anymore but a vector of size 3\n\n*Note*: here β is a vector, but if it had been a 3x5 matrix we would\n have had =β 3x5= printed instead.\n\nA call to \n#+BEGIN_SRC mathematica :eval never\nGetStanResult[stanResult, \"beta\"]\n#+END_SRC\nreturns a vector of size 3 but where each component is a list of 1000\nsample (for β1, β2 and β3).\n\nAs before it generally useful to summarize this sample with function like mean or histogram:\n\n#+BEGIN_SRC mathematica :eval never\nGetStanResult[Mean, stanResult, \"beta\"]\nGetStanResult[Histogram, stanResult, \"beta\"]\n#+END_SRC\n\nprints:\n#+BEGIN_EXAMPLE\n{3.30321, -0.010088, 0.0126913}\n#+END_EXAMPLE\nand plots:\n\n[[file:figures/linReg2Histo.png][file:./figures/linReg2Histo.png]]\n\n\nThis is the moment to digress about Keys. If you try:\n#+BEGIN_SRC mathematica :eval never\nStanResultKeys[stanResult]\nStanResultMetaKeys[stanResult]\n#+END_SRC\n\nthis will print:\n#+BEGIN_EXAMPLE\n{\"alpha\", \"beta.1\", \"beta.2\", \"beta.3\", \"sigma\"}\n{\"lp__\", \"accept_stat__\", \"stepsize__\", \"treedepth__\", \"n_leapfrog__\", \"divergent__\", \"energy__\"}\n#+END_EXAMPLE\n\nThese functions are useful to get the complete list of keys. Note\nthat, as β is an 1D-array of size 1 we have =beta.1, beta.2, beta.3=. If\nβ was a NxM matrix, the list of keys would have been: =beta.1.1,\nbeta.1.2,... beta.N.M=.\n\nThere is also *reduced keys* functions:\n\n#+BEGIN_SRC mathematica :eval never\nStanResultReducedKeys[stanResult]\nStanResultReducedMetaKeys[stanResult]\n#+END_SRC\n\nwhich print\n\n#+BEGIN_EXAMPLE\n{\"alpha\", \"beta\", \"sigma\"}\n{\"lp__\", \"accept_stat__\", \"stepsize__\", \"treedepth__\", \"n_leapfrog__\", \"divergent__\", \"energy__\"}\n#+END_EXAMPLE\n\nAs you can see the *reduced keys* functions collect and discard indices\nto keys associated to arrays.\n\nWhen accessing a parameter you can work at the component level or globally:\n#+BEGIN_SRC mathematica :eval never\nGetStanResult[Mean, stanResult, \"beta.2\"]\nGetStanResult[Mean, stanResult, \"beta\"]\n#+END_SRC\n\nwhich prints\n\n#+BEGIN_EXAMPLE\n-0.010088\n{3.30321, -0.010088, 0.0126913}\n#+END_EXAMPLE\n* Unit tests\nYou can run [[file:tests/CmdStan_test.wl]] to check that everything works\nas expected.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstan-dev%2Fmathematicastan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstan-dev%2Fmathematicastan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstan-dev%2Fmathematicastan/lists"}