% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/voting_methods.R
\name{seq_phragmen}
\alias{seq_phragmen}
\title{Sequential Phragmen's Rule}
\usage{
seq_phragmen(
  voters,
  candidates,
  weights = NULL,
  committee_size = NULL,
  borda_score = TRUE,
  check = FALSE
)
}
\arguments{
\item{voters}{(\code{list()}) \cr
A list of subsets (\code{character} vectors), where each subset contains the
candidates approved or selected by a voter.}

\item{candidates}{(\code{character()}) \cr
A vector of all candidates to be ranked.}

\item{weights}{(\code{numeric()|NULL}) \cr
A numeric vector of non-negative weights representing each voter's influence.
Larger weight, higher influence.
Must have the same length as \code{voters}.
If \code{NULL} (default), all voters are assigned equal weights of 1, representing
equal influence.}

\item{committee_size}{(\code{integer(1)|NULL})\cr
Number of top-ranked candidates to return.
Default (\code{NULL}) returns all candidates.}

\item{borda_score}{(\code{logical(1)}) \cr
Whether to include a \code{borda_score} column in the output, which provides a
normalized score based on the candidate's rank.
If \code{TRUE} (default), the \code{borda_score} is calculated as \eqn{(p - i) / (p - 1)},
where \eqn{p} is the total number of candidates and \eqn{i} is the candidate's rank.}

\item{check}{(\code{logical(1)}) \cr
Whether to run additional voter-integrity checks. When \code{TRUE}, each voter
must approve at least one candidate, approvals must be unique per voter, and
all approved candidates must appear in \code{candidates}. Use \code{FALSE} to skip
these checks when inputs are known to be valid.}
}
\value{
A \code{data.frame} with columns:
\itemize{
\item \code{"candidate"}: Candidate names.
\item \code{"borda_score"}: Borda scores for method-agnostic comparison, ranging in \eqn{[0,1]}, where the top candidate receives a score of 1 and the lowest-ranked candidate receives a score of 0, based on the total number of candidates.
}

Candidates are ordered by the sequence in which they were selected.
}
\description{
\strong{Sequential Phragmen's Rule} is a multi-winner method that builds a committee
by distributing representation \emph{loads} across voters as evenly as possible.
At each step, it selects the candidate that yields the smallest increase in
voter load, then updates loads for voters who approved the chosen candidate.
The process continues until the committee is filled or all candidates are ranked.

This function uses an internal C++ implementation for efficient computation.
}
\seealso{
Other voting methods: 
\code{\link{av}()},
\code{\link{sav}()},
\code{\link{seq_pav}()}
}
\concept{voting methods}
