% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aomstats.R
\name{aomstats}
\alias{aomstats}
\title{aomstats}
\usage{
aomstats(
  reh,
  sender_effects = NULL,
  receiver_effects = NULL,
  attr_actors = NULL,
  attr_dyads = NULL,
  memory = c("full", "window", "decay", "interval"),
  memory_value = NA,
  start = 2,
  stop = Inf,
  display_progress = FALSE
)
}
\arguments{
\item{reh}{an object of class \code{"\link[remify]{remify}"} characterizing 
the relational event history.}

\item{sender_effects}{an object of class \code{"\link[stats]{formula}"} (or
one that can be coerced to that class): a symbolic description of the
effects in the sender activity rate step of the actor-oriented model for
which statistics are computed, see `Details'}

\item{receiver_effects}{an object of class \code{"\link[stats]{formula}"}
(or one that can be coerced to that class): a symbolic description of the
effects in the receiver choice step of model for which statistics are
computed, see `Details'}

\item{attr_actors}{optionally, an object of class
\code{"\link[base]{data.frame}"} that contains exogenous attributes for 
actors (see Details).}

\item{attr_dyads}{optionally, an object of class \code{data.frame} or 
\code{matrix} containing attribute information for dyads (see Details).}

\item{memory}{The memory to be used. See `Details'.}

\item{memory_value}{Numeric value indicating the memory parameter. Default 
is \code{NA}, which is only valid for \code{memory = "full"} (no memory
parameter required). See `Details'.}

\item{start}{an optional integer value, specifying the index of the first
time or event in the relational event history for which statistics must be 
computed (see 'Details'). Default is \code{2}: the first event has no history and is used only to initialize statistics, not to fit the model.}

\item{stop}{an optional integer value, specifying the index of the last
time or event in the relational event history for which statistics must be 
computed (see 'Details')}

\item{display_progress}{should a progress bar for the computation of the
endogenous statistics be shown (TRUE) or not (FALSE)?}
}
\value{
An object of class 'aomstats'. List with in the first element the
statistics for the sender activity rate step and in the second element the
statistics for the receiver choice step. Statistics are computed once per 
unique time point (per-timepoint "pt" method), so the number of rows in the 
output equals \code{reh$M} (the number of  unique time points), which may be 
less than the total number of observed events when simultaneous events are 
present. The 'aomstats' object has the following attributes: 
  \describe{
    \item{\code{model}}{Type of model that is estimated.}
    \item{\code{formula}}{Model formula(s), obtained from the formula(s) 
    inputted to 'sender_effects' and/or 'receiver_effects'.}
    \item{\code{actors}}{The set of actors used to construct the statistics, 
    obtained from the remify object inputted to 'reh'.}
  }
}
\description{
Computes statistics for the sender activity rate step and receiver choice
step in actor-oriented relational event models (e.g., see Stadtfeld & Block,
2017).
}
\section{Effects}{

The statistics to be computed are defined symbolically and should be
supplied to the \code{sender_effects} and/or \code{receiver_effects}
arguments in the form \code{~ effects}. The terms are separated by +
operators. For example: \code{receiver_effects = ~ inertia() + otp()}.
Interactions between two effects can be included with * or :
operators. For example: \code{receivereffects = ~ inertia():otp()}.  A list
of available effects can be obtained with \code{\link{actor_effects}()}.

The majority of the statistics can be scaled in some way, see
the documentation of the \code{scaling} argument in the separate effect
functions for more information on this.
}

\section{attr_actors}{

For the computation of the \emph{exogenous} statistics an attributes object
with the exogenous covariate information has to be supplied to the
\code{attr_actors} argument in either \code{remstats()} or in the separate
effect functions supplied to the \code{..._effects} arguments (e.g., see
\code{\link{send}}). This \code{attr_actors} object should be constructed as
follows: A dataframe with rows referring to the attribute value of actor
\emph{i} at timepoint \emph{t}. A `name` column is required that contains the
actor name (corresponding to the actor names in the relational event
history). A `time` column is required that contains the time when attributes
change (set to zero if none of the attributes vary over time). Subsequent
columns contain the attributes that are called in the specifications of
exogenous statistics (column name corresponding to the string supplied to
the \code{variable} argument in the effect function). Note that the
procedure for the exogenous effects `tie' and `event' deviates from this,
here the exogenous covariate information has to be specified in a different
way, see \code{\link{tie}} and \code{\link{event}}.
}

\section{attr_dyads}{
  
For the computation of the \emph{dyad exogenous} statistics with \code{tie()}, an attributes object with the exogenous covariates information per dyad has to be supplied. This is a \code{data.frame} or \code{matrix} containing attribute information for dyads. If \code{attr_dyads} is a \code{data.frame}, the first two columns should represent "actor1" and "actor2" (for directed events, "actor1" corresponds to the sender, and "actor2" corresponds to the receiver). Additional columns can represent dyads' exogenous attributes. If attributes vary over time, include a column named "time". If \code{attr_dyads} is a \code{matrix}, the rows correspond to "actor1", columns to "actor2", and cells contain dyads' exogenous attributes.
}

\section{Memory}{

The default `memory` setting is `"full"`, which implies that at each time
point $t$ the entire event history before $t$ is included in the computation
of the statistics. Alternatively, when `memory` is set to `"window"`, only
the past event history within a given time window is considered (see
Mulders & Leenders, 2019). This length of this time window is set by the
`memory_value` parameter. For example, when `memory_value = 100` and `memory
= "window"`, at time point $t$ only the past events that happened at most
100 time units ago are included in the computation of the statistics.
A third option is to set `memory` to `"interval"`. In this case, the past
event history within a given time interval is considered. For example, when
`"memory_value" = c(50, 100)` and `memory = "window"`, at time point $t$
only the past events that happened between 50 and 100 time units ago are
included in the computation of the statistics. Finally, the fourth option is
to set `memory` to `"decay"`. In this case, the weight of the past event in
the computation of the statistics depend on the elapsed time between $t$ and
the past event. This weight is determined based on an exponential decay
function with half-life parameter `memory_value` (see Brandes et al., 2009).
}

\section{Event weights}{

Note that if the relational event history contains a column that is named
``weight'', it is assumed that these affect the endogenous statistics. These
affect the computation of all endogenous statistics with a few exceptions
that follow logically from their definition (e.g., the recenyContinue
statistic does depend on time since the event and not on event weights).
}

\section{Subset of the relational event history}{

Optionally, statistics can be computed for a slice of the relational event
sequence - but based on the entire history. This is achieved by setting the
start and stop values equal to the index of the first and last event for
which statistics are requested. For example, start = 5 and stop = 5 computes
the statistics for only the 5th event in the relational event sequence,
based on the history that consists of events 1-4.
}

\examples{
library(remstats)

# Load the data
data(history)
data(info)

# Prepare the data
reh <- remify::remify(edgelist = history, model = "actor")

# Define the sender effects
seff <- ~ send("extraversion")

# Define the receiver_effects
reff <- ~ receive("agreeableness") + inertia() + otp()

# Compute the statistics
aomstats(
  reh = reh, sender_effects = seff, receiver_effects = reff,
  attr_actors = info
)

}
\references{
Stadtfeld, C., & Block, P. (2017). Interactions, actors, and
time: Dynamic network actor models for relational events. Sociological
Science, 4, 318–352. \doi{10.15195/v4.a14}
}
