2  Events

hawkesNet is events-first. Instead of converting your data into a network object up-front, you provide node arrivals and edge arrivals as data frames, then call make_events() to convert them into the internal events representation used by simulation and fitting.

Input data frames

As stated, the two inputs are an edges and a nodes data frame.

Note

The nodes data frame is not required. Node arrival times can be inferred from the edge alone (make sure allow_implicit_births = TRUE when using make_events()). However, if you only pass edges, you cannot represent edgeless node arrivals, as the node only exists when it first appears in an edge.

edges

Column	Type	Meaning	Notes
i	character / integer	Tail/endpoint node id	Together with j identifies an edge between two nodes.
j	character / integer	Head/endpoint node id	Current hawkesNet kernels treat edges as undirected (order doesn’t matter).
time	numeric	Edge arrival time	Must be \(\ge\) both endpoint birth times in nodes (if provided).
...	any	Extra edge attributes	Carried through as edge attributes in the underlying network during fitting.

nodes

Column	Type	Meaning	Notes
id	character / integer	Node identifier	Must be unique within nodes. IDs used in edges$i/edges$j must match these.
time	numeric	Node birth/arrival time	Can be continuous or discrete. Must be comparable to edges$time.
role (optional)	character	Node role/type (e.g. "event", "perp")	Required for bipartite kernels (e.g. *_bip) if your mark model distinguishes node types.
...	any	Extra node attributes	Carried through as vertex attributes in the underlying network during fitting.

Creating events objects

make_events()

You can create events objects used for fitting by using the make_events() function.

Argument	What it is	What it does
nodes	data frame (optional)	Node arrivals (id, time, …). If omitted, births can be inferred from edges (see below).
edges	data frame (optional)	Edge arrivals (i, j, time, …).
allow_implicit_birth	logical	If TRUE and nodes is not supplied, infer node birth time as the first time the id appears in edges.
...	optional	Package may expose additional validation/behaviour flags (kept here to avoid duplicating implementation details in the docs).

Return value

An events object is a list with three data frames:

Component	Columns	Meaning
ev$times	event_id, t	Unique sorted times used as event indices.
ev$nodes	event_id, id, …	Node arrivals mapped onto event_id.
ev$edges	event_id, i, j, …	Edge arrivals mapped onto event_id.

Helpers

There are a number of helpers included in the package to make working with the events objects easier:

• create_net_from_events(ev) → Create an events object from an network object.
• create_events_from_net(net) → Create an network object from an events object.
• nodes_by_event(ev) → list of node-arrival data frames (one per event_id)
• edges_by_event(ev) → list of edge-arrival data frames (one per event_id)

See the actual docs (eg. ?hawkesNet::create_net_from_events) for more information on these.

Examples

Standard

nodes <- data.frame(
  id   = c("1", "2", "3"),
  time = c(0, 1, 2)
)
edges <- data.frame(
  i    = c("1", "1"),
  j    = c("2", "3"),
  time = c(1, 2)
)

ev <- make_events(nodes = nodes, edges = edges)

Implicit births from edges

edges_example <- data.frame(
  i    = c("1", "1"),
  j    = c("2", "3"),
  time = c(1, 2)
)

events_from_edges <- make_events(edges = edges_example, allow_implicit_birth = TRUE)

Node & edge attributes

nodes <- data.frame(
  id   = c("1", "2", "3"),
  time = c(0, 1, 2),
  role = c("event", "perp", "perp")
)
edges <- data.frame(
  i    = c("1", "1"),
  j    = c("2", "3"),
  time = c(1, 2),
  attribute = c("strong", "weak")
)

ev <- make_events(nodes = nodes, edges = edges)

ev$nodes

  event_id id  role
1        1  1 event
2        2  2  perp
3        3  3  perp

ev$edges

  event_id i j attribute
1        2 1 2    strong
2        3 1 3      weak