% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.calib.R, R/plot.incl.R, R/plot.theory.R,
%   R/qcaERT-plots.R
\name{qcaERT_plots}
\alias{qcaERT_plots}
\alias{plot.calib_test}
\alias{plot.incl_test}
\alias{plot.theory_test}
\title{Plot and chart qcaERT results}
\usage{
\method{plot}{calib_test}(
  x,
  type = c("interval", "heatmap", "trace"),
  sets = NULL,
  roles = NULL,
  anchors = NULL,
  directions = c("lower", "upper"),
  stop_reason = NULL,
  changed_types = NULL,
  solution_type = NULL,
  solution = NULL,
  monitored_solutions = NULL,
  metric = c("raw", "pct", "steps"),
  value = c("delta", "last_safe", "failing"),
  abs_delta = FALSE,
  cell = c("anchor_direction", "anchor"),
  show_text = FALSE,
  set = NULL,
  anchor = NULL,
  direction = NULL,
  show_stop = TRUE,
  order_sets = c("input", "most_sensitive", "least_sensitive"),
  legend = TRUE,
  theme = .plot_theme(),
  ...
)

\method{plot}{incl_test}(
  x,
  type = c("interval", "trace"),
  directions = c("lower", "upper"),
  stop_reason = NULL,
  changed_types = NULL,
  solution_type = NULL,
  solution = NULL,
  monitored_solutions = NULL,
  i_mode = NULL,
  direction = NULL,
  show_stop = TRUE,
  legend = TRUE,
  theme = .plot_theme(),
  ...
)

\method{plot}{theory_test}(
  x,
  solution_type = NULL,
  intermediate_branch = NULL,
  show_labels = TRUE,
  label_line = TRUE,
  label_line_alpha = 0.45,
  label_line_width = 0.35,
  point_size = 3.5,
  text_size = 3.5,
  label_nudge_x = 0.008,
  label_nudge_y = 0.006,
  legend = TRUE,
  theme = .plot_theme(),
  ...
)
}
\arguments{
\item{x}{An \code{incl_test} object returned by \code{\link[=incl.test]{incl.test()}}, a \code{calib_test}
object returned by \code{\link[=calib.test]{calib.test()}}, or a \code{theory_test} object returned by
\code{\link[=theory.test]{theory.test()}}.}

\item{type}{Plot type. \code{incl_test} supports \code{"interval"} and \code{"trace"}.
\code{calib_test} supports \code{"interval"}, \code{"heatmap"}, and \code{"trace"}.
\code{theory_test} has one consistency-coverage plot and does not use \code{type}.}

\item{sets}{For \code{calib_test}, optional character vector selecting calibrated
sets.}

\item{roles}{For \code{calib_test}, optional character vector selecting set
roles. Supported values are \code{"condition"} and \code{"outcome"}.}

\item{anchors}{For \code{calib_test}, optional character vector selecting
calibration anchors. Supported anchors are taken from the result object and
may include crisp (\code{"T"}), fuzzy direct three-threshold (\code{"E"}, \code{"C"},
\code{"I"}), fuzzy direct six-threshold (\code{"E1"}, \code{"C1"}, \code{"I1"}, \code{"I2"},
\code{"C2"}, \code{"E2"}), or fuzzy indirect (\code{"T1"}, \code{"T2"}, ...) anchors.}

\item{directions}{Character vector selecting lower and/or upper searches.}

\item{stop_reason}{Optional character vector used to filter diagnostic rows
by stop reason before plotting.}

\item{changed_types}{Optional solution-type filter applied to comma-coded
\code{changed_types} diagnostic values. Accepted tokens follow the common
qcaERT solution-type conventions: \code{"con"}/\code{"conservative"},
\code{"par"}/\code{"parsimonious"}, and \code{"int"}/\code{"intermediate"}.}

\item{solution_type}{Solution type to plot. Required when more than one
solution type is present. Accepted values follow the common qcaERT
solution-type conventions, excluding \code{"all"}.}

\item{solution}{Reserved. Plot methods do not accept \code{solution}; use
\code{solution_type}.}

\item{monitored_solutions}{Reserved. Plot methods do not accept
\code{monitored_solutions}; use \code{solution_type}.}

\item{metric}{For \code{calib_test} heatmaps, the quantity used for the fill
color: \code{"raw"}, \code{"pct"}, or \code{"steps"}.}

\item{value}{For \code{calib_test} heatmaps with \code{metric = "raw"}, the raw
threshold value to show: \code{"delta"}, \code{"last_safe"}, or \code{"failing"}.}

\item{abs_delta}{Logical. If \code{TRUE}, heatmaps using raw or percentage deltas
display absolute values.}

\item{cell}{For \code{calib_test} heatmaps, whether cells are split by
anchor-direction path (\code{"anchor_direction"}) or by anchor only
(\code{"anchor"}).}

\item{show_text}{Logical. If \code{TRUE}, add rounded heatmap values as text.}

\item{set}{For \code{calib_test} trace plots, the single calibrated set to plot.}

\item{anchor}{For \code{calib_test} trace plots, the single calibration anchor to
plot.}

\item{direction}{For \code{type = "trace"}, the single search direction to plot:
\code{"lower"} or \code{"upper"}.}

\item{show_stop}{Logical. If \code{TRUE}, draw reference lines for baseline and,
when present, first-failing values.}

\item{order_sets}{For \code{calib_test}, set ordering in interval and heatmap
views. \code{"input"} preserves result order; \code{"most_sensitive"} and
\code{"least_sensitive"} order by the smallest solution-changing percentage
delta when available.}

\item{legend}{Logical. If \code{FALSE}, hide the plot legend.}

\item{theme}{A ggplot2 theme object added to the plot.}

\item{...}{Additional graphical arguments forwarded to the primary ggplot2
geometry.}

\item{i_mode}{For \code{incl_test}, optional filter applied to the \code{i_mode}
diagnostic column. Accepted values are \code{"all"} and \code{"C1P1"}.}

\item{intermediate_branch}{For \code{theory_test} intermediate plots, the
intermediate branch to plot when more than one branch is present.}

\item{show_labels}{For \code{theory_test}, logical. If \code{TRUE}, print theory names
next to their consistency/coverage points.}

\item{label_line}{For \code{theory_test}, logical. If \code{TRUE}, draw a line from
each consistency/coverage point to its theory-name label.}

\item{label_line_alpha}{For \code{theory_test}, transparency of label connector
lines.}

\item{label_line_width}{For \code{theory_test}, width of label connector lines.}

\item{point_size}{For \code{theory_test}, point size.}

\item{text_size}{For \code{theory_test}, theory-name label size.}

\item{label_nudge_x}{For \code{theory_test}, horizontal nudge for theory-name
labels.}

\item{label_nudge_y}{For \code{theory_test}, vertical nudge for theory-name
labels.}
}
\value{
A ggplot object.
}
\description{
Plot methods provide visual inspection helpers for qcaERT result objects.
They are simplified views of the existing result object: the
detailed \code{diagnostics} table supplies the interval and heatmap views, while
the path-level trace components supply trace views. \code{\link[=sol.chart]{sol.chart()}} provides a
matching visual display for \code{\link[=sol.df]{sol.df()}} solution tables.
}
\details{
Plotting is optional. The qcaERT analysis functions do not require
\code{ggplot2}, but these methods do.
}
\section{Plot Types}{

For \code{incl_test}, \code{"interval"} shows the baseline inclusion cutoff and the
lower/upper last-safe values. \code{"trace"} shows the stepwise path for one
search direction.

For \code{calib_test}, \code{"interval"} shows baseline and lower/upper last-safe
threshold values by set and anchor. \code{"heatmap"} summarizes sensitivity
across anchor paths. \code{"trace"} shows the stepwise path for one set,
anchor, and direction.

For \code{theory_test}, the plot compares theory-specific selected models in
consistency/coverage space for one selected solution type. Theory names are shown
near the points, and the legend pairs each theory with its selected solution
terms.

For \code{\link[=sol.df]{sol.df()}} tables, \code{\link[=sol.chart]{sol.chart()}} draws a table-like chart of sufficient
configurations, using filled and open circles for condition presence and
absence.
}

