| 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:
Vinodhkumar Obli Rajendran vinodhkumar.rajendran@gmail.com
Keerthi Aaradhana vkeerthi1817@gmail.com
See Also
Useful links:
Report bugs at https://github.com/vinodhpmd/CausalLoopAnalytics/issues
Add a directed causal link
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 |
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 |
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 |
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 |
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 |
loops |
Optional output from |
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 |
|
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
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.
Remove a directed causal link
Description
Removes a directed link between two variables from a causal-loop diagram.
Usage
remove_link(model, source, target)
Arguments
model |
A |
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 |
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 |
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 |
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)