causal_map()

Build the causal map from the relations and the names of their spans.

causal_map(
    relations: list[dict],
    names: dict,
    min_papers: int = 1,
    min_sentences: int = 2,
    min_share: float = MIN_SHARE,
) -> dict

Source: theoryminer/causal_map.py

Each node is a construct: a named group, or a thesaurus concept. Each edge is “cause node -> effect node”, with the number of papers, sentences and relations that claim it. Self-loops and two-way pairs get flags. A filter hides a weak edge, but deletes nothing: a hidden edge goes to “hidden” with its drop_reason. The function reads no file and loads no model.

Arguments

`relations`

The relations from causenet().

Values: a list of relation dicts. Each relation needs rel_id, doc_id, cause and effect; sent_id is used when it is there.
Default: none. Give the relations.

`names`

The names of the spans, made from the same relations.

Values: the result of label_groups() (a node is a group, named by its name), standardize_groups() (a node is the best concept of a group; groups with the same best concept share a node), or standardize_constructs() (a node is the best concept of a span). A group or span without a concept keeps its own node, under its own text.
Default: none. Give the names.

`min_papers`

Show an edge only when at least this many papers claim it.

Values: a whole number, 1 or more.
Default 1: show the edge whatever the number of papers. This also suits one long book.

`min_sentences`

Show an edge only when at least this many different sentences claim it.

Values: a whole number, 1 or more.
Default 2: hide the claims that only one sentence makes. Use 1 to show every edge.

`min_share`

The share of the papers that one side of a two-way pair (A -> B and B -> A) needs to be the main direction.

Values: a number above 0.5, up to 1.
Default 0.67: one side needs 2/3 of the papers. Then it is “dominant” and the other side is “minority”. Else both sides are “contested”.

Returns

A dict with the keys

key	meaning
`nodes`	{node_id: node}: label, members, as_cause, as_effect, n_sentences, n_papers, role (“cause only”, “effect only” or “cause and effect”) and shown
`edges`	the shown edges: edge_id, source, target, n_papers, n_sentences, n_relations, rel_ids, doc_ids, direction (“one-way”, “dominant”, “minority” or “contested”), reciprocal, self_loop and drop_reason (“”)
`hidden`	the hidden edges, with drop_reason “below_min_papers” or “below_min_sentences”
`relations`	{rel_id: relation}
`papers`	one dict per paper, {“doc_id”, “doi”, “title”}, from the relations; draw_map() shows them
`settings`	{“min_papers”, “min_sentences”, “min_share”}

Raises

ValueError: The relations are empty; names is empty or has an unknown shape; a span of a relation is not in names; or a setting is out of its range.

Example

>>> relations = [
...     {"rel_id": "r1", "sent_id": "s1", "doc_id": "p1", "cause": "job insecurity", "effect": "stress"},
...     {"rel_id": "r2", "sent_id": "s2", "doc_id": "p2", "cause": "fear of job loss", "effect": "anxiety"}]
>>> names = {0: {"central": "job insecurity", "members": ["job insecurity", "fear of job loss"],
...              "name": "job insecurity"},
...          1: {"central": "stress", "members": ["stress", "anxiety"], "name": "stress"}}
>>> cmap = causal_map(relations, names)
causal map: 2 nodes | 1 edges shown, 0 hidden | self-loops: 0 edges, 0 of 2 relations (0.0%) | two-way pairs: 0 (0 contested)
>>> edge = cmap["edges"][0]
>>> edge["source"], edge["target"], edge["n_papers"], edge["rel_ids"]
('g:0', 'g:1', 2, ['r1', 'r2'])

Keyboard shortcuts

theoryminer