% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/magnitude_difference.R
\name{magnitude_difference}
\alias{magnitude_difference}
\alias{print.magnitude_difference}
\alias{plot.magnitude_difference}
\title{Magnitude difference between the frequency and probability views}
\usage{
magnitude_difference(
  data,
  actor = "Actor",
  action = "Action",
  time = NULL,
  metric = c("abs_diff", "chord_dist", "atanh_diff", "geom_norm_diff", "cv_inflation"),
  scale = c("tna_range", "rank_minmax", "minmax", "none"),
  format = c("auto", "long", "wide")
)

\method{print}{magnitude_difference}(x, ...)

\method{plot}{magnitude_difference}(x, type = c("stacked", "circular"), min_show = 0.01, title = NULL, ...)
}
\arguments{
\item{data}{Long- or wide-format event log (\code{data.frame}).}

\item{actor, action, time}{Column names in \code{data} (long format). \code{time} may
be \code{NULL}.}

\item{metric}{Discrepancy metric. One of \code{"abs_diff"} (default; absolute
difference, simplest and most robust), \code{"chord_dist"} (chord distance on
the unit sphere), \code{"atanh_diff"} (Fisher z-style on a bounded scale),
\code{"geom_norm_diff"} (geometric-mean normalized; amplifies small edges),
\code{"cv_inflation"} (per-vector SD-standardized then absolute difference).}

\item{scale}{How the two weight matrices are placed on a common scale
before differencing. \code{"tna_range"} (default) rescales FTNA linearly into
TNA's \verb{[min, max]} range and leaves TNA untouched, so the difference is
in TNA probability units. \code{"rank_minmax"} converts each matrix's values
to ranks scaled to \verb{[0, 1]} (ordinal). \code{"minmax"} scales each matrix's
raw values to \verb{[0, 1]} separately (asymmetric - TNA's max and FTNA's max
map to the same value despite differing native ranges). \code{"none"} uses
raw weights.}

\item{format}{Input format passed through to \code{\link[=build_network]{build_network()}};
\code{"auto"} (default) treats the data as wide when \code{action} is not a column.}

\item{x}{A \code{magnitude_difference} object.}

\item{...}{Passed to plotting helpers (ignored by \code{print}).}

\item{type}{Plot style, \code{"stacked"} (default) or \code{"circular"}.}

\item{min_show}{For \code{type = "circular"}, drop edges whose magnitude is
below this fraction of the maximum.}

\item{title}{Plot title. \code{NULL} generates one from the metric and scale.}
}
\value{
An object of class \code{"magnitude_difference"}: a list with
\verb{$edges} (per-edge \code{data.frame} with columns \code{from}, \code{to}, \code{ftna},
\code{tna}, \code{signed} = \code{tna - ftna}, and \code{value} = the chosen metric),
\verb{$metric}, \verb{$scale}, \verb{$weights_ftna}, \verb{$weights_tna}, and \verb{$states}.

\code{print} invisibly returns \code{x}.

\code{plot} returns a \code{ggplot} object.
}
\description{
Quantifies, per edge, how much row-normalization moves a transition
network between its two natural summaries: raw transition counts
(frequency / FTNA, \code{build_network(method = "frequency")}) and
row-conditional probabilities (TNA, \code{build_network(method = "relative")}).
The two matrices rank edges differently - an edge that is large in counts
can be modest in probability, and a rare-source edge can dominate its row
in probability. The per-edge discrepancy on a common scale is the
\emph{magnitude difference}.
}
\section{Methods (by generic)}{
\itemize{
\item \code{print(magnitude_difference)}: Print a compact summary of the per-edge
magnitude-difference distribution.

\item \code{plot(magnitude_difference)}: Plot the per-edge magnitude difference as
a polar portrait. \code{type = "stacked"} (default) draws one sector per
from-state with stacked wedges (grey base = shared value, colored tip =
magnitude difference); \code{type = "circular"} draws a chord-style diagram
with signed differences on a diverging blue-orange scale.

}}
\examples{
data(group_regulation_long, package = "Nestimate")
fit <- magnitude_difference(group_regulation_long,
                            actor = "Actor", action = "Action",
                            time = "Time")
print(fit)
# Edges most promoted by row-normalization (rare-source transitions):
head(fit$edges[order(-fit$edges$signed), c("from", "to", "ftna", "tna")])
\donttest{
plot(fit)                       # stacked polar portrait
plot(fit, type = "circular")    # chord-style diagram
}
}
\seealso{
\code{\link[=build_network]{build_network()}}, \code{\link[=compare_model]{compare_model()}}
}
