Skip to content

Commit

Permalink
Merge pull request #11 from mitzimorris/install-tools-edits
Browse files Browse the repository at this point in the history 
install instruction updates, harmonize w/ tools page
  • Loading branch information
@mitzimorris
mitzimorris authored Nov 21, 2024
2 parents 0c331c1 + ff93ecb commit 654228e
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 240 deletions.
115 changes: 55 additions & 60 deletions install/install.qmd
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,25 @@
---
pagetitle: "Get Stan"
title: "Getting Started"
page-layout: full
toc-location: right
toc-depth: 3
---
## Download and Install Stan

Stan is available for all major operating systems and several programming languages.
You can get started by selecting your OS, programming language interface, and preferred installation method in the grid below.
If you don't see your exact set-up, see [Other Stan interfaces](#other-packages) below.
To analyze your data with Stan, you can either

- [Use Stan directly from within your preferred programming environment](#sec-install).
This option lets you write custom models using the Stan language and then fit them to data.

- Use a Stan based-modeling package - skip to [High-level Stan Interfaces](#high-level-stan-interfaces).
This option lets you specify your model using formula-based syntax, as in R packages `lm` and `lme4`,
eliminating the need to learn how to write Stan programs.


## Download and Install Stan {#sec-install}

To compile and run Stan models directly from within R, Python, or Julia,
select your OS, programming language interface, and preferred installation method in the grid below.
For other programming environments, skip to [Other Programming Environments](#other-programming-environments)

::: {#install-grid}
<!-- Filled in by JS -->
Expand All @@ -27,7 +37,7 @@ Prerequisites
::::: {.prereq #prereq-windows .hidden}
Stan requires a C++17 compiler and some build utilities.. The `conda`
option of certain packages can install these for you, otherwise these are bundled together
by [Rtools](https://cran.r-project.org/bin/windows/Rtools/).
by [Rtools](https://cran.r-project.org/bin/windows/Rtools/){target="_blank"}.
:::::

::::: {.prereq #prereq-macos .hidden}
Expand Down Expand Up @@ -171,18 +181,34 @@ then follow instructions in the README file.
Conda simplifies the installation process by ensuring that all required libraries and tools are compatible with each other
and is available for Linux, Mac, and Windows platforms.

You can either install [miniconda](https://docs.conda.io/en/latest/miniconda.html), a free, minimal installer for conda
or you can get the full [Anaconda](https://docs.continuum.io/anaconda/) system
You can either install [miniconda](https://docs.conda.io/en/latest/miniconda.html){target="_blank"}, a free, minimal installer for conda
or you can get the full [Anaconda](https://docs.continuum.io/anaconda/){target="_blank"} system
which provides graphical installer wizards for [MacOS](https://www.anaconda.com/products/distribution#macos){target="_blank"}
and [Windows](https://www.anaconda.com/products/distribution#windows){target="_blank"} users.

Julia users can install [Conda.jl](https://github.com/JuliaPy/Conda.jl){target="_blank"}.
:::

## Prerequisite: C++17 toolchain
### Other Programming Environments

| **Language** | **Tool** | **Description** |
|--------------|----------|-----------------|
| **R, Python** | [**Google Colab**](https://github.com/stan-dev/cmdstan/releases){target="_blank"} | Prebuilt CmdStan binaries for Google Colab are available from the GitHub CmdStan releases page. Installing these binaries at the start of a Colab session is much faster than installing CmdStan during a Colab session. |
| **Mathematica** | [**MathematicaStan**](https://github.com/stan-dev/MathematicaStan){target="_blank"} | Stan interface for Mathematica. Available from its GitHub repository.|
| **MATLAB** | [**MatlabStan**](https://github.com/brian-lau/MatlabStan/wiki){target="_blank"} | Installation instructions available on the MatlabStan wiki.|
| **Python** | [**PyStan**](https://pystan.readthedocs.io/){target="_blank"} | Available via pip. Run command: `python -m pip install pystan`.|
: {tbl-colwidths="[10, 20, 70]"}

::: {.callout-note}
As of Release 3.10.0, PyStan is no longer being actively supported.
:::



## Prerequisite: C++17 toolchain

Stan requires a C++17 compiler and the GNU Make utility.
Stan models are specified using the Stan language which are then compiled to executable programs that can be run on your data to perform inference and make predictions.
To use Stan from within your preferred programming environment, you need a **C++ toolchain** comprised of a C++17 compiler and the GNU Make utility.

* On Linux, these are bundled into the meta-package `build-essential`.
To install, run command:\
Expand All @@ -208,9 +234,9 @@ Both CmdStanPy and CmdStanR provide method `install_cmdstan` to do this from wit
and CmdStanPy also provides this as a command-line function.
See the online documentation:

* CmdStanPy: [install_cmdstan function](https://mc-stan.org/cmdstanpy/installation.html#function-install-cmdstan)
* CmdStanR: [install_cmdstan function](https://mc-stan.org/cmdstanr/reference/install_cmdstan.html)
* Stan.jl [build instructions](https://github.com/StanJulia/Stan.jl/blob/master/INSTALLING_CMDSTAN.md)
* CmdStanPy: [install_cmdstan function](https://mc-stan.org/cmdstanpy/installation.html#function-install-cmdstan){target="_blank"}
* CmdStanR: [install_cmdstan function](https://mc-stan.org/cmdstanr/reference/install_cmdstan.html){target="_blank"}
* Stan.jl [build instructions](https://github.com/StanJulia/Stan.jl/blob/master/INSTALLING_CMDSTAN.md){target="_blank"}

The default installation location is in the user's home directory and is named `.cmdstan` (a hidden directory).
This directory contains one or more versions of CmdStan.
Expand All @@ -222,34 +248,6 @@ Both CmdStanPy and CmdStanR provide the following functions:
* `cmdstan_path` - shows which version of CmdStan is being used
* `set_cmdstan_path` - specify which version of CmdStan to use.

## Other Stan Interfaces {#other-packages}

* Google Colab - prebuilt CmdStan binaries for Google Colab are available from the [GitHub CmdStan releases page](https://github.com/stan-dev/cmdstan/releases){target="_blank"}.
Installing these binaries at the start of a Colab session is much faster than installing CmdStan during a Colab session.

* MathematicaStan - available from GitHub repository: https://github.com/stan-dev/MathematicaStan

* MatlabStan - installation instructions available on the [MatlabStan wiki](https://github.com/brian-lau/MatlabStan/wiki){target="_blank"}

* PyStan is available from via pip, run commmand: `python -m pip install pystan`.

::: {.callout-note}
As of Release 3.10.0, PyStan is no longer being actively supported.
:::

## High-level Stan Interfaces for R Users

* [BRMS](https://github.com/paul-buerkner/brms) - The BRMS package (Bayesian Regression Models using Stan)
simplifies and streamlines the use of Stan by providing an extended R formula syntax for model specification,
not unlike that of package LME4.

* [RStanArm](https://mc-stan.org/rstanarm/) - RStanArm provides Stan versions of other R model-fitting functions.
It provides precompiled versions of common models which are robust to sampling problems.

* [Rethinking](https://github.com/rmcelreath/rethinking) - this package accompanies the book and course materials
for [Statistical Rethinking, 2nd Ed](https://www.taylorfrancis.com/books/mono/10.1201/9780429029608/statistical-rethinking-richard-mcelreath)
by Richard McElreath.

## Troubleshooting the Install

To help troubleshoot problems that arise when trying to use Stan,
Expand Down Expand Up @@ -283,27 +281,24 @@ Common Points of failure; how to address them.

See CmdStan Guide section [Troubleshooting the Installation](https://mc-stan.org/docs/cmdstan-guide/installation.html#troubleshooting-the-installation){target="_blank"} for further details.

## Introductory Notebooks, Vignettes, and Tutorials

### Python

* CmdStanPy User's Guide Examples

* "Getting Started with Bayesian Statistics using Stan and Python" by Bob Carpenter

* [Multilevel regression modeling with CmdStanPy and plotnine](case-studies/radon_cmdstanpy_plotnine.html){target="_blank"}

### R
## High-level Stan Interfaces

* CmdStanR Vignettes
| **Language** | **Tool** | **Description** |
|--------------|----------|-----------------|
| **R** | [**brms**](https://paul-buerkner.github.io/brms/){target="_blank"} | Use extended `lme4`-like formula syntax to specify and fit multivariate and multilevel models in Stan. *(Requires CmdStanR and C++ compiler.)* |
| **R** | [**RStanArm**](https://mc-stan.org/rstanarm){target="_blank"} | Provides stable, efficient Stan versions of R model-fitting packages. *(Stan models are pre-compiled, no C++ compiler needed.)* |
| **R** | [**Rethinking**](https://github.com/rmcelreath/rethinking){target="_blank"} | Accompanies the book and course materials for [Statistical Rethinking, 2nd Ed](https://www.taylorfrancis.com/books/mono/10.1201/9780429029608/statistical-rethinking-richard-mcelreath){target="_blank"} by Richard McElreath. *(Requires CmdStanR and C++ compiler.)*|
: {tbl-colwidths="[10, 15, 75]"}

* 2019 Ben Goodrich presentation on hierarchical models with RStan, BRMS, and RStanArm

### General Overview
## Introductory Notebooks,&nbsp; Vignettes,&nbsp; and Tutorials

* StanCon 2023 "Fundamentals of Stan"
| **Interface** | **Title** |
|--------------------|-----------------------------------------------------------------------------------------------|
| **CmdStanPy** | [CmdStanPy "Hello, World!"](https://mc-stan.org/cmdstanpy/users-guide/hello_world.html){target="_blank"}</br>[Getting Started with Bayesian Statistics using Stan and Python](https://github.com/bob-carpenter/stan-getting-started){target="_blank"}</br>[Multilevel regression modeling with CmdStanPy and plotnine](case-studies/radon_cmdstanpy_plotnine.html){target="_blank"} |
| **CmdStanR** | [Getting Started with CmdStanR](https://mc-stan.org/cmdstanr/articles/cmdstanr.html){target="_blank"}</br>[StanCon2023/Stan_tutorial.ipynb](https://github.com/charlesm93/stanTutorial/blob/main/StanCon2023/Stan_tutorial.ipynb){target="_blank"} |
| **Julia** | [Stan.jl Examples](https://github.com/StanJulia/Stan.jl/tree/master/Examples){target="_blank"} |
| **Google Colab** | [Stan Notebooks in the Cloud](https://mc-stan.org/users/documentation/case-studies/jupyter_colab_notebooks_2020.html){target="_blank"} |
: {tbl-colwidths="[20, 80]"}

* Course notes: *Software for MCMC* from Odd Kolbjørnsen, Spring 2023, Oslo Uni\
\fontsize{9pt}{9.4}\selectfont
www.uio.no/studier/emner/matnat/math/STK4051/v23/timeplan/lecture_12_softwareformcmc.pdf
\normalsize
For more learning resources, see the [Tutorials](../learn-stan/tutorials.qmd), [Publications](../learn-stan/publications.qmd) and [Stan Case Studies](../learn-stan/case-studies.qmd) pages.
1 change: 0 additions & 1 deletion theming/theme.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@ $sidebar-fg: $navy-blue;
/* Level 2 Headings */
h2 {
background-color: $palest-beige;
padding: 0.5em;
border-radius: 5px;
}

Expand Down
Loading

0 comments on commit 654228e

Please sign in to comment.