% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motif-visualisation.R
\name{plot_sequence_motifs}
\alias{plot_sequence_motifs}
\title{Plot Sequence Motif Summaries}
\usage{
plot_sequence_motifs(
  x,
  metric = c("sequence_prevalence", "n_occurrences", "n_sequences", "occurrence_share"),
  top_n = 20L,
  motif_lengths = NULL,
  ties = c("include", "first"),
  horizontal = TRUE
)
}
\arguments{
\item{x}{A motif extraction, summary, or filtered-motif object.}

\item{metric}{Structural metric to plot: \code{"sequence_prevalence"},
\code{"n_occurrences"}, \code{"n_sequences"}, or \code{"occurrence_share"}.}

\item{top_n}{Positive whole number giving the requested number of motifs.}

\item{motif_lengths}{Optional vector of positive whole-number motif lengths
to retain.}

\item{ties}{Top-\code{n} boundary policy. \code{"include"} retains all motifs tied on
the selected metric; \code{"first"} retains exactly \code{top_n} after deterministic
secondary sorting.}

\item{horizontal}{Logical value indicating whether bars should be horizontal.}
}
\value{
Invisibly returns the exact motif table used for plotting, including
\code{plot_rank}, \code{plot_value}, \code{plot_label}, and \code{bar_midpoint}.
}
\description{
Draws a dependency-free base-R bar chart of structural motif measurements.
}
\details{
The plot is descriptive. It does not perform inferential testing or assign
substantive meaning to motif frequency or prevalence. Empty inputs produce
an informative blank plot and return an empty table.
}
\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_motifs(
  extracted,
  metric = "sequence_prevalence",
  top_n = 10
)

}
