| Title: | Data-Driven Causal Loop and Feedback Network Analysis |
|---|---|
| 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>. |
| Authors: | Vinodhkumar Obli Rajendran [aut, cre], Keerthi Aaradhana [aut] |
| Maintainer: | Vinodhkumar Obli Rajendran <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.0 |
| Built: | 2026-09-22 00:19:32 UTC |
| Source: | https://github.com/cran/CausalLoopAnalytics |
Adds a directed signed link between two variables in a causal-loop diagram.
add_link(model, source, target, polarity = "+", weight = 1)add_link(model, source, target, polarity = "+", weight = 1)
model |
A |
source |
Character string giving the source variable. |
target |
Character string giving the target variable. |
polarity |
Link polarity, specified as |
weight |
Numeric weight assigned to the link. Defaults to |
An updated object of class cld containing the new directed signed link.
model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") modelmodel <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") model
Adds a new variable (node) to an existing causal-loop diagram.
add_variable(model, name)add_variable(model, name)
model |
A |
name |
Character string giving the variable name. |
An updated object of class cld containing the newly added variable.
model <- create_cld() model <- add_variable(model, "Population") modelmodel <- create_cld() model <- add_variable(model, "Population") model
Returns the signed adjacency matrix representing the causal relationships in a causal-loop diagram.
causal_matrix(model)causal_matrix(model)
model |
A |
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.
model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+", weight = 2) causal_matrix(model)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
classify_loops(model, loops = NULL)classify_loops(model, loops = NULL)
model |
A |
loops |
Optional output from |
A data frame with loop polarity and type.
Compare two causal-loop models
compare_cld(x, y)compare_cld(x, y)
x, y
|
|
A structured comparison.
Creates an empty causal-loop diagram or initializes a causal-loop diagram with a specified set of variables.
create_cld(nodes = character())create_cld(nodes = character())
nodes |
Character vector of variable names. Defaults to an empty character vector. |
An object of class cld containing the variable names, a signed
adjacency matrix, and a data frame describing the causal links.
model <- create_cld(c("A", "B", "C")) modelmodel <- create_cld(c("A", "B", "C")) model
Find unique directed feedback loops
find_feedback_loops( model, max_length = length(model$nodes), include_self_loops = FALSE )find_feedback_loops( model, max_length = length(model$nodes), include_self_loops = FALSE )
model |
A |
max_length |
Maximum loop length; defaults to number of nodes. |
include_self_loops |
Whether to include one-node loops. |
A list of loop variable vectors.
Estimate pairwise Granger-style causal edges
granger_edges(data, lag = 1, alpha = 0.05)granger_edges(data, lag = 1, alpha = 0.05)
data |
Numeric time-series data frame/matrix. |
lag |
Maximum lag (1 by default). |
alpha |
Significance threshold. |
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.
Edge table with direction, sign, coefficient and p-value.
Identify potential leverage points from network and feedback structure
identify_leverage_points( model, weights = c(centrality = 0.4, loops = 0.3, strength = 0.3) )identify_leverage_points( model, weights = c(centrality = 0.4, loops = 0.3, strength = 0.3) )
model |
A |
weights |
Optional named weights for centrality, loop participation and loop strength. |
Ranked data frame.
Discovers directed temporal relationships using Granger-style tests and constructs a signed causal-loop model from the resulting edges.
infer_causal_network(data, lag = 1, alpha = 0.05)infer_causal_network(data, lag = 1, alpha = 0.05)
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. |
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.
A cld object containing the inferred causal network and
causal edge information.
Simulate a structural causal intervention by propagating effects through paths
intervention_analysis(model, variable, change = 1, steps = length(model$nodes))intervention_analysis(model, variable, change = 1, steps = length(model$nodes))
model |
A |
variable |
Intervention variable. |
change |
Numeric change applied to the intervention variable. |
steps |
Number of propagation steps. |
Data frame of propagated signed effects.
Bootstrap stability of feedback loops
loop_stability(model, B = 200, threshold = 0.5, seed = NULL)loop_stability(model, B = 200, threshold = 0.5, seed = NULL)
model |
A |
B |
Number of bootstrap resamples. |
threshold |
Probability threshold for reporting stable loops. |
seed |
Optional random seed. |
Data frame with loop stability proportions.
Calculate multiplicative feedback-loop strength
loop_strength(model, loops = NULL)loop_strength(model, loops = NULL)
model |
A |
loops |
Optional loops. |
Data frame with edge and loop strength.
Summarize a signed causal network
network_summary(model)network_summary(model)
model |
A |
Data frame of node-level metrics.
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.
plot_cld( model, vertex.cex = 0.85, edge.cex = 0.75, show_weights = FALSE, seed = 1, main = "Causal Loop Diagram" )plot_cld( model, vertex.cex = 0.85, edge.cex = 0.75, show_weights = FALSE, seed = 1, main = "Causal Loop Diagram" )
model |
A |
vertex.cex |
Numeric value controlling node text size. |
edge.cex |
Numeric value controlling edge-label size. |
show_weights |
Logical; if |
seed |
Integer seed used to obtain a reproducible circular layout. |
main |
Character string giving the plot title. |
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.
model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") plot_cld(model)model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") plot_cld(model)
Produces a base R horizontal bar plot summarizing the strength of identified feedback loops.
plot_loops(model, main = "Feedback Loop Strength")plot_loops(model, main = "Feedback Loop Strength")
model |
A |
main |
Character string giving the plot title. |
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.
model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") model <- add_link(model, "B", "A", polarity = "+") plot_loops(model)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
prepare_data(data, scale = FALSE)prepare_data(data, scale = FALSE)
data |
Data frame or numeric matrix. |
scale |
Logical; standardize columns. |
Numeric matrix with complete rows.
Removes a directed link between two variables from a causal-loop diagram.
remove_link(model, source, target)remove_link(model, source, target)
model |
A |
source |
Character string giving the source variable. |
target |
Character string giving the target variable. |
An updated object of class cld with the specified directed link removed.
model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") model <- remove_link(model, "A", "B") modelmodel <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") model <- remove_link(model, "A", "B") model
Removes a variable and all associated links from a causal-loop diagram.
remove_variable(model, name)remove_variable(model, name)
model |
A |
name |
Character string giving the variable to remove. |
An updated object of class cld with the specified variable and its
associated links removed.
model <- create_cld(c("A", "B", "C")) model <- remove_variable(model, "B") modelmodel <- create_cld(c("A", "B", "C")) model <- remove_variable(model, "B") model
Summarize a causal-loop model
summary_causal_loop(model)summary_causal_loop(model)
model |
A |
A concise list of model diagnostics.
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.
validate_cld(model)validate_cld(model)
model |
A |
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.
model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") validate_cld(model)model <- create_cld(c("A", "B")) model <- add_link(model, "A", "B", polarity = "+") validate_cld(model)