% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/app_launch.R
\name{ggstratify}
\alias{ggstratify}
\title{Describe a data set, one layer at a time}
\usage{
ggstratify(dataset, launch.browser = TRUE, ...)
}
\arguments{
\item{dataset}{The data to describe, and the one thing the function needs:
a data frame -- including a \code{tibble} or a \code{data.table} -- or a matrix,
already read into your session and already of the types you mean. A file
path is not accepted; see \emph{Before you start}. Whatever it is given becomes
a plain \code{data.table}, so a grouped \code{tibble} is described as its rows, not
as its groups. The object is copied, never modified in place, and its name
is what the generated code refers to it by -- so pass a named object,
rather than an expression: \code{ggstratify(head(cohort))} is described
perfectly well, but the code it prints says \code{d <- mydata}, because
\code{head(cohort)} is not a name.}

\item{launch.browser}{Passed to \code{\link[shiny:runApp]{shiny::runApp()}}. \code{TRUE} opens the system
browser.}

\item{...}{Further arguments passed to \code{\link[shiny:runApp]{shiny::runApp()}}.}
}
\value{
Invisibly \code{NULL}, after the app is closed. Called for its side
effect of running a Shiny application.
}
\description{
Launches a point-and-click Shiny interface for descriptive analysis: pick
the variable you want to describe, then add the layers you want to see it
within. The figure, the number of observations behind it and the R code
that reproduces it all appear together.
}
\section{The layers}{


A description has a variable being described and, around it, the variables
you want to see it within. \code{ggstratify} calls those the layers, and asks
you to place each one:

\describe{
\item{One layer}{The variable on its own. A plain \code{ggplot2} figure.}
\item{Two layers}{The second variable becomes the panels of a
\code{facet_wrap()}, so the whole comparison is one figure.}
\item{Three or more}{Two layers is what a single figure holds. Beyond
that, you choose: one variable stays as the \code{facet_wrap()} panels, and
the rest become separate figures -- one file each. With columns A, B, C
and D you might describe D, panel it by C, and get one figure per
level of A and of B.}
}

The variables that make separate figures can be treated separately, which
is the default -- ticking \code{sex} and \code{treatment} gives the figures \code{sex_M},
\code{sex_F}, \code{treatment_A}, ... -- or crossed, giving one figure per observed
combination. Separately is usually the right question for descriptive
work: crossing two five-level variables gives twenty-five mostly empty
figures.
}

\section{What it tells you}{


Every level is reported with the number of observations it contains, and
that number is written into the figure title and onto each panel strip
inside it: a strip reads \verb{site: Site A (N = 303)} rather than \verb{Site A}, so
that a level which does not explain itself -- the bare range a categorized
variable produces -- still says which variable it is a level of. A level
with no observations at all (an unused factor level) is listed with
\code{N = 0} and produces no figure. Rows with a missing value in any layer
variable are excluded -- a row that does not say which panel it belongs to
cannot be drawn in one -- and the number excluded is reported on the Strata
tab and by the generated code.
}

\section{Three things descriptive work keeps needing}{


Under \strong{Categorize}, a continuous variable becomes a categorical one --
quantile groups, equal-width bins or your own cut points -- and can then be
used as a layer like any other categorical variable.

Under \strong{Type of graph}, \emph{Kaplan-Meier curve} draws survival curves from a
time variable and an event indicator, fitted with \code{\link[survival:survfit]{survival::survfit()}}
within each group, panel and figure, optionally with a confidence band,
censoring marks and a number-at-risk table under the curve. \emph{Line} draws
change over time: put time on the X axis and the measurement on the Y axis,
and name the subject identifier under \strong{One line per} to get one line per
subject.

A \emph{Line} or \emph{Scatter} figure can carry a LOWESS smoother -- \code{stats::loess()}
through \code{\link[ggplot2:geom_smooth]{ggplot2::geom_smooth()}} -- with its span under your control and,
when a grouping variable is set, one fit per group.
}

\section{Before you start}{


Convert each column to the type you mean it to have -- \code{numeric} for
measurements, \code{factor} for groups, with the levels in the order you want
them read -- before passing the data. \code{ggstratify} describes what it is
given; it does not guess what you meant. A grouping variable stored as
\verb{1, 2, 3} will be described as a number.

This is why the data must be an object you already have in your session.
There is no file to choose from inside the application, and no file path to
hand it: a data set that arrives by being read from disk arrives with types
that a reader guessed, and it is then described on those guessed types
without anyone having looked at them. Read the file yourself, run
\code{\link[=str]{str()}} or \code{\link[=summary]{summary()}} over the result, fix the types that are wrong, and
pass that object:

\if{html}{\out{<div class="sourceCode">}}\preformatted{cohort <- read.csv("cohort.csv")
cohort$treatment <- factor(cohort$treatment,
                           levels = c("Control", "Low dose", "High dose"))
str(cohort)
ggstratify(cohort)
}\if{html}{\out{</div>}}

The figure types, themes and palettes otherwise match those offered by the
\pkg{ggplotgui} package. All data handling uses \pkg{data.table}. Figures
are written as PNG (through \pkg{ragg}) or as SVG, and the "R-code" tab
shows the self-contained \pkg{ggplot2} code for the figure on screen --
just the figure, since writing the files is what the export button is for.
The preview, the export button and that code are all produced by the same
code generator, so the code you are shown is the code that made the
figure.
}

\examples{
if (interactive()) {
  ggstratify(iris)
  ggstratify(epi_cohort)
}
}
