1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rstan_create_package.R
\name{rstan_create_package}
\alias{rstan_create_package}
\alias{rstan_package_skeleton}
\title{Create a new \R package with compiled Stan programs}
\usage{
rstan_create_package(
path,
fields = NULL,
rstudio = TRUE,
open = TRUE,
stan_files = character(),
roxygen = TRUE,
travis = FALSE,
license = TRUE,
auto_config = TRUE
)
}
\arguments{
\item{path}{The path to the new package to be created (terminating in the
package name).}
\item{fields, rstudio, open}{Same as \code{\link[usethis:create_package]{usethis::create_package()}}. See
the documentation for that function, especially the note in the
\strong{Description} section about the side effect of changing the active
project.}
\item{stan_files}{A character vector with paths to \code{.stan} files to include
in the package.}
\item{roxygen}{Should \pkg{roxygen2} be used for documentation? Defaults to
\code{TRUE}. If so, a file \code{R/{pkgname}-package.R} is added to the package with
roxygen tags for the required import lines. See the \strong{Note} section below
for advice specific to the latest versions of \pkg{roxygen2}.}
\item{travis}{Should a \code{.travis.yml} file be added to the package directory?
This argument is now deprecated. We recommend using GitHub Actions to set
up automated testings for your package. See
https://github.com/r-lib/actions for useful templates.}
\item{license}{Logical or character; whether or not to paste the contents of
a \code{license.stan} file at the top of all Stan code, or path to such a
file. If \code{TRUE} (the default) adds the \verb{GPL (>= 3)} license (see
\strong{Details}).}
\item{auto_config}{Whether to automatically configure Stan functionality
whenever the package gets installed (see \strong{Details}). Defaults to \code{TRUE}.}
}
\description{
\if{html}{\figure{stanlogo.png}{options: width="25" alt="https://mc-stan.org/about/logo/"}}
The \code{rstan_create_package()} function helps get you started developing a
new \R package that interfaces with Stan via the \pkg{rstan} package. First
the basic package structure is set up via \code{\link[usethis:create_package]{usethis::create_package()}}.
Then several adjustments are made so the package can include Stan programs
that can be built into binary versions (i.e., pre-compiled Stan C++ code).
The \strong{Details} section below describes the process and the
\strong{See Also} section provides links to recommendations for developers
and a step-by-step walk-through.
As of version \verb{2.0.0} of \pkg{rstantools} the
\code{rstan_package_skeleton()} function is defunct and only
\code{rstan_create_package()} is supported.
}
\details{
This function first creates a regular \R package using
\code{usethis::create_package()}, then adds the infrastructure required to compile
and export \code{stanmodel} objects. In the package root directory, the user's
Stan source code is located in:
\preformatted{
inst/
|_stan/
| |_include/
|
|_include/
}
All \code{.stan} files containing instructions to build a \code{stanmodel}
object must be placed in \code{inst/stan}. Other \code{.stan} files go in
any \verb{stan/} subdirectory, to be invoked by Stan's \verb{#include}
mechanism, e.g.,
\preformatted{
#include "include/mylib.stan"
#include "data/preprocess.stan"
}
See \pkg{rstanarm} for many examples.
The folder \code{inst/include} is for all user C++ files associated with the
Stan programs. In this folder, the only file to directly interact with the
Stan C++ library is \code{stan_meta_header.hpp}; all other \verb{#include}
directives must be channeled through here.
The final step of the package creation is to invoke
\code{\link[=rstan_config]{rstan_config()}}, which creates the following files for
interfacing with Stan objects from \R:
\itemize{
\item \code{src} contains the \verb{stan_ModelName\{.cc/.hpp\}} pairs
associated with all \code{ModelName.stan} files in \code{inst/stan} which
define \code{stanmodel} objects.
\item \code{src/Makevars[.win]} which link to the \code{StanHeaders} and
Boost (\code{BH}) libraries.
\item \code{R/stanmodels.R} loads the C++ modules containing the
\code{stanmodel} class definitions, and assigns an \R instance of each
\code{stanmodel} object to a \code{stanmodels} list (with names
corresponding to the names of the Stan files).
}
When \code{auto_config = TRUE}, a \code{configure[.win]} file is added to the
package, calling \code{\link[=rstan_config]{rstan_config()}} whenever the package is installed.
Consequently, the package must list \pkg{rstantools} in the \code{DESCRIPTION}
Imports field for this mechanism to work. Setting \code{auto_config = FALSE}
removes the package's dependency on \pkg{rstantools}, but the package then
must be manually configured by running \code{\link[=rstan_config]{rstan_config()}} whenever
\code{stanmodel} files in \code{inst/stan} are added, removed, or modified.
In order to enable Stan functionality, \pkg{\link{rstantools}}
copies some files to your package. Since these files are licensed as GPL= 3, the same license applies to your package should you choose todistribute it. Even if you don't use \pkg{\link{rstantools}} to createyour package, it is likely that you will be linking to \pkg{\link{Rcpp}} toexport the Stan C++ stanmodel objects to \R. Since\pkg{\link{Rcpp}} is released under GPL >= 2, the same license would applyto your package upon distribution.
Authors willing to license their Stan programs of general interest
under the GPL are invited to contribute their \code{.stan} files and
supporting \R code to the \pkg{rstanarm} package.
}
\note{
For \pkg{devtools} users, because of changes in the latest versions of
\pkg{roxygen2} it may be necessary to run \code{pkgbuild::compile_dll()}
once before \code{devtools::document()} will work.
}
\section{Using the pre-compiled Stan programs in your package}{
The
\code{stanmodel} objects corresponding to the Stan programs included with your
package are stored in a list called \code{stanmodels}. To run one of the Stan
programs from within an R function in your package just pass the
appropriate element of the \code{stanmodels} list to one of the \pkg{rstan}
functions for model fitting (e.g., \code{sampling()}). For example, for a Stan
program \code{"foo.stan"} you would use \code{rstan::sampling(stanmodels$foo, ...)}.
}
\seealso{
\itemize{
\item \code{\link[=use_rstan]{use_rstan()}} for adding Stan functionality to an existing
\R package and \code{\link[=rstan_config]{rstan_config()}} for updating an existing package
when its Stan files are changed.
\item The \pkg{rstanarm} package \href{https://github.com/stan-dev/rstanarm}{repository}
on GitHub.
}
\itemize{
\item Guidelines and recommendations for developers of \R packages
interfacing with Stan and a demonstration getting a simple package working
can be found in the vignettes included with \pkg{rstantools} and at
\href{https://mc-stan.org/rstantools/articles/}{mc-stan.org/rstantools/articles}.
}
\itemize{
\item After reading the guidelines for developers, if you have trouble setting up
your package let us know on the the \href{https://discourse.mc-stan.org}{Stan Forums}
or at the \pkg{rstantools} GitHub \href{https://github.com/stan-dev/rstantools/issues}{issue tracker}.
}
}
|
