activity_heatmap: Generate a character by story-chunk matrix for analysing...

In pj398/charinet: A Package for Character Interaction Network Analysis

Generate a character by story-chunk matrix for analysing character activity by story chunks.

Description

This function calculates the number of interactions initated by each character within each story chunk. Story chunks could be scenes, chapters, or some other arbitrary division of the event list into temporal segments such as quartiles or deciles. This produces a character-by-story-chunk matrix which can be used to generate a heatmap of character activity over the course of a narrative.

For pre-defined story chunks (e.g. scenes or chapters), the user must specify (via story_chunk_col) a column in the event list which represents a variable indexing the chunk ID of each interaction. Alternatively, the function can automatically chunk the event list into equally-sized segments such as quartiles using the n_chunks argument.

Usage

activity_heatmap(
  event_list,
  char_names = NULL,
  n_chunks = NULL,
  story_chunk_col = NULL,
  from = 3
)

Arguments

event_list	An event list containing the time-ordered interactions. The function expects a particular format (described in detail elsewhere in the package documentation) wherein each row is an event, and the event list contains at least a column indicating the ID of the sending character, followed by columns containing dummy variables for each character which take the value 1 if that character is a target of the interaction, and 0 otherwise.
char_names	An optional vector of character names to be used to label the rows of the matrix returned by the function. This is useful when the sender ID column contains the numeric IDs of characters rather than the character names. If specified, this vector must be of equal length to the number of unique characters in the event list, and must be ordered by character ID number. If not supplied, names will be assigned based on how character names appear in the event list.
n_chunks	If a numeric value is passed to this argument, the event list will be "chunked" into that many equally-sized segments. This will override the story_chunk_col argument which is for specifying user-defined story chunk variables.
story_chunk_col	The position of the column in the input event_list which indexes the events by story chunk. This argument will be ignored unless n_chunks = NULL.
from	The position of the column in the input event_list which indexes the event by the sender ID (e.g. for dialogue data, this will be the speaker ID column).

Value

A matrix is returned, with each row corresponding to a character and each column corresponding to a story chunk. The value of cell [i, j] is the number of interactions sent by character i in chunk j.

Examples

tfa <- movienetdata::starwars_tfa
my_heatmap <- activity_heatmap(event_list = tfa$event_list,
                            char_names = tfa$node_list$char_name,
                            story_chunk_col = 2,
                            from = 3)
# How many times does character 5 speak in scene 6?
my_heatmap[5, 6]

pj398/charinet documentation built on May 2, 2024, 10:28 p.m.