
\documentclass[11pt]{article}

\usepackage{indentfirst}
\usepackage{natbib}
\usepackage{url}

% \VignetteIndexEntry{Linking to Native Routines in This Package}

\begin{document}

\title{Linking to Native Routines in This Package}

\author{Charles J. Geyer}

\maketitle

\section{Aster Models}

Aster models implemented in this package (\texttt{aster},
\citealp{package-aster}) are described
by \citet*{gws} but are better described by the first draft of that
paper \citep*[Chapter~1]{gws-tr}.
or by the course slides
for a course on aster models
\url{http://www.stat.umn.edu/geyer/8931aster/slides/s2.pdf}.

The issue is that \citet{gws} describe too many aster models, those
implemented in the package \texttt{aster2} \citep{package-aster2},
and while discussing this package
we don't want to know about aster models it does not implement.

The aster models in this package are described by
\begin{enumerate}
\item[(a)] A directed acyclic graph in which each node has at most one
    predecessor.
\item[(b)] A one-parameter exponential family of distributions associated with
    each arrow of this graph.
\item[(c)] A data vector giving data for each non-initial node of the graph
    for each individual.
\item[(d)] A data vector giving data for each initial node of the graph
    for each individual.
\end{enumerate}

A node is \emph{initial} if it has no predecessor, otherwise \emph{non-initial}.
This agrees with the terminology used in the \texttt{aster2} package and
recent papers and technical reports about aster models by this author.
It disagrees with the terminology used in the \texttt{aster} package
which says \emph{root} instead of \emph{initial}.

In this package, every individual has the same graph.  Call the number of
non-initial nodes in that graph \texttt{nnode}.
Give these non-initial nodes indices (integers from 1 to \texttt{nnode})
so that each predecessor has a lower index than any of its successors.
Then the graph for one
individual is specified by an integer vector of length \texttt{nnode},
which gives for each non-initial node the index of its predecessor node
if its predecessor is non-initial and zero otherwise (meaning its predecessor
is an initial node).  Call this vector \texttt{pred}.  It specifies (a)
in the list above.

Item (b) in the list above is also specified by an integer vector of length
\texttt{nnode}.  Call it \texttt{fam}.
The specification also needs a mapping from integers to families.
The families for the model are specified by a list of R objects of
class \texttt{"astfam"}, which are described by the help page
\begin{verbatim}
library("aster")
help("families")
\end{verbatim}
Call this list \texttt{famlist}.  Then these must satisfy
\begin{verbatim}
all(fam %in% seq(along = famlist))
\end{verbatim}
Then \verb@famlist[[fam[j]]]@ specifies the family associated with the
arrow to node \texttt{j} from its predecessor.

Data at non-initial nodes is considered random and is specified by
a \texttt{double} vector of length \verb@nind * nnode@, where \texttt{nind}
is the number of individuals on which we have data.  The order in this vector is
first node of the graph for all individuals, second
node of the graph for all individuals (in the same order
as before), and so forth.   Call this vector \texttt{resp}.

Data at initial nodes is considered non-random and is specified by
a \texttt{double} vector of length \verb@nind * nnode@.
The order in this vector is the same as for \texttt{resp}.
Call this vector \texttt{root}.
The meaning of this vector is that if we turn \texttt{resp} and \texttt{root}
into matrices
\begin{verbatim}
resp <- matrix(resp, nind, nnode)
root <- matrix(root, nind, nnode)
\end{verbatim}
so \verb@resp[i, j]@ is the data for individual \texttt{i} and node \texttt{j},
then the arrow in the graph going to node \texttt{j} (there is exactly one
by assumption) has successor data \verb@resp[i, j]@ for individual \texttt{i}
and predecessor data
\begin{enumerate}
\item[(e)] \verb@resp[i, pred[j]]@ in case \verb@pred[j]@ is not zero, and
\item[(f)] \verb@root[i, j]@ in case \verb@pred[j]@ is zero.
\end{enumerate}
That specifies the aster model and its data.

Now we have parameters.  The \emph{conditional canonical parameterization}
of the saturated aster model is a vector \texttt{theta} laid out like
\texttt{resp} and \texttt{root}.  If we also consider it a matrix (like
we did for \texttt{resp} and \texttt{root} above), then \verb@theta[i, j]@
is the parameter for the conditional distribution of \verb@resp[i, j]@
given its predecessor data (specified by (e) or (f) in the list above as
the case may be).

We also have a parameter vector \texttt{phi} which is laid out like
\texttt{theta}, \texttt{root}, and \texttt{resp} called the
\emph{unconditional canonical parameter vector} of the saturated aster model.
This is too complicated to describe here.
See Section~2.3 of \citet{gws} or (better) Section~1.1.3 of \citet{gws-tr}
or (better still) the aforementioned course slides
(slides 1--37 of \url{http://www.stat.umn.edu/geyer/8931aster/slides/s2.pdf}).

Everything in this section agrees with this package and its documentation.
The other descriptions are just better descriptions of the same thing.

\paragraph{Summary}
A saturated aster model is specified by vectors \texttt{pred},
\texttt{fam}, and \texttt{famlist} described above.
Its data is specified by vectors \texttt{resp} and \texttt{root}
described above.
One particular distribution in the model is specified by a parameter
vector, one or the other of \texttt{theta} and \texttt{phi} described above.

\section{Evaluating the Aster Log Likelihood in C in Another Package}

This package registers two C functions via the \verb@R_RegisterCCallable@
mechanism described in Section 5.4.2 of \emph{Writing R Extensions}
\citep{r-extensions}.  Their prototypes (found in \verb@mlogl.h@ in
the \texttt{src} directory) are
\begin{verbatim}
double aster_mlogl_sat_unco(int nind, int nnode, int *pred, int *fam,
    double *phi, double *root, double *response, _Bool check);

double aster_mlogl_sat_cond(int nind, int nnode, int *pred, int *fam,
    double *theta, double *root, double *response, _Bool check);
\end{verbatim}
and a correct typedef for these functions is
found in the \verb@mlogl-export.h@ file in the \verb@inst/include@
directory, which, of course, is in the \verb@include@ directory when
this package is installed
\begin{verbatim}
typedef double (*aster_mlogl_sat_either_funptr)(int nind, int nnode,
    int *pred, int *fam, double *phi, double *root, double *response,
    _Bool check);
\end{verbatim}

To call one of these functions (for specificity, say the former)
from C code in another package, one does the following.
For a toy working example of this see the demonstration packages
in the \texttt{linkingTo} git repository \citet{linking-to}.
This discussion is copied from that.
\begin{enumerate}
\item The calling package (the one you write) must have
    \verb@aster (>= 0.9)@ in either the \texttt{Depends} or
    the \texttt{Imports} field of its \texttt{DESCRIPTION} file.
\item The calling package (the one you write) must have
    \verb@\import{aster}@ in its \texttt{NAMESPACE} file.
    Or perhaps only import some functions from aster in the
    \texttt{NAMESPACE} file with an \verb@\importFrom@ directive,
    as described in Section~1.5.1 of \emph{Writing R Extensions}
    \citep{r-extensions}.
    The purpose of this item and the preceding one is to have
    R package \texttt{aster} loaded before your package
    (so its code is available to yours).
\item The calling package (the one you write) must have
    \verb@aster (>= 0.9)@ in the \texttt{LinkingTo} field
    of its \texttt{DESCRIPTION} file.
    The purpose of this item is to have the include file \verb@mlogl-export.h@
    in R package \texttt{aster} available to your package, that is,
    \begin{verbatim}
    #include "mlogl-export.h"
    \end{verbatim}
    will work in C code in your package.
\end{enumerate}

Now in your package, you can write a function, call it \texttt{mlogl},
that has prototype the same as the function you are calling, that is,
\begin{verbatim}
double mlogl(int nind, int nnode, int *pred, int *fam,
    double *theta, double *root, double *response, _Bool check);
\end{verbatim}
Say you put that in a header file called \verb@mlogl.h@.

Then the following code should work
\begin{verbatim}
#include <stddef.h>             // defines NULL
#include <R_ext/Rdynload.h>     // defines R_GetCCallable
#include "mlogl-export.h"       // defines aster_mlogl_sat_either_funptr
#include "mlogl.h"              // defines mlogl

inline double mlogl(int nind, int nnode, int *pred, int *fam,
    double *phi, double *root, double *response, _Bool check)
{
    static aster_mlogl_sat_either_funptr fun = NULL;
    if (fun == NULL)
        fun = (aster_mlogl_sat_either_funptr)
            R_GetCCallable("aster", "aster_mlogl_sat_unco");
    return fun(nind, nnode, pred, fam, phi, root, response, check);
}
\end{verbatim}

Now there is one last thing to say.  What happened to \texttt{famlist}?
\begin{enumerate}
\item[4.] Before any calls to \texttt{mlogl} one must call from R
    (before going to C)
    \begin{verbatim}
    aster:::setfam(famlist)
    \end{verbatim}
    This sets the identification of integers with families.
\item[5.] Then one can call \texttt{mlogl} (from C) as many times
    as one likes.
\item[6.] Finally (after returning to R from C) one should call (from R)
    \begin{verbatim}
    aster:::clearfam()
    \end{verbatim}
    This clears the identification of integers with families.
\end{enumerate}



\begin{thebibliography}{}

\bibitem[Geyer(2015)]{package-aster2}
Geyer, C.~J. (2015).
\newblock R package \texttt{aster2} (Aster Models), version 0.2-1.
\newblock \url{http://www.stat.umn.edu/geyer/aster/} and
    \url{https://cran.r-project.org/package=aster2}.

\bibitem[Geyer(2017a)]{package-aster}
Geyer, C.~J. (2017a).
\newblock R package \texttt{aster} (Aster Modeels), version 0.9.
\newblock \url{http://www.stat.umn.edu/geyer/aster/} and
    \url{https://cran.r-project.org/package=aster}.

\bibitem[Geyer(2017b)]{linking-to}
Geyer, C.~J. (2017b).
\newblock Github repo \texttt{linkingTo}, which contains two R packages
      \texttt{foompter} (version 0.2) and \texttt{goompter}
      (version 0.2) illustrating calling
      C functions from one from C functions called from R in the other.
      \url{https://github.com/cjgeyer/linkingTo}.

\bibitem[Geyer et al.(2007a)Geyer, Wagenius and Shaw]{gws}
Geyer, C.~J., Wagenius, S. and Shaw, R.~G. (2007a).
\newblock Aster models for life history analysis.
\newblock \emph{Biometrika}, \textbf{94}, 415--426.

\bibitem[Geyer et al.(2007b)Geyer, Wagenius and Shaw]{gws-tr}
Geyer, C.~J., Wagenius, S. and Shaw, R.~G. (2007b).
\newblock Aster models for life history analysis.
\newblock Technical Report No. 644, School of Statistics, University of
    Minnesota.
\newblock \url{http://www.stat.umn.edu/geyer/aster/tr644.pdf}.

\bibitem[R Development Core Team(2017)]{r-extensions}
R Development Core Team (2017).
\newblock \emph{Writing R Extensions}.
\newblock \url{https://cran.r-project.org/doc/manuals/r-release/R-exts.html}.
\newblock Also available in PDF or EPUB format.

\end{thebibliography}

\end{document}

Following the example in the help page for the R function
\texttt{aster} in this package,
\begin{verbatim}
library("aster")
help("aster")
\end{verbatim}
