% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/manhattanplot.R
\name{ManhattanPlot}
\alias{ManhattanPlot}
\title{Manhattan plot}
\usage{
ManhattanPlot(
  data,
  chr_by,
  pos_by,
  pval_by,
  split_by = NULL,
  split_by_sep = "_",
  label_by = NULL,
  chromosomes = NULL,
  pt_size = 0.75,
  pt_color = NULL,
  pt_alpha = alpha,
  pt_shape = 19,
  label_size = 3,
  label_fg = NULL,
  highlight = NULL,
  highlight_color = NULL,
  highlight_size = 1.5,
  highlight_alpha = 1,
  highlight_shape = 19,
  preserve_position = TRUE,
  chr_gap_scaling = 1,
  pval_transform = "-log10",
  signif = c(5e-08, 1e-05),
  signif_color = NULL,
  signif_rel_pos = 0.2,
  signif_label = TRUE,
  signif_label_size = 3.5,
  signif_label_pos = c("left", "right"),
  thin = NULL,
  thin_n = 1000,
  thin_bins = 200,
  rescale = TRUE,
  rescale_ratio_threshold = 5,
  palette = "Dark2",
  palcolor = NULL,
  palreverse = FALSE,
  alpha = 1,
  theme = "theme_this",
  theme_args = list(),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = expression("-" * log[10](p)),
  seed = 8525,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  axes = NULL,
  axis_titles = axes,
  guides = NULL,
  facet_by = NULL,
  design = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{chr_by}{A character string specifying the column name for chromosome
identifiers.  Default: \code{"chr"}.}

\item{pos_by}{A character string specifying the column name for genomic
positions (integer or numeric).  Default: \code{"pos"}.}

\item{pval_by}{A character string specifying the column name for p-values
(numeric).  Default: \code{"pval"}.}

\item{split_by}{The column(s) to split data by and produce separate
sub-plots.  Multiple columns are concatenated with
\code{split_by_sep}.}

\item{split_by_sep}{A character string used to concatenate multiple
\code{split_by} column values.  Default: \code{"_"}.}

\item{label_by}{A character string specifying the column name for variant
labels.  Only variants with non-empty values in this column will be
labelled.  Default: \code{NULL} (no labels).}

\item{chromosomes}{A character or numeric vector specifying which
chromosomes to include and/or their display order.  When \code{NULL}
(the default), all chromosomes present in the data are plotted in
their natural factor order.  A single value filters to that
chromosome; a vector reorders and subsets.}

\item{pt_size}{A numeric value specifying the size of the points.
Default: \code{0.75}.}

\item{pt_color}{A character string specifying a single colour for all
background (non-highlighted) points.  When \code{NULL} (the default),
alternating chromosome colours from \code{palette} / \code{palcolor}
are used.  Typically set to \code{"grey80"} when \code{highlight} is
used with a distinct \code{highlight_color}.}

\item{pt_alpha}{A numeric value in \code{[0, 1]} specifying the
transparency of the points.  Default: \code{alpha} (aliased
parameter).}

\item{pt_shape}{A numeric value specifying the shape of the points.
Default: \code{19} (filled circle).}

\item{label_size}{A numeric value specifying the font size of the
variant labels.  Default: \code{3}.}

\item{label_fg}{A character string specifying the colour of the variant
labels.  When \code{NULL} (the default), each label inherits the
colour of its corresponding point.}

\item{highlight}{Either a numeric vector of row indices or a character
string containing an R expression (parsed via
\code{rlang::parse_expr()}) to select variants to highlight.
Default: \code{NULL} (no highlighting).}

\item{highlight_color}{A character string specifying the colour of
highlighted points.  When \code{NULL} (the default), highlighted
points inherit the chromosome colour from the underlying
\code{geom_point()} layer.}

\item{highlight_size}{A numeric value specifying the size of
highlighted points.  Default: \code{1.5}.}

\item{highlight_alpha}{A numeric value in \code{[0, 1]} specifying the
transparency of highlighted points.  Default: \code{1}.}

\item{highlight_shape}{A numeric value specifying the shape of
highlighted points.  Default: \code{19} (filled circle).}

\item{preserve_position}{A logical value.  When \code{TRUE} (the
default), the width of each chromosome segment reflects its number
of variants and variant positions are correctly scaled.  When
\code{FALSE}, all chromosomes have equal width and variants are
equally spaced.}

\item{chr_gap_scaling}{A numeric scaling factor for the gap between
chromosomes.  Larger values increase the gap.  Default: \code{1}.}

\item{pval_transform}{A function or character string that can be
evaluated to a function for transforming p-values.  Default:
\code{"-log10"}, which computes \eqn{-\log_{10}(p)}.  Other
examples: \code{"-log2"} or a custom
\code{function(x) -log10(x)}.}

\item{signif}{A numeric vector of significance thresholds to draw as
horizontal dashed lines.  Default: \code{c(5e-8, 1e-5)}.}

\item{signif_color}{A character vector of colours for the significance
threshold lines, of equal length as \code{signif}.  When \code{NULL}
(the default), the smallest threshold is coloured black and the rest
grey.}

\item{signif_rel_pos}{A numeric value between \code{0.1} and \code{0.9}
specifying the relative position of the y-axis jump when rescaling
is active.  Default: \code{0.2}.}

\item{signif_label}{A logical value.  When \code{TRUE} (the default),
significance threshold values are annotated on the plot.}

\item{signif_label_size}{A numeric value for the font size of the
significance threshold labels.  Default: \code{3.5}.}

\item{signif_label_pos}{A character string specifying where to place
the significance threshold labels: \code{"left"} (default) or
\code{"right"}.}

\item{thin}{A logical value indicating whether to thin dense data by
sampling points per horizontal partition.  Defaults to \code{TRUE}
when \code{chromosomes} selects fewer chromosomes than in the data,
and \code{FALSE} otherwise.}

\item{thin_n}{An integer specifying the maximum number of points per
horizontal partition after thinning.  Default: \code{1000}.}

\item{thin_bins}{An integer specifying the number of horizontal bins
for thinning.  Default: \code{200}.}

\item{rescale}{A logical value.  When \code{TRUE} (the default), the
y-axis is automatically rescaled (broken axis) if extreme
significance values would otherwise compress the main data cloud.}

\item{rescale_ratio_threshold}{A numeric threshold for triggering
y-axis rescaling.  The ratio is computed as
\code{ceiling(max(log10pval) / 5) * 5 / signif_jump}.
Default: \code{5}.}

\item{palette}{A character string specifying the palette to use.
A named list or vector can be used to specify the palettes for different \code{split_by} values.}

\item{palcolor}{A character string specifying the color to use in the palette.
A named list can be used to specify the colors for different \code{split_by} values.
If some values are missing, the values from the palette will be used (palcolor will be NULL for those values).}

\item{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

\item{alpha}{A numeric value specifying the transparency of the plot.}

\item{theme}{A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use.
Default is "theme_this".}

\item{theme_args}{A list of arguments to pass to the theme function.}

\item{title}{A character string specifying the title of the plot.
A function can be used to generate the title based on the default title.
This is useful when split_by is used and the title needs to be dynamic.}

\item{subtitle}{A character string specifying the subtitle of the plot.}

\item{xlab}{A character string specifying the x-axis label.}

\item{ylab}{A character string specifying the y-axis label.}

\item{seed}{A numeric seed for reproducibility.  Passed to
\code{\link{validate_common_args}()}.  Default: \code{8525}.}

\item{combine}{A logical value.  When \code{TRUE} (the default), the
list of per-split plots is combined into a single \code{patchwork}
object.  When \code{FALSE}, returns the raw list.}

\item{nrow, ncol, byrow}{Integers controlling the layout of combined
plots via \code{patchwork::wrap_plots()}.  \code{byrow = TRUE}
fills the layout row-wise.}

\item{axes, axis_titles}{Strings controlling how axes and axis titles
are handled across combined plots.  Passed to
\code{\link{combine_plots}()}.  See \code{?patchwork::wrap_plots}
for options (\code{"keep"}, \code{"collect"}, \code{"collect_x"},
\code{"collect_y"}).}

\item{guides}{A string controlling guide collection across combined
plots.  Passed to \code{\link{combine_plots}()}.}

\item{facet_by}{A character string specifying the column name of the data frame to facet the plot.
Otherwise, the data will be split by \code{split_by} and generate multiple plots
and combine them into one using \code{patchwork::wrap_plots}}

\item{design}{A custom layout specification for combined plots.
Passed to \code{\link{combine_plots}()}.  When specified,
\code{nrow}, \code{ncol}, and \code{byrow} are ignored.}

\item{...}{Additional arguments.}
}
\value{
A \code{ggplot} object (single plot, no \code{split_by}), a
\code{patchwork} object (when \code{combine = TRUE} with
\code{split_by}), or a named list of \code{ggplot} objects (when
\code{combine = FALSE}).  Each individual plot carries
\code{height} and \code{width} attributes.
}
\description{
Renders a publication-quality Manhattan plot for genetic association
results.  The y-axis displays \eqn{-\log_{10}(p)} (or a user-specified
transformation) of p-values, and the x-axis shows genomic positions
organised by chromosome.  Each chromosome is rendered in alternating
colours, and configurable horizontal dashed lines mark genome-wide
significance thresholds.

The function is adapted from \code{ggmanh::manhattan_plot()} with
extended control over point appearance, variant labels, highlighting,
data thinning, y-axis rescaling, and \code{split_by} support for
creating multi-panel layouts (e.g. faceted by cohort or phenotype).
}
\note{
\code{facet_by} is not supported by this plot type and triggers
a warning if provided.  Use \code{split_by} instead to produce
comparable multi-panel layouts.
}
\section{split_by Workflow}{


When \code{split_by} is provided:
\enumerate{
\item \strong{Column validation} --- \code{\link{check_columns}()}
resolves \code{split_by} with \code{force_factor = TRUE},
\code{allow_multi = TRUE}, and \code{concat_multi = TRUE}.  For
\code{GRanges} inputs, validation is performed on the
\code{@elementMetadata} slot.
\item \strong{GRanges support} --- \code{data} can be a
\code{data.frame} or a \code{GenomicRanges::GRanges} object.
When \code{GRanges} is used, \code{split_by} is read from the
metadata columns.
\item \strong{Data splitting} --- drops unused \code{split_by}
levels, splits \code{data} by \code{split_by} (preserving factor
level order), and wraps into a named list.  When \code{split_by}
is \code{NULL}, the data is wrapped as a single-element list with
name \code{"..."}.
\item \strong{Per-split palette / colour} ---
\code{\link{check_palette}()} and \code{\link{check_palcolor}()}
resolve per-split palette and colour overrides.
\item \strong{Per-split title} --- when \code{title} is a function,
it receives the default title (the split level name) and can return
a custom string; otherwise \code{title \%||\% split_level} is used.
\item \strong{Dispatch} --- each split subset is passed to
\code{\link{ManhattanPlotAtomic}}.
\item \strong{Combination} --- \code{\link{combine_plots}()}
assembles the list of plots via \code{patchwork::wrap_plots},
honouring \code{nrow} / \code{ncol} / \code{byrow} / \code{design}.
}
}

\examples{
\donttest{
set.seed(1000)

nsim <- 50000

# --- Data simulation ---
simdata <- data.frame(
  "chromosome" = sample(c(1:22,"X"), size = nsim, replace = TRUE),
  "position" = sample(1:100000000, size = nsim),
  "P.value" = rbeta(nsim, shape1 = 5, shape2 = 1)^7,
  "cohort" = sample(c("A", "B"), size = nsim, replace = TRUE)
)
simdata$chromosome <- factor(simdata$chromosome, c(1:22, "X"))
options(repr.plot.width=10, repr.plot.height=5)

# --- Basic Manhattan plot ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   title = "Simulated P.Values", ylab = "P")
}

# --- split_by ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   title = "Simulated P.Values", ylab = "P", split_by = "cohort", ncol = 1)
}

# --- Customized p-value transformation and significance threshold line colors ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   title = "Simulated -Log2 P.Values", ylab = "-log2(P)", pval_transform = "-log2",
   signif_color = c("red", "blue"))
}

