% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motifs.R
\name{filter_sequence_motifs}
\alias{filter_sequence_motifs}
\title{Filter Sequence Motif Summaries}
\usage{
filter_sequence_motifs(
  x,
  min_occurrences = 1L,
  min_sequences = 1L,
  min_prevalence = 0,
  motif_lengths = NULL,
  top_n = NULL,
  rank_by = c("sequence_prevalence", "n_occurrences", "n_sequences"),
  ties = c("include", "first")
)
}
\arguments{
\item{x}{A motif extraction, motif summary, or filtered-motif object.}

\item{min_occurrences}{Non-negative whole number giving the minimum total
occurrence count.}

\item{min_sequences}{Non-negative whole number giving the minimum number of
sequences containing the motif.}

\item{min_prevalence}{Minimum sequence prevalence between 0 and 1.}

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

\item{top_n}{Optional positive whole number giving the requested number of
highest-ranked motifs.}

\item{rank_by}{Metric used for deterministic top-ranking: one of
\code{"sequence_prevalence"}, \code{"n_occurrences"}, or \code{"n_sequences"}.}

\item{ties}{Character value controlling the top-\code{n} boundary. \code{"include"}
retains every motif tied on \code{rank_by} with the final selected motif;
\code{"first"} retains exactly \code{top_n} motifs after deterministic secondary
sorting.}
}
\value{
A named list containing the filtered \code{motifs} table, the matching
sequence-level rows in \code{by_sequence}, sequence and state dictionaries,
validation metadata, filter settings, and counts before and after filtering.
}
\description{
Applies transparent count, prevalence, length, and top-ranking filters to
sequence motif summaries.
}
\details{
Filtering is descriptive and deterministic. When \code{ties = "first"}, ties are
resolved by sequence prevalence, occurrence count, sequence count, shorter
motif length, and finally the collision-resistant motif key.
}
\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"
)

filtered <- filter_sequence_motifs(
  extracted,
  min_sequences = 2,
  top_n = 5,
  ties = "include"
)

filtered$motifs

}
