Skip to contents

Extract causal relations from sentence(s) via a Hugging Face Space

Source: R/causal_sentences.R
causal_relations.Rd

Sends one or more input sentences to a public Gradio app hosted on Hugging Face (the lakens-causal-sentences Space), created based on code by Rasoul Norouzi, retrieves the result via Server-Sent Events (SSE), and returns a tidy data frame with one row per detected cause–effect relation.

Usage

causal_relations(
  sentence,
  rel_mode = "auto",
  rel_threshold = 0.5,
  cause_decision = "cls+span",
  timeout = 10,
  verbose = FALSE
)

Arguments

sentence

A character vector of one or more sentences to analyze for causal relations.

rel_mode

Relation extraction mode. Options are "auto" (default) or "neural_only".

rel_threshold

Numeric threshold (default 0.5) for deciding whether a relation is considered causal.

cause_decision

Strategy for cause/effect detection. Options: "cls_only", "span_only", or "cls+span" (default).

timeout

Maximum time (in seconds) to wait for the Hugging Face Space to return a result via SSE before aborting. Default is 10.

verbose

Logical; if TRUE, prints diagnostic information (URLs, status codes, event progression). Default FALSE.

Value

A base data.frame with columns:

  • sentence (character): the original input sentence,

  • causal (logical): whether the sentence is causal per the model,

  • cause (character): extracted cause span (or NA),

  • effect (character): extracted effect span (or NA).

Details

The function uses Gradio’s two-step queue API: (1) a POST request enqueues the job and returns an event_id; (2) a GET request streams text/event-stream frames until event: complete. Many Gradio apps emit a double-encoded completion payload of the form ["<final JSON string>"]. This function unwraps that to obtain the final JSON structure (an array of items containing causal and relations) before parsing.

If a sentence has no relations, the output includes one row with cause = NA, effect = NA, and the sentence’s causal flag (as returned by the model). For sentences with multiple relations, the function returns one row per relation.

References

Norouzi, R., Kleinberg, B., Vermunt, J. K., & van Lissa, C. J. (2025). Capturing causal claims: A fine-tuned text mining model for extracting causal sentences from social science papers. Research Synthesis Methods, 16(1), 139–156. https://doi.org/10.1017/rsm.2024.13

Hugging Face Model Card: rasoultilburg/SocioCausaNet https://huggingface.co/rasoultilburg/SocioCausaNet

Examples

# \donttest{
  # Single sentence
  df1 <- causal_relations("Smoking causes cancer")
  print(df1)
#>                sentence causal   cause effect
#> 1 Smoking causes cancer   TRUE smoking cancer

  # Multiple sentences (batch)
  df2 <- causal_relations(c("Insomnia causes depression.", "Rain leads to flooding."))
  print(df2)
#>                      sentence causal    cause     effect
#> 1 Insomnia causes depression.   TRUE insomnia depression
#> 2     Rain leads to flooding.   TRUE     rain   flooding

  # Custom parameters and verbose diagnostics
  df3 <- causal_relations(
    sentence = "Stress increases blood pressure.",
    rel_mode = "auto",
    rel_threshold = 0.4,
    cause_decision = "cls+span",
    timeout = 10,
    verbose = TRUE
  )
#> === Processing sentence 1/1 ===
#> [POST] https://lakens-causal-sentences.hf.space/gradio_api/call/predict
#> [POST] HTTP 200, 47 bytes
#> [GET/SSE] https://lakens-causal-sentences.hf.space/gradio_api/call/predict/9e45f8c8aab34270a281de6fd5b0cdca
#> [SSE] event: complete
#> [SSE] received complete payload
  print(df3)
#>                           sentence causal  cause         effect
#> 1 Stress increases blood pressure.   TRUE stress blood pressure
# }