% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/addRepCoordinates.R
\name{addRepCoordinates}
\alias{addRepCoordinates}
\title{Add representative coordinates from amino acid position annotations}
\usage{
addRepCoordinates(
  guideSet,
  positionMethod = c("average", "max", "all"),
  minEditingWeight = 0.3
)
}
\arguments{
\item{guideSet}{A \code{GuideSet} object containing at least a column named
\code{aaPos}. Optionally, it may also contain a column named
\code{aaChanges}.}

\item{positionMethod}{Character string specifying how plotting coordinates
should be assigned. Must be one of \code{"average"}, \code{"max"}, or
\code{"all"}.}

\item{minEditingWeight}{Numeric scalar giving the minimum editing weight
required for an edited amino acid position to be retained when
\code{positionMethod = "all"}. Default is \code{0.3}.}
}
\value{
If \code{positionMethod = "average"}, an integer vector of length
\code{nrow(df)} is added to the mcols of the GuideSet object. 

If \code{positionMethod = "max"}, a named integer vector of length
\code{nrow(df)} when \code{aaChanges} is available; otherwise an unnamed
integer vector.

If \code{positionMethod = "all"}, a list of length \code{nrow(df)}, where
each element is an integer vector containing one or more plotting
coordinates for that row. When \code{aaChanges} is available, each integer
vector is named by the corresponding amino acid substitution.
}
\description{
Convert amino acid position annotations into representative coordinates for
downstream one-dimensional smoothing or clustering analyses.
}
\details{
The column annotation of the input \code{GuideSet} must contain a 
column named \code{aaPos}. This column
typically stores one or more amino acid positions per row, encoded as
semi-colon-separated integers (for example, \code{"120;121"}).

When \code{positionMethod = "average"}, each row is assigned a single
coordinate equal to the floor of the mean of the positions listed in
\code{aaPos}.

When \code{positionMethod = "max"}, the function uses the \code{aaChanges}
column, if available, to identify the amino acid position associated with
the largest editing score. The returned integer vector is named by the
corresponding amino acid substitution (for example, \code{"R314K"}). If
\code{aaChanges} is missing, the function falls back to \code{aaPos} and
returns an unnamed vector.

When \code{positionMethod = "all"}, the function returns all amino acid
positions with editing weights greater than or equal to
\code{minEditingWeight}, based on \code{aaChanges}. If no position passes
the threshold, the first listed substitution is returned. Each element of
the returned list is a named integer vector, where names are amino acid
substitutions (for example, \code{"R314K"}). If \code{aaChanges} is
missing, the function falls back to \code{aaPos}.

The \code{aaChanges} column is expected to contain strings such as
\code{"R314K(0.41);V315I(0.29);A311T(0.10)"}, where the amino acid position
is extracted from each substitution and the value in parentheses is treated
as its editing weight.
}
