% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/remify2.R
\name{remify}
\alias{remify}
\title{Process a Relational Event History}
\usage{
remify(
  edgelist,
  directed = TRUE,
  ordinal = FALSE,
  model = c("tie", "actor"),
  thin = 1,
  actors = NULL,
  riskset = c("full", "active", "active_saturated", "manual"),
  manual.riskset = NULL,
  extend_riskset_by_type = FALSE,
  event_type = NULL,
  origin = NULL,
  time.units = c("auto", "secs", "mins", "hours", "days", "weeks"),
  attach_riskset = TRUE,
  riskset_decode = c("labels", "ids", "none"),
  riskset_max_decode = 200000L,
  event_covariates = NULL,
  ncores = 1L,
  omit_dyad = NULL
)
}
\arguments{
\item{edgelist}{the relational event history. An object of class \code{\link[base]{data.frame}} with first three columns corresponding to time, and actors forming the dyad. The first three columns will be re-named "time", "actor1", "actor2" (where, for directed networks, "actor1" corresponds to the sender and "actor2" to the receiver of the relational event). Optional columns that can be supplied are: `type` and `weight`. If one or both exist in \code{edgelist}, they have to be named accordingly.}

\item{directed}{logical value indicating whether events are directed (\code{TRUE}) or undirected (\code{FALSE}). (default value is \code{TRUE})}

\item{ordinal}{logical value indicating whether only the order of events matters in the model (\code{TRUE}) or also the exact timing must be considered in the model (\code{FALSE}). (default value is \code{FALSE}). If \code{TRUE}, then the column "time" of \code{edgelist} is still used to extract the order.}

\item{model}{either \code{"tie"} (default) or \code{"actor"} oriented modeling. For \code{"tie"}, the riskset is at the dyad level. For \code{"actor"}, the model has two sub-processes: a sender rate model (who sends next?) and a receiver choice model (who does the sender choose?). Actor-oriented modeling requires \code{directed=TRUE}. The returned object includes \code{sender_riskset}, \code{receiver_riskset}, and \code{activeN} (see \code{@return}).}

\item{thin}{Integer >= 1. Event-time thinning based on unique time points.
Keeps every \code{thin}-th unique event time (after time translation) and
maps each event time to the next kept time point (i.e., ceiling to the kept grid).
This reduces the number of unique time points (and thus memory/computation in later steps).}

\item{actors}{[\emph{optional}] character vector of actors' names that may be observed interacting in the network. If \code{NULL} (default), actors' names will be taken from the input edgelist.}

\item{riskset}{[\emph{optional}] character value indicating the type of risk set to process: \code{riskset = "full"} (default) consists of all the possible dyadic events given the number of actors (and the number of event types) and it mantains the same structure over time. \code{riskset = "active"} considers at risk only the observed dyads and it mantains the same structure over time. \code{riskset = "manual"}, allows the risk set to have a structure that is user-defined, and it is based on the instructions supplied via the argument \code{omit_dyad}. This type of risk set allows for time-varying risk set, in which, for instance, subset of actors can interact only at specific time windows, or events of a specific type (sentiment) can't be observed within time intervals that are defined by the user. \code{riskset = "active_saturated"} extends the active riskset by adding the reverse direction for each observed dyad (if A->B is observed, B->A is also at risk) and includes all event types for each observed actor pair (type column is ignored). This reflects the assumption that observing any interaction between two actors implies both directions and all types are possible.}

\item{manual.riskset}{[\emph{optional}] When \code{riskset = "manual"}, this argument of class \code{\link[base]{data.frame}} specifies which dyadic riskset to consider through the entire sequence. If observed dyads from the \code{edgelist} are missing, they will be automatically be added.}

\item{extend_riskset_by_type}{logical. \code{FALSE} (default). When event types are present (via
\code{event_type}), controls whether the risk set is expanded over types.
If \code{TRUE} (default when types are present), each actor pair is
duplicated for each event type, so the risk set has size
\eqn{D = N(N-1) \times C} (directed) or \eqn{D = N(N-1)/2 \times C}
(undirected), and the \code{type} column appears in the decoded risk set.
If \code{FALSE}, event type is treated as a mark on events only and does
not expand the risk set: \eqn{D = N(N-1)} (directed) or
\eqn{D = N(N-1)/2} (undirected), and no \code{type} column appears in the
decoded risk set. This argument is ignored when no event types are present.}

\item{event_type}{Optional. Either \code{NULL} (default) or a single character
  string giving the name of the column in \code{edgelist} that contains event
  types (marks).

  If \code{event_type} is \code{NULL}, \code{remify()} uses \code{edgelist$type}
  if it exists; otherwise events are treated as untyped.

  If \code{event_type} is a column name, that column is used as the event-type
  mark. If a column named \code{type} already exists and \code{event_type != "type"},
  the existing \code{edgelist$type} is overridden (with a warning).

  When event types are present (via \code{edgelist$type} or \code{event_type}),
  the dyadic risk set is extended over types, i.e., each dyad is duplicated for
  each event type (dyad \eqn{\times} type).}

\item{origin}{[\emph{optional}] starting time point of the observation period (default is \code{NULL}). If it is supplied, it must have the same class of the `time` column in the input \code{edgelist}. If unsupplied, the origin
is set to the average waiting time in the sequence subtracted from the time of the first event.}

\item{time.units}{Character string specifying the time unit for converting time values when `edgelist$time` is of class Date or POSIXct; ignored for numeric or integer time. Default is "secs".}

\item{attach_riskset}{Logical. If \code{TRUE}, attaches a list \code{riskset_info}
to the returned \code{remify} object. The list contains the effective risk set
representation used for estimation (e.g., \code{riskset_idx}, \code{dyadIDactive},
dictionaries, and basic risk set metadata). This is intended to make the
returned object self-describing and easier to inspect/debug.}

\item{riskset_decode}{Character. Controls how (and whether) the included risk set
dyads are decoded and attached in \code{riskset_info$included}.
\describe{
  \item{\code{"labels"}}{Attach a decoded dyad table including actor (and type)
    labels (e.g., \code{actor1}, \code{actor2}, and optional \code{type}).}
  \item{\code{"ids"}}{Attach a decoded dyad table with integer IDs only
    (e.g., \code{actor1ID}, \code{actor2ID}, optional \code{typeID}, and \code{dyadID}).}
  \item{\code{"none"}}{Do not attach a decoded dyad table.}
}}

\item{riskset_max_decode}{Integer. Maximum number of included dyads (i.e.,
\code{length(riskset_idx)} / \code{D_active}) for which \code{riskset_decode="labels"}
is allowed. If the included risk set exceeds this threshold, decoding to labels
is skipped (typically falling back to \code{"ids"} with a warning) to avoid large
memory usage.}

\item{event_covariates}{Optional character vector of column names in
  \code{edgelist} to retain as additional event-level variables in the
  returned \code{reh} object.

  These columns are stored as \code{reh$event_covariates} together with the
  corresponding \code{time}, \code{actor1}, and \code{actor2} columns (and an
  internal \code{.event_id}). This is useful when downstream functions (e.g.,
  in \pkg{remstats}) need access to event-level marks/covariates that are not
  part of the core \code{reh$edgelist} produced by \code{remify()}.

  Note: \code{event_covariates} does not affect risk set construction or type
  handling in \code{remify()}; it only preserves additional columns for later
  use. Currently there is no further support yet when event_covariates
  have been added.}

\item{ncores}{[\emph{optional}] number of cores used in the parallelization of the processing functions. (default is \code{1}).}

\item{omit_dyad}{Deprecated. Set to \code{NULL}.}
}
\value{
A \code{remify} S3 object (list) with the following elements:
  \itemize{
    \item \code{M} number of events (or unique time points if simultaneous events exist).
    \item \code{N} number of actors.
    \item \code{C} number of event types (1 if untyped).
    \item \code{D} number of dyads in the riskset.
    \item \code{intereventTime} vector of inter-event waiting times (\code{NULL} if \code{ordinal=TRUE}).
    \item \code{edgelist} processed input edgelist as \code{data.frame}.
    \item \code{edgelist_id} per-event integer ID summary.
    \item \code{meta} list of metadata (model, directed, ordinal, riskset, dictionary, etc.).
    \item \code{ids} list of per-event integer IDs (actor1, actor2, dyad, type).
    \item \code{index} list of decoded riskset tables (\code{dyad_map} or \code{dyad_map_active} for tie model; \code{sender_map} for actor model).
    \item \code{activeD} number of active dyads (tie model, \code{riskset="active"} or \code{"manual"} only).
    \item \code{riskset_info} decoded riskset metadata (tie model only, when \code{attach_riskset=TRUE}).
  }
  For \strong{actor-oriented models} (\code{model="actor"}), the following additional elements are returned:
  \itemize{
    \item \code{sender_riskset} integer vector of actor IDs allowed to send (all actors for \code{"full"}; observed senders for \code{"active"}; senders in \code{manual.riskset} for \code{"manual"}/\code{"active_saturated"}).
    \item \code{receiver_riskset} named list (actor names) of integer vectors of allowed receiver IDs per sender.
    \item \code{activeN} number of active senders.
    \item \code{index\$sender_map} data.frame with columns \code{senderID} and \code{actorName} for active senders.
  }
}
\description{
A function that processes raw relational event history data and returns a S3 object of class 'remify' which is used as input in other functions inside 'remverse'.
}
\details{
In \code{omit_dyad}, the \code{NA} value can be used to remove multiple objects from the risk set at once with one risk set modification list. For example, to remove all events with sender equal to actor “A” add a list with two objects \code{time = c(NA, NA)} and \code{dyad = data.frame(actor1 = A, actor2 = NA, type = NA)} to the \code{omit_dyad} list. For more details about
}
\examples{

# load package and random network 'randomREH'
library(remify)
data(randomREH)

# first events in the sequence
head(randomREH$edgelist)

# actor's names
randomREH$actors

# event type's names
randomREH$types

# start time of the study (origin)
randomREH$origin

# list of changes of the risk set: each one is a list of:
# 'time' (indicating the time window where to apply the risk set reduction)
# 'dyad' (a data.frame describing the dyads to remove from the risk set
# during the time window specified in 'time')
str(randomREH$omit_dyad)

# -------------------------------------- #
#  processing for tie-oriented modeling  #
# -------------------------------------- #

tie_randomREH <- remify(edgelist = randomREH$edgelist,
       directed = TRUE,
       ordinal = FALSE,
       model = "tie",
       origin = randomREH$origin)

# summary
summary(tie_randomREH)

# visualize descriptive measures of relational event data
plot(x = tie_randomREH)

# -------------------------------------- #
# processing for actor-oriented modeling #
# -------------------------------------- #

# loading network 'randomREHsmall'
data(randomREHsmall)

# processing small random network
actor_randomREH <- remify(edgelist = randomREHsmall$edgelist,
       directed = TRUE,
       ordinal = FALSE,
       model = "actor",
       actors = randomREHsmall$actors,
       origin = randomREHsmall$origin)

# summary
summary(actor_randomREH)

# visualize
plot(actor_randomREH)

# ------------------------------------ #
# for more information about remify()  #
# check: vignette(package="remify")    #
# ------------------------------------ #


}
