shinystan-package.Rmd

---
title: 'Getting Started'
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Using the ShinyStan app with different types of objects

## stanfit objects

If `my_stanfit` is a stanfit object (the result of fitting a model with
[**rstan**](https://mc-stan.org/)), then to launch the ShinyStan app simply use

```r
library(shinystan)
my_sso <- launch_shinystan(my_stanfit)
```

and ShinyStan will launch. Here `my_sso` is the name you want to use for the
shinystan object that will be returned. If you simply run

```r
launch_shinystan(my_stanfit)
```

then ShinyStan will launch but no shinystan object will be saved upon quitting
the app. 

Sometimes keeping only a subset of parameters before can improve performance.
This can be done by creating an object with `as.shinystan` and specifying the
`pars` argument. The resulting shinystan object can then be passed to
`launch_shinystan()`.


### stanreg and brmsfit objects

The **rstanarm** and **brms** packages provide `launch_shinystan` methods for stanreg and brmsfit objects, 
respectively. For example, the method for stanreg objects is 
documented at 

http://mc-stan.org/rstanarm/reference/launch_shinystan.stanreg.html

## mcmc.list objects

If you have an `mcmc.list` object called `my_mcmc` then you can use the
`as.shinystan` function to convert `my_mcmc` into a shinystan object that can
then be used with `launch_shinystan`:

```r
my_sso <- launch_shinystan(as.shinystan(my_mcmc, model_name = "my_model"))
```

If, for example, the first 100 iterations in each chain in `my_mcmc` are 
warmup iterations, you should add the `warmup` argument when you 
call `as.shinystan`:

```r
my_sso <- launch_shinystan(as.shinystan(my_mcmc, model_name = "my_model", warmup = 100))
```

However, you should only use the `warmup` argument if the warmup iterations have 
been saved and included in `my_mcmc`.   


## Other types of objects

### 3-D array

To convert a 3-D array to a shinystan object make sure that the three dimensions 
of the array correspond to the 
*number of iterations* **x** *number of chains*  **x** *number of parameters*. 
You can then `as.shinystan` exactly how it's used in the examples for `mcmc.list`
objects above (but you don't need to convert your array  to an `mcmc.list`).

### List of matrices

If you have separate chains that are each a matrix (with iterations as rows and
parameters as columns) you can combine them in a list to pass to `as.shinystan`

```r
# Generate some fake data
chain1 <- cbind(beta1 = rnorm(100), beta2 = rnorm(100), sigma = rexp(100))
chain2 <- cbind(beta1 = rnorm(100), beta2 = rnorm(100), sigma = rexp(100))
chain_list <- list(chain1, chain2)
my_sso <- launch_shinystan(as.shinystan(X = list(chain1, chain2), model_name = "my_model"))
```


******

# Other functions in the shinystan package

## Generating new quantities

You can add a new parameter/quantity as a function of one or two existing 
parameters to your shinystan object by using the `generate_quantity` function. 
For example, assume `sso` is a shinystan object and two of the parameters are
```alpha``` and ```beta```. We could add a parameter ```gamma``` that is the 
inverse logit of ```beta``` using the code

```r
inv_logit <- function(x) 1/(1 + exp(-x))
sso <- generate_quantity(sso, fun = inv_logit, param1 = "beta", new_name = "gamma")
```

Here, `fun` is the function we want to use, `param1` is the name of the parameter 
to apply the function to, and `new_name` is the name to give the new parameter. 

Adding a parameter as a function of two parameters just requires specifying the
`param2` argument and providing a function of two variables. For example, we can 
add a parameter `delta` to `sso` that is the squared difference of `alpha` and 
`beta` like this

```r
sso <- generate_quantity(sso, fun = function(x,y) (x-y)^2,
                       param1 = "alpha", param2 = "beta", new_name = "delta")
```


## Storing your model code in a shinystan object

For models fit using **rstan** the model code will 
automatically be stored in the `model_code` slot of your shinystan object. 
When ShinyStan is open you can view your model code in the *Model Code* tab. 

If you did not use **rstan** fit your model then you can add your model code 
by using the `model_code()` function. For example, you may have used Bugs 
or JAGS or some other software and want to add the following code

```
  for (i in 1:length(Y)) {
     Y[i] ~ dpois(lambda[i])
     log(lambda[i]) <- inprod(X[i,], theta[])
   }
   for (j in 1:J) {
     theta[j] ~ dt(0.0, 1.0, 1.0)
   }
 }
```

to your shinystan object. To add that code you can simply include it as the 
`code` argument to the `model_code` function 

```r
my_code <- "
 model {
  for (i in 1:length(Y)) {
     Y[i] ~ dpois(lambda[i])
     log(lambda[i]) <- inprod(X[i,], theta[])
   }
   for (j in 1:J) {
     theta[j] ~ dt(0.0, 1.0, 1.0)
   }
 }
"

# Add the code to a shinystan object sso
sso <- model_code(sso, code = my_code)
```

## Renaming a model

On the home page ShinyStan will display the model name associated with the 
shinystan object being used. This name can be set by adding the `model_name`
argument to `as.shinystan` when creating a shinystan object. For an existing
shinystan object you can use the `model_name` function like this:

```r
sso <- model_name(sso, "new_model_name")
```

where `"new_model_name"` is the new name you want to give your model.