Package: tgm
tgm - Temporal Graph MotifsPython code to look for temporal motifs, namely temporal K_{2,h} motifs, in a graph or network ofevents.We assume that events are time indexed and grouped under someroot eventwhich happens first via a tree structure. Most styles of threaded conversation (e.g. tweets and retweets, reddit comments, email chains) can be described in this format.Data FormatThe data consists of temporal 4- or 5-tuples:(event_id, actor_id, time, root_id)(event_id, actor_id, time, root_id, parent_id)Where:event_id: is a unique id for each eventactor_id: is the id of the actor/user generating the eventtime: in UTC formatroot_id: is the id of the root event that this event_id is part ofparent_id: is the id of the parent of this event when events with same root_id have a tree structureAssumption:event_id == root_id for theroot event; in this case, parent_id is meaninglessall events with same root_id can not happen before the root event itself (where event_id == root_id)if "parent_id" are used, the parent event can not happen before one of its child eventTemporal K_{2,h} motifsSuch motifs are parametrized by 3 values:dt: the reaction time, in secondsdT: the repetition time, in secondsh: the number of distinct root events forming the motifWe distinguish 2 families of motifs:(1) root-based motifsA temporal K_{2,h} motifs given (dt, dT) occurs when:an actor A submits aroot eventand a different actor B sumbits an event under that root event (i.e. same root_id) withindtseconds (reactiontime)the above scenario happenshtimes, for h distinct root events, all withindTseconds (repetitiontime)(2) hop-based motifsA temporal K_{2,h} motifs given (dt, dT) occurs when:an actor A submits an event under a root_event (the event needs not be the root event but it can be) with someevent_id, and a different actor B sumbits another event such that itsparent_id == event_id, withindtseconds (reactiontime)the above scenario happenshtimes, in h distinct root events, all withindTseconds (repetitiontime)Finding K_{2,h} motifsThe functionK2his called to find temporal motifs. When called first, a DataFrame with the required columns needs to be passed (see details below). If the function is called several times for the same dataset (for example, trying different dt and dT parameters), then some speed-up can be achieved as we illustrate below.Parameters:mode: 'root' for root-based motifs, or 'hop' for hop-based motifsdf: pandas DataFrame with the required columns:event_id: unique id for each eventactor_id: actor/user idtime: in seconds, typically UTCroot_id: id of the root event that this event_id is part ofparent_id: id of the parent event, only required if mode == 'hop'dt: reaction time for the motifs, in secondsdT: repetition time for the motifs, in secondsh: the 'h' in K2h; the number of different root_id's in the motifs (>=2)bg: bipartite graph obtained from a previous call of the 'K2h' function with the same dataframe 'df'; if supplied, 'df' is not required; this will speed-up the computationverbose: if set, return the tuples of root_id's for each K_{2,h} motif found (default=False)return_df: if set, also output the results as a pandas DataFrame (default=False)return_bg: if set, output the bipartite graph that can be re-used for faster subsequent runs of 'K2h' (default=True)Result are pairs of actors with the number of temporal motifs they share and if 'verbose' is set, the list of tuples of root_id's they share.Output:self.graph: igraph Graph with the K2h motifs (nodes=actors, edges=K_{2,h} motifs)self.df: pandas DataFrame with K2h motifs (optional, default=False)self.bg: igraph multi-bipartite Graph; can be used for faster subsequent runs of 'K2h' (optional, default=True)For the DataFrame output, we also group the actors into weakly connected components, returning the component number for each one.For the Graph output, the edges aredirectedfrom the non-root actor to the root actor. Edge weights indicate the number of motifs. There are no loops.