% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motif-visualisation.R
\name{plot_sequence_motif_positions}
\alias{plot_sequence_motif_positions}
\title{Plot Sequence Motif Positions}
\usage{
plot_sequence_motif_positions(
  x,
  motifs = NULL,
  position = c("start", "centre", "end"),
  scale = c("absolute", "relative"),
  top_n = 10L,
  display = c("strip", "distribution")
)
}
\arguments{
\item{x}{An object returned by \code{extract_sequence_ngrams()} or
\code{summarise_sequence_motif_positions()}.}

\item{motifs}{Optional character vector of motif identifiers, motif keys, or
displayed motif labels. When omitted, motifs are selected deterministically
by occurrence count, sequence count, motif length, and motif key.}

\item{position}{Occurrence position represented by motif \code{"start"},
\code{"centre"}, or \code{"end"}.}

\item{scale}{Position scale: one-based \code{"absolute"} sequence positions or
\code{"relative"} positions from 0 to 1.}

\item{top_n}{Positive whole number giving the number of motifs selected when
\code{motifs} is \code{NULL}.}

\item{display}{Base-R display type: occurrence \code{"strip"} or
\code{"distribution"} boxplots.}
}
\value{
Invisibly returns the exact occurrence-level data used by the plot,
including deterministic motif ranks and plotting coordinates where relevant.
}
\description{
Shows occurrence locations for selected contiguous motifs.
}
\details{
The strip display uses deterministic vertical stacking rather than random
jitter. The distribution display uses one horizontal boxplot per motif.
Empty inputs produce an informative blank plot and return an empty table.
The function provides structural location summaries only.
}
\examples{
sequences <- data.frame(
  id = c(rep("s1", 5L), rep("s2", 4L)),
  position = c(1:5, 1:4),
  state = c("A", "B", "A", "B", "C", "A", "B", "C", "B")
)

extracted <- extract_sequence_ngrams(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

plot_sequence_motif_positions(
  extracted,
  position = "centre",
  scale = "relative",
  top_n = 5,
  display = "strip"
)

}
