Implements the hypergraph conversation model from this paper.

Example usage: Hypergraph creation and feature extraction, visualization and interpretation on a subsample of Reddit.

Example usage: Using Hyperconvo features to predict conversation growth on Reddit in a paired setting.

class convokit.hyperconvo.hyperconvo.HyperConvo(prefix_len: int = 10, min_convo_len: int = 10, vector_name: str = 'hyperconvo', invalid_val: float = numpy.nan)

Encapsulates computation of hypergraph features for a particular corpus.

fit_transform() retrieves features from the corpus conversational threads using retrieve_feats, and stores it in the corpus’s conversations’ meta field under the key “hyperconvo”

Either use the features directly, or use the other transformers, threadEmbedder (https://convokit.cornell.edu/documentation/threadEmbedder.html) or communityEmbedder (https://convokit.cornell.edu/documentation/communityEmbedder.html) to embed threads or communities respectively in a low-dimensional space for further analysis or visualization.

As features, we compute the degree distribution statistics from Table 4 of http://www.cs.cornell.edu/~cristian/Patterns_of_participant_interactions.html, for both a whole conversation and its midthread, and for indegree and outdegree distributions of C->C, C->c and c->c edges, as in the paper. We also compute the presence and count of each motif type specified in Fig 2. However, we do not include features making use of reaction edges, due to our inability to release the Facebook data used in the paper (which reaction edges are most naturally suited for). In particular, we do not include edge distribution statistics from Table 4, as these rely on the presence of reaction edges. We hope to implement a more general version of these reaction features in an upcoming release.

  • prefix_len – Use the first [prefix_len] utterances of each conversation to construct the hypergraph

  • min_convo_len – Only consider conversations of at least this length

  • vector_name – feature name to store hyperconvo features under

  • invalid_val – value to use for invalid hyperconvo features, default is np.nan

retrieve_feats(corpus: convokit.model.corpus.Corpus, selector: Callable[[convokit.model.conversation.Conversation], bool] = <function HyperConvo.<lambda>>) → Dict[str, Dict]

Retrieve all hypergraph features for a given corpus (viewed as a set of conversation threads).

See init() for further documentation.

  • corpus – target Corpus

  • selector – (lambda) function selecting the Conversations that features should be computed for.


A dictionary from a thread root id to its stats dictionary, which is a dictionary from feature names to feature values. For degree-related features specifically.

transform(corpus: convokit.model.corpus.Corpus, selector: Optional[Callable[[convokit.model.conversation.Conversation], bool]] = <function HyperConvo.<lambda>>) → convokit.model.corpus.Corpus

Retrieves features from the Corpus Conversations using retrieve_feats() and annotates Conversations with this feature set

  • corpus – Corpus object to retrieve feature information from

  • selector – a (lambda) function that takes a Conversation and returns True / False; function selects conversations to be annotated with hypergraph features. By default, all conversations will be annotated.


corpus with conversations having a new meta field with the specified feature name containing the stats generated by retrieve_feats().

class convokit.hyperconvo.hypergraph.Hypergraph

Represents a hypergraph, consisting of nodes, directed edges, hypernodes (each of which is a set of nodes) and hyperedges (directed edges from hypernodes to hypernodes). Contains functionality to extract motifs from hypergraphs (Fig 2 of http://www.cs.cornell.edu/~cristian/Patterns_of_participant_interactions.html)

dyadic_interaction_motifs() → List[Tuple]

List of tuples of form (C1, C2, C1->C2, C2->C1) as in paper

external_reciprocity_motifs() → List[Tuple]

List of tuples of form (C3, c2, c1, C3->c2, c2->c1) as in paper

incoming_triad_motifs() → List[Tuple]

List of tuples of form (C1, C2, C3, C2->C1, C3->C1) as in paper

outgoing_triad_motifs() → List[Tuple]

List of tuples of form (C1, C2, C3, C1->C2, C1->C3) as in paper

reciprocity_motifs() → List[Tuple]

List of tuples of form (C1, c1, c2, C1->c2, c2->c1) as in paper