% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/com_segment_missingness.R
\name{com_segment_missingness}
\alias{com_segment_missingness}
\title{Summarizes missingness for individuals in specific segments}
\usage{
com_segment_missingness(
  study_data,
  item_level = "item_level",
  strata_vars = NULL,
  group_vars = NULL,
  label_col,
  threshold_value,
  direction,
  color_gradient_direction,
  expected_observations = c("HIERARCHY", "ALL", "SEGMENT"),
  exclude_roles = c(VARIABLE_ROLES$PROCESS),
  meta_data = item_level,
  meta_data_v2,
  segment_level,
  meta_data_segment
)
}
\arguments{
\item{study_data}{\link{data.frame} the data frame that contains the measurements}

\item{item_level}{\link{data.frame} the data frame that contains metadata
attributes of study data}

\item{strata_vars}{\link{variable} the name of a variable used for stratification,
defaults to NULL for not grouping output}

\item{group_vars}{\link{variable} the name of a variable used for grouping,
defaults to \emph{NULL} for not grouping output}

\item{label_col}{\link{variable attribute} the name of the column in the metadata
with labels of variables}

\item{threshold_value}{\link{numeric} from=0 to=100. a numerical value ranging
from 0-100}

\item{direction}{\link{enum} low | high. "high" or "low", i.e. are deviations
above/below the threshold critical. This argument is deprecated and replaced by \emph{color_gradient_direction}.}

\item{color_gradient_direction}{\link{enum} above | below. "above" or "below", i.e. are deviations
above or below the threshold critical? (default: above)}

\item{expected_observations}{\link{enum} HIERARCHY | ALL | SEGMENT. If ALL, all
observations are expected to comprise
all study segments. If SEGMENT, the
\code{PART_VAR} is expected to point
to a variable with values of 0 and 1,
indicating whether the variable was
expected to be observed for each data
row. If HIERARCHY, this is also
checked recursively, so, if a variable
points to such a participation variable,
and that other variable does has also
a \code{PART_VAR} entry pointing
to a variable, the observation of the
initial variable is only
expected, if both segment variables are
1.}

\item{exclude_roles}{\link{variable roles} a character (vector) of variable roles
not included}

\item{meta_data}{\link{data.frame} old name for \code{item_level}}

\item{meta_data_v2}{\link{character} path to workbook like metadata file, see
\code{\link{prep_load_workbook_like_file}} for details.
\strong{ALL LOADED DATAFRAMES WILL BE PURGED},
using \code{\link{prep_purge_data_frame_cache}},
if you specify \code{meta_data_v2}.}

\item{segment_level}{\link{data.frame} alias for \code{meta_data_segment}}

\item{meta_data_segment}{\link{data.frame} Segment level metadata. Optional.}
}
\value{
a list with:
\itemize{
\item \code{ResultData}: data frame about segment missingness
\item \code{SummaryPlot}: ggplot2 heatmap plot: a heatmap-like graphic that
highlights critical values depending on the respective
threshold_value and direction.
\item \code{ReportSummaryTable}: data frame underlying \code{SummaryPlot}
}
}
\description{
\subsection{This implementation can be applied in two use cases:}{
\enumerate{
\item participation in study segments is not recorded by respective variables,
e.g. a participant's refusal to attend a specific examination is not
recorded.
\item participation in study segments is recorded by respective
variables.
}

Use case \emph{(1)} will be common in smaller studies. For the calculation of
segment missingness it is assumed that study variables are nested in
respective segments. This structure must be specified in the static metadata.
The R-function identifies all variables within each segment and returns TRUE
if all variables within a segment are missing, otherwise FALSE.

Use case \emph{(2)} assumes a more complex structure of study data and metadata.
The study data comprise so-called intro-variables (either TRUE/FALSE or codes
for non-participation). The column \code{PART_VAR} in the metadata is
filled by variable-IDs indicating for each variable the respective
intro-variable. This structure has the benefit that subsequent calculation of
item missingness obtains correct denominators for the calculation of
missingness rates.

\link{Descriptor}
}
}
\details{
\subsection{Implementation and use of thresholds}{

This implementation uses one threshold to discriminate critical from
non-critical values. If direction is above than all values below the
threshold_value are normal (displayed in dark blue in the plot and flagged
with GRADING = 0 in the dataframe). All values above the threshold_value are
considered critical. The more they deviate from the threshold the displayed
color shifts to dark red. All critical values are highlighted with GRADING =
1 in the summary data frame. By default, highest values are always shown in
dark red irrespective of the absolute deviation.

If direction is below than all values above the threshold_value are normal
(displayed in dark blue, GRADING = 0).
}

\subsection{Hint}{

This function does not support a \code{resp_vars} argument but \code{exclude_roles} to
specify variables not relevant for detecting a missing segment.

List function.
}
}
\seealso{
\href{https://dataquality.qihs.uni-greifswald.de/VIN_com_impl_segment_missingness.html}{Online Documentation}
}
