causenet()

Find the cause -> effect pairs in the sentences.

causenet(
    sentences: list,
    threshold: float = 0.8,
    mode: str = 'neural',
    decision: str = 'span_only',
    batch_size: int = 64,
    device: str = 'auto',
    avoid_ambiguous: bool = True,
) -> list[dict]

Source: theoryminer/causenet.py

The model rasoultilburg/SocioCausaNet reads one sentence at a time. It decides whether the sentence is causal, marks the cause spans and the effect spans, and links each cause to each effect. The function then repairs each span with tidy_span(), which removes no word, and gives each relation the path back to its sentence. The first call loads the model (about 440 MB, downloaded on first use). The function writes no file. Keep the result in a variable: a large corpus takes long on a CPU.

Arguments

sentences

The sentences to read.

• Values: the rows of harvest()[“sentences”] (the function reads “clean”, “sent_id”, “doc_id” and “page”), or a plain list of strings (then doc_id is “input”, page is 0, and sent_id is “s0000”, “s0001”, …).
• Default: none. Give the sentences.

threshold

The score that a cause -> effect pair needs to become a relation.

• Values: a number from 0 to 1. A lower value gives more relations and more errors.
• Default 0.8: keep a pair with a score of 0.8 or more.

mode

How the model links each cause to each effect.

• Values: “neural”: the model scores every cause -> effect pair, and threshold decides. “auto”: when a sentence has only one cause or only one effect, every pair is kept without a score; else as “neural”.
• Default “neural”.

decision

The rule that makes a sentence causal.

• Values: “span_only”: the sentence has a cause span and an effect span. “cls+span”: also the sentence classifier must say causal (the default before 0.2.0). “cls_only”: only the sentence classifier decides.
• Default “span_only”.

batch_size

The number of sentences in one model call.

• Values: a whole number, 1 or more. On a GPU a larger value is often faster. Lower it after a GPU “out of memory” error.
• Default 64.

device

Where the model runs.

• Values: “auto”, “cpu”, “cuda” (an NVIDIA GPU) or “mps” (the GPU of an Apple Silicon Mac). If the model fails on an Apple GPU, it moves to the CPU and the run goes on.
• Default "auto": an NVIDIA GPU when torch sees one, else the Apple GPU, else the CPU.

avoid_ambiguous

Whether to skip a relation whose cause or effect only points to another sentence: “this”, “it”, “such things” (the rule is harmonizer.spans.is_vague_span).

• Values: True or False.
• Default True: skip these relations. The summary prints their count and examples. False keeps every relation.

Returns

A list of dicts, one per relation, with the keys

Raises

• ValueError: An unknown mode, decision or device, a threshold outside 0 to 1, a batch_size below 1, or a device that torch cannot see (“cuda” without an NVIDIA GPU).

Example

>>> relations = causenet(["Social support increases feelings of security and well-being."])
>>> [(r["cause"], r["effect"]) for r in relations]
[('social support', 'feelings of security and well-being')]