\section{Family Consistency}{

These methods follow the common qcaERT output conventions described in
\code{?qcaERT_conventions}: plots read from \code{diagnostics} and path-level supporting
components, while \code{print()} and \code{as.data.frame()} keep their existing
concise and tabular behavior. \code{\link[=sol.chart]{sol.chart()}} follows the same division of
labor by reading from the already-extracted \code{\link[=sol.df]{sol.df()}} table.
}

\examples{
\donttest{
library(QCA)
library(ggplot2)

data(LR)

conditions <- c("DEV", "URB", "LIT", "IND", "STB")
outcome <- "SURV"
dir_exp <- rep("1", length(conditions))

thresholds <- list(
  DEV = findTh(LR$DEV, groups = 7),
  URB = findTh(LR$URB, groups = 4),
  LIT = findTh(LR$LIT, groups = 4),
  IND = findTh(LR$IND, groups = 4),
  STB = findTh(LR$STB, groups = 4),
  SURV = findTh(LR$SURV, groups = 4)
)

dat <- LR
dat$DEV <- calibrate(LR$DEV, type = "fuzzy", thresholds = thresholds$DEV)
dat$URB <- calibrate(LR$URB, type = "fuzzy", thresholds = thresholds$URB)
dat$LIT <- calibrate(LR$LIT, type = "fuzzy", thresholds = thresholds$LIT)
dat$IND <- calibrate(LR$IND, type = "fuzzy", thresholds = thresholds$IND)
dat$STB <- calibrate(LR$STB, type = "fuzzy", thresholds = thresholds$STB)
dat$SURV <- calibrate(LR$SURV, type = "fuzzy", thresholds = thresholds$SURV)

incl_out <- incl.test(
  data = dat,
  outcome = outcome,
  conditions = conditions,
  incl.cut = 0.8,
  step = 0.05,
  max_steps = 5,
  n.cut = 1,
  solution = "all",
  dir.exp = dir_exp,
  progress = TRUE
)

calib_spec <- list(
  DEV = list(raw = "DEV", type = "fuzzy", method = "direct", thresholds = thresholds$DEV),
  URB = list(raw = "URB", type = "fuzzy", method = "direct", thresholds = thresholds$URB),
  LIT = list(raw = "LIT", type = "fuzzy", method = "direct", thresholds = thresholds$LIT),
  IND = list(raw = "IND", type = "fuzzy", method = "direct", thresholds = thresholds$IND),
  STB = list(raw = "STB", type = "fuzzy", method = "direct", thresholds = thresholds$STB)
)

calib_out <- calib.test(
  raw.data = LR,
  calib.data = dat,
  outcome = outcome,
  conditions = conditions,
  calib_spec = calib_spec,
  test.conditions = c("DEV", "URB"),
  unit_step = NULL,
  unit_step_divisor = 10,
  max_steps = 5,
  incl.cut = 0.8,
  n.cut = 1,
  solution = "all",
  dir.exp = dir_exp,
  progress = TRUE
)

theories <- list(
  development = c("DEV", "URB", "LIT"),
  industrial = c("DEV", "URB", "IND"),
  broad = c("DEV", "URB", "LIT", "IND", "STB")
)

theory_out <- theory.test(
  data = dat,
  outcome = outcome,
  theories = theories,
  incl.cut = 0.8,
  n.cut = 1,
  solution = "all",
  dir.exp = list(
    development = c("1", "1", "1"),
    industrial = c("1", "1", "1"),
    broad = c("1", "1", "1", "1", "1")
  ),
  progress = TRUE
)

plot(incl_out, solution_type = "conservative")
plot(incl_out, solution_type = "conservative", type = "trace", direction = "lower")
plot(calib_out, solution_type = "conservative")
plot(calib_out, solution_type = "conservative", type = "heatmap")
plot(
  calib_out,
  solution_type = "conservative",
  type = "trace",
  set = "DEV",
  anchor = "E1",
  direction = "lower"
)
plot(theory_out, solution_type = "conservative")
}

}