# --- Different palette and no significance threshold labels ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   palette = "Set1", signif_label = FALSE)
}

# --- Reverse palette and label position on the right ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   palette = "Set1", palreverse = TRUE, signif_label_pos = "right")
}

# --- Single chromosome ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   title = "Simulated P.Values", chromosomes = 5)
}

# --- Chromosome subset and reorder ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
   simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
   title = "Simulated P.Values", chromosomes = c(20, 4, 6))
}

tmpdata <- data.frame(
  "chromosome" = c(rep(5, 10), rep(21, 5)),
  "position" = c(sample(250000:250100, 10, replace = FALSE),
    sample(590000:600000, 5, replace = FALSE)),
  "P.value" = c(10^-(rnorm(10, 100, 3)), 10^-rnorm(5, 9, 1)),
  "cohort" = c(rep("A", 10), rep("B", 5))
)

simdata <- rbind(simdata, tmpdata)
simdata$chromosome <- factor(simdata$chromosome, c(1:22, "X"))

# --- Disable y-axis rescaling ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
    simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
    title = "Simulated P.Values - Significant", rescale = FALSE)
}

# --- Y-axis rescaling with custom break position ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(
    simdata, pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
    title = "Simulated P.Values - Significant", rescale = TRUE, signif_rel_pos = 0.5)
}

