DPI (version 2025.11)

DPI_dag: Directed acyclic graphs (DAGs) via DPI exploratory analysis (causal discovery) for all significant partial rs.

Description

Directed acyclic graphs (DAGs) via DPI exploratory analysis (causal discovery) for all significant partial rs.

Usage

DPI_dag(
  data,
  k.covs = 1,
  n.sim = 1000,
  alpha = 0.05,
  bonf = FALSE,
  pseudoBF = FALSE,
  seed = NULL,
  progress,
  file = NULL,
  width = 6,
  height = 4,
  dpi = 500
)

Value

Return a data.frame (class dpi.dag) of DPI exploration results.

Arguments

data

A dataset with at least 3 variables.

k.covs

An integer vector (e.g., 1:10) of number of random covariates (simulating potential omitted variables) added to each simulation sample. Defaults to 1. For details, see DPI().

n.sim

Number of simulation samples. Defaults to 1000.

alpha

Significance level for computing the Significance score (0~1) based on p value of partial correlation between X and Y. Defaults to 0.05.

• Direction = R2.Y - R2.X

• Significance = 1 - tanh(p.beta.xy/alpha/2)

bonf

Bonferroni correction to control for false positive rates: alpha is divided by, and p values are multiplied by, the number of comparisons.

• Defaults to FALSE: No correction, suitable if you plan to test only one pair of variables.

• TRUE: Using k * (k - 1) / 2 (all pairs of variables) where k = length(data).

• A user-specified number of comparisons.

pseudoBF

Use normalized pseudo Bayes Factors sigmoid(log(PseudoBF10)) alternatively as the Significance score (0~1). Pseudo Bayes Factors are computed from p value of X-Y partial relationship and total sample size, using the transformation rules proposed by Wagenmakers (2022) tools:::Rd_expr_doi("10.31234/osf.io/egydq").

Defaults to FALSE because it makes less penalties for insignificant partial relationships between X and Y, see Examples in DPI() and online documentation.

seed

Random seed for replicable results. Defaults to NULL.

progress

Show progress bar. Defaults to TRUE (if length(k.covs) >= 5).

file

File name of saved plot (".png" or ".pdf").

width, height

Width and height (in inches) of saved plot. Defaults to 6 and 4.

dpi

Dots per inch (figure resolution). Defaults to 500.

See Also

S3method.network

DPI()

DPI_curve()

BNs_dag()

cor_net()

p_to_bf()

Examples

# partial correlation networks (undirected)
cor_net(airquality, "pcor")

# directed acyclic graphs (grey edge = insignificant DPI)
dpi.dag = DPI_dag(airquality, k.covs=c(1,3,5), seed=1)
print(dpi.dag, k=1)  # DAG with DPI(k=1)
print(dpi.dag, k=3)  # DAG with DPI(k=3)
print(dpi.dag, k=5)  # DAG with DPI(k=5)

# set edge labels and edge transparency
# (grey edge = insignificant DPI)
print(dpi.dag, k=5, show.label=FALSE, faded.dpi=TRUE)

# modify ggplot attributes
gg = plot(dpi.dag, k=5, show.label=FALSE, faded.dpi=TRUE)
gg + labs(title="DAG with DPI (k=5)")

# visualize DPIs of multiple paths
ggplot(dpi.dag$DPI, aes(x=k.cov, y=DPI)) +
  geom_ribbon(
    aes(ymin=Sim.LLCI, ymax=Sim.ULCI, fill=path),
        alpha=0.1) +
  geom_line(aes(color=path), linewidth=0.7) +
  geom_point(aes(color=path)) +
  geom_hline(yintercept=0, color="red",
             linetype="dashed") +
  scale_y_continuous(limits=c(NA, 0.5)) +
  labs(color="Directed Prediction",
       fill="Directed Prediction") +
  theme_classic()