Package {CausalLoopAnalytics}

Type: Package
Title: Data-Driven Causal Loop and Feedback Network Analysis
Version: 1.0.0
Description: Provides tools for constructing signed causal-loop models, discovering directed causal relationships from time-series data using Granger-style tests, identifying and classifying reinforcing and balancing feedback loops, quantifying loop strength, assessing loop stability by bootstrap resampling, calculating network centrality and leverage-point scores, comparing causal-loop models, and producing publication-ready base R visualizations and summaries. The package is domain-agnostic and can be used in human medicine, veterinary medicine, agriculture, epidemiology, ecology, public health, and One Health. Methods are based on Granger (1969) <doi:10.2307/1912791> and Efron (1979) <doi:10.1214/aos/1176344552>.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: stats, graphics
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
URL: https://github.com/vinodhpmd/CausalLoopAnalytics
BugReports: https://github.com/vinodhpmd/CausalLoopAnalytics/issues
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-09-11 14:21:34 UTC; m
Author: Vinodhkumar Obli Rajendran [aut, cre], Keerthi Aaradhana [aut]
Maintainer: Vinodhkumar Obli Rajendran <vinodhkumar.rajendran@gmail.com>
Repository: CRAN
Date/Publication: 2026-09-21 21:50:17 UTC

CausalLoopAnalytics: Data-Driven Causal Loop and Feedback Network Analysis

Description

Tools for constructing signed causal-loop models, discovering causal relationships from time-series data, identifying and classifying feedback loops, quantifying loop strength, assessing loop stability, analysing network structure, and identifying potential leverage points.

Author(s)

Maintainer: Vinodhkumar Obli Rajendran vinodhkumar.rajendran@gmail.com

Authors:

See Also

Useful links:

Description

Adds a directed signed link between two variables in a causal-loop diagram.

Usage

add_link(model, source, target, polarity = "+", weight = 1)

Arguments

model

A cld object.

source

Character string giving the source variable.

target

Character string giving the target variable.

polarity

Link polarity, specified as "+" or "-".

weight

Numeric weight assigned to the link. Defaults to 1.

Value

An updated object of class cld containing the new directed signed link.

Examples

model <- create_cld(c("A", "B"))
model <- add_link(model, "A", "B", polarity = "+")
model

Add a variable to a causal-loop diagram

Description

Adds a new variable (node) to an existing causal-loop diagram.

Usage

add_variable(model, name)

Arguments

model

A cld object.

name

Character string giving the variable name.

Value

An updated object of class cld containing the newly added variable.

Examples

model <- create_cld()
model <- add_variable(model, "Population")
model

Extract the causal adjacency matrix

Description

Returns the signed adjacency matrix representing the causal relationships in a causal-loop diagram.

Usage

causal_matrix(model)

Arguments

model

A cld object.

Value

A numeric matrix containing the signed causal adjacency matrix. Rows represent source variables and columns represent target variables. Positive and negative entries represent positive and negative causal relationships, respectively, while zero indicates no direct link.

Examples

model <- create_cld(c("A", "B"))
model <- add_link(model, "A", "B", polarity = "+", weight = 2)
causal_matrix(model)

Classify feedback loops as reinforcing or balancing

Description

Classify feedback loops as reinforcing or balancing

Usage

classify_loops(model, loops = NULL)

Arguments

model

A cld object.

loops

Optional output from find_feedback_loops().

Value

A data frame with loop polarity and type.

Compare two causal-loop models

Description

Compare two causal-loop models

Usage

compare_cld(x, y)

Arguments

x, y

cld objects.

Value

A structured comparison.

Create a causal-loop diagram

Description

Creates an empty causal-loop diagram or initializes a causal-loop diagram with a specified set of variables.

Usage

create_cld(nodes = character())

Arguments

nodes

Character vector of variable names. Defaults to an empty character vector.

Value

An object of class cld containing the variable names, a signed adjacency matrix, and a data frame describing the causal links.

Examples

model <- create_cld(c("A", "B", "C"))
model

Find unique directed feedback loops

Description

Find unique directed feedback loops

Usage

find_feedback_loops(
  model,
  max_length = length(model$nodes),
  include_self_loops = FALSE
)

Arguments

model

A cld object.

max_length

Maximum loop length; defaults to number of nodes.

include_self_loops

Whether to include one-node loops.

Value

A list of loop variable vectors.

Estimate pairwise Granger-style causal edges

Description

Estimate pairwise Granger-style causal edges

Usage

granger_edges(data, lag = 1, alpha = 0.05)

Arguments

data

Numeric time-series data frame/matrix.

lag

Maximum lag (1 by default).

alpha

Significance threshold.

Details

For each ordered pair X -> Y, the function compares a restricted model containing lags of Y with an unrestricted model containing lags of Y and X. The reported polarity is the sign of the sum of coefficients for the added X lags. This is predictive temporal causality, not proof of mechanistic causation.

Value

Edge table with direction, sign, coefficient and p-value.

Identify potential leverage points from network and feedback structure

Description

Identify potential leverage points from network and feedback structure

Usage

identify_leverage_points(
  model,
  weights = c(centrality = 0.4, loops = 0.3, strength = 0.3)
)

Arguments

model

A cld object.

weights

Optional named weights for centrality, loop participation and loop strength.