sig <- simdata$P.value < 5e-07

simdata$label <- ""
simdata$label[sig] <- sprintf("Label: \%i", 1:sum(sig))
simdata$label2 <- ""
i <- (simdata$chromosome == 5) & (simdata$P.value < 5e-8)
simdata$label2[i] <- paste("Chromosome 5 label", 1:sum(i))

# --- Variant labels ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(simdata, label_by = "label", pval_by = "P.value", chr_by = "chromosome",
    pos_by = "position", title = "Simulated P.Values with labels", label_size = 4)
}

# --- Variant labels with custom color ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(simdata, label_by = "label2", pval_by = "P.value", chr_by = "chromosome",
    pos_by = "position", title = "Simulated P.Values with labels",
    label_size = 3, label_fg = "black")
}

simdata$color <- "Not Significant"
simdata$color[simdata$P.value <= 5e-8] <- "Significant"

# --- Highlight points with custom shape ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(simdata, title = "Highlight Points with shapes",
    pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
    highlight = "color == 'Significant'", highlight_color = NULL, highlight_shape = 6,
    highlight_size = 5, pt_alpha = 0.2, pt_size = 1)
}

# --- Highlight points with custom color ---
if (requireNamespace("ggmanh", quietly = TRUE)) {
ManhattanPlot(simdata, title = "Highlight Points",
    pval_by = "P.value", chr_by = "chromosome", pos_by = "position",
    highlight = "color == 'Significant'", highlight_color = "black",
    pt_color = "lightblue", pt_alpha = 0.2, pt_size = 0.1)
}
}
}
