---
title: "Using Staninside"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using Staninside}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(staninside)
```

# Motivation

Stan is a powerful language and using R (and specifically rstan) as glue to allow R users to easily interface existing models.
Sometimes a user might wish to use a different backend (CmdStanR) or examine and modify the written Stan code directly.
This package seeks to allow users the ability to:

* Build R packages that are not pre-compiled by rstan
* Allow users to use CmdStanR in their R packages
* Allow users to easily see the Stan code within packages

## Building a Stan Package

### Package Infrastructure

If a package developer were to build a package with stanside, they first could create the package directory in the usual ways.

Next, to build the appropriate structure the author could call

```r
setup_stan_package()
```

This function will create the following directory tree:

```
.
├── inst
│   ├── stan
│   │   ├── base.stan
│   │   ├── data
│   │   ├── functions
│   │   ├── parameters

```
This provides the user with a structure to use when building their Stan programs.
For complicated programs, it is sometimes useful to break up the Stan code blocks into separate files stored in sub-directories. 
These separate `.stan` files can then be accessed within the Stan code with the following syntax:

```stan
# include functions/my_functions.stan
```
### Model Fitting

Generally speaking, there will be some function in an R package that will fit the data to a model. 
In order to faciliate this fitting with a CmdStanR backend, a process like that below could be used.

```r

fit_my_data <- function(my_data){
    requireNamespace("mypackage")
    local_location <- rappdirs::user_cache_dir(appname = "my_package")

    if (length(list.files(local_location, pattern = ".stan")) > 1) {
        cli::cli_alert_info("Using cached Stan models")
        cli::cli_alert_info(
        "Use `intervalcalc::clear_cache` if you need to refresh")
    } else {
        cli::cli_alert_info("Copying Stan models to cache")
        staninside::copy_models(this_pkg())
        cli::cli_alert_success("Models copied!")
    }
    
    model_file_path <- file.path(local_location, paste0("base", ".stan"))
        mod <- cmdstanr::cmdstan_model(model_file_path)
        
   fit <- mod$sample(data = my_data)
   
   return(fit)
}

```