Value

Ranked data frame.

Infer a causal-loop network from time-series data

Description

Discovers directed temporal relationships using Granger-style tests and constructs a signed causal-loop model from the resulting edges.

Usage

infer_causal_network(data, lag = 1, alpha = 0.05)

Arguments

data

A numeric data frame or matrix containing time-series variables.

lag

Maximum lag used for the Granger-style test.

alpha

Significance threshold for retaining causal edges.

Details

This function uses predictive temporal relationships to construct a signed causal-loop diagram. A detected Granger-style relationship should not be interpreted as proof of mechanistic causation.

Value

A cld object containing the inferred causal network and causal edge information.

Simulate a structural causal intervention by propagating effects through paths

Description

Simulate a structural causal intervention by propagating effects through paths

Usage

intervention_analysis(model, variable, change = 1, steps = length(model$nodes))

Arguments

model

A cld object.

variable

Intervention variable.

change

Numeric change applied to the intervention variable.

steps

Number of propagation steps.

Value

Data frame of propagated signed effects.

Bootstrap stability of feedback loops

Description

Bootstrap stability of feedback loops

Usage

loop_stability(model, B = 200, threshold = 0.5, seed = NULL)

Arguments

model

A cld object.

B

Number of bootstrap resamples.

threshold

Probability threshold for reporting stable loops.

seed

Optional random seed.

Value

Data frame with loop stability proportions.

Calculate multiplicative feedback-loop strength

Description

Calculate multiplicative feedback-loop strength

Usage

loop_strength(model, loops = NULL)

Arguments

model

A cld object.

loops

Optional loops.

Value

Data frame with edge and loop strength.

Summarize a signed causal network

Description

Summarize a signed causal network

Usage

network_summary(model)

Arguments

model

A cld object.

Value

Data frame of node-level metrics.

Plot a signed causal-loop diagram

Description

Produces a base R plot of a signed causal-loop diagram. Variables are displayed as nodes and directed causal relationships are displayed as arrows with their corresponding polarity.

Usage

plot_cld(
  model,
  vertex.cex = 0.85,
  edge.cex = 0.75,
  show_weights = FALSE,
  seed = 1,
  main = "Causal Loop Diagram"
)

Arguments

model

A cld object.

vertex.cex

Numeric value controlling node text size.

edge.cex

Numeric value controlling edge-label size.

show_weights

Logical; if TRUE, edge weights are displayed together with their polarity.

seed

Integer seed used to obtain a reproducible circular layout.

main

Character string giving the plot title.

Value

A numeric matrix of node coordinates, returned invisibly. Rows correspond to variables in the causal-loop model and the two columns contain the x- and y-coordinates used for plotting. If the model contains no variables, the function returns NULL invisibly.

Examples

model <- create_cld(c("A", "B"))
model <- add_link(model, "A", "B", polarity = "+")
plot_cld(model)

Plot feedback loop strength

Description

Produces a base R horizontal bar plot summarizing the strength of identified feedback loops.

Usage

plot_loops(model, main = "Feedback Loop Strength")

Arguments

model

A cld object.

main

Character string giving the plot title.

Value

A data frame containing the identified feedback loops and their classifications and strengths, returned invisibly. The columns include loop, type, strength, and length. If no feedback loops are detected, an empty data frame is returned invisibly.

Examples

model <- create_cld(c("A", "B"))
model <- add_link(model, "A", "B", polarity = "+")
model <- add_link(model, "B", "A", polarity = "+")
plot_loops(model)

Prepare a numeric time-series data set

Description

Prepare a numeric time-series data set

Usage

prepare_data(data, scale = FALSE)

Arguments

data

Data frame or numeric matrix.

scale

Logical; standardize columns.

Value

Numeric matrix with complete rows.

Description

Removes a directed link between two variables from a causal-loop diagram.

Usage

remove_link(model, source, target)

Arguments

model

A cld object.

source

Character string giving the source variable.

target

Character string giving the target variable.

Value

An updated object of class cld with the specified directed link removed.

Examples

model <- create_cld(c("A", "B"))
model <- add_link(model, "A", "B", polarity = "+")
model <- remove_link(model, "A", "B")
model

Remove a variable from a causal-loop diagram

Description

Removes a variable and all associated links from a causal-loop diagram.

Usage

remove_variable(model, name)

Arguments

model

A cld object.

name

Character string giving the variable to remove.

Value

An updated object of class cld with the specified variable and its associated links removed.

Examples

model <- create_cld(c("A", "B", "C"))
model <- remove_variable(model, "B")
model

Summarize a causal-loop model

Description

Summarize a causal-loop model

Usage

summary_causal_loop(model)

Arguments

model

A cld object.

Value

A concise list of model diagnostics.

Validate a causal-loop model

Description

Checks the structural validity of a causal-loop model and reports structural characteristics such as isolated variables, source-only variables, sink-only variables, self-loops, and links.

Usage

validate_cld(model)

Arguments

model

A cld object.

Value

A list containing validation status and structural summary information. The list contains valid, n_nodes, n_links, isolated, source_only, sink_only, self_loops, and missing_polarity.

Examples

model <- create_cld(c("A", "B"))
model <- add_link(model, "A", "B", polarity = "+")
validate_cld(model)