% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motif-visualisation.R
\name{format_sequence_motif_positions}
\alias{format_sequence_motif_positions}
\title{Format Sequence Motif Position Summaries}
\usage{
format_sequence_motif_positions(
  x,
  digits = 3L,
  position_units = c("proportion", "percent"),
  include_rank = TRUE
)
}
\arguments{
\item{x}{An object returned by \code{summarise_sequence_motif_positions()}.}

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

\item{position_units}{Display units for relative positions: \code{"proportion"}
or \code{"percent"}. Absolute positions remain one-based sequence indices.}

\item{include_rank}{Logical value indicating whether to include an
earlier-to-later rank based on mean position. Ranking is performed within
each supplied \code{by} group.}
}
\value{
A named list containing the formatted \code{table}, validation metadata,
and formatting settings.
}
\description{
Produces a deterministic report-ready table from positional motif summaries.
}
\details{
Formatting copies and transforms the summary table only. The input object is
not modified. Rows are ordered deterministically by grouping values, mean
and median position, occurrence and sequence counts, motif length, and motif
key. Equal mean positions receive the same minimum rank.
}
\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"
)

positions <- summarise_sequence_motif_positions(
  extracted,
  position = "centre",
  scale = "relative"
)

formatted <- format_sequence_motif_positions(
  positions,
  position_units = "percent",
  digits = 1
)

formatted$table

}
