% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motifs.R
\name{format_sequence_motifs}
\alias{format_sequence_motifs}
\title{Format Sequence Motif Summaries}
\usage{
format_sequence_motifs(
  x,
  digits = 3L,
  prevalence = c("proportion", "percent"),
  include_rank = TRUE,
  rank_by = c("sequence_prevalence", "n_occurrences", "n_sequences"),
  ties = c("min", "first"),
  include_ids = TRUE
)
}
\arguments{
\item{x}{A motif extraction, motif summary, or filtered-motif object.}

\item{digits}{Whole number from 0 to 15 controlling numeric rounding.}

\item{prevalence}{Character value specifying whether prevalence and
occurrence share are shown as \code{"proportion"}s or \code{"percent"}ages.}

\item{include_rank}{Logical value indicating whether to add a rank column.}

\item{rank_by}{Metric used to order and rank motifs: one of
\code{"sequence_prevalence"}, \code{"n_occurrences"}, or \code{"n_sequences"}.}

\item{ties}{Character value specifying \code{"min"} shared ranks or
deterministic \code{"first"} ranks.}

\item{include_ids}{Logical value indicating whether \code{motif_id} and
\code{motif_key} should be included in the formatted table.}
}
\value{
A named list containing \code{table}, validation metadata, and formatting
settings. The table contains only structural motif measurements.
}
\description{
Produces a stable, report-ready table from motif extraction, summary, or
filtered-motif output.
}
\details{
Formatting changes display precision and units only. It does not change the
underlying motif counts or introduce substantive interpretation.
}
\examples{
sequences <- data.frame(
  id = c(rep("s1", 5L), rep("s2", 4L)),
  position = c(1:5, 1:4),
  state = c("A", "B", "A", "B", "A", "A", "B", "A", "C")
)

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

formatted <- format_sequence_motifs(
  extracted,
  prevalence = "percent",
  digits = 1
)

formatted$table

}
