combine pivot docs

use divisor_methods man page

R/S3.R

@@ -12,14 +12,14 @@ as.matrix.proporz_matrix = function(x, ...) {
 
 #' Get district and party divisors from [biproporz()] result
 #'
-#' Show the district and party divisors used for to assign seats.
+#' Show the district and party divisors used to assign seats.
 #' This method provides easier access to divisors stored in
 #' `attributes(...)$divisors`
 #'
-#' @param biproporz_result a matrix created by \code{\link{biproporz}}
-#'                         or a data.frame created by \code{\link{pukelsheim}}
+#' @param biproporz_result a matrix created by [biproporz()]
+#'                         or a data.frame created by [pukelsheim()]
 #'
-#' @returns The district and party divisors in a list
+#' @returns The district and party divisors in a list, each as vectors
 #'
 #' @examples
 #' votes_matrix = matrix(c(51,60,63,98,100,102,45,120,144), nrow = 3)

R/biproportional.R

@@ -131,15 +131,15 @@ pukelsheim = function(votes_df, district_seats_df,
 #'       to terminate with the default Sainte-Laguë/Webster method.
 #'
 #' @seealso [pukelsheim()] for usage with data frames.
-#'          [get_divisors()] to access the divisors
 #'
 #' @references Gaffke, Norbert; Pukelsheim, Friedrich (2008): Divisor methods
 #'             for proportional representation systems: An optimization approach
 #'             to vector and matrix apportionment problems. Mathematical Social
 #'             Sciences, 56 (2), 166–184.
 #'
 #' @returns Matrix with the same dimension as `votes_matrix` containing
-#'          the number of seats
+#'          the number of seats with the row and column divisors stored in
+#'          attributes (hidden from print, see [get_divisors()]).
 #'
 #' @examples
 #' votes_df = unique(zug2018[c("list_id", "entity_id", "list_votes")])

R/divisor.R

@@ -79,6 +79,10 @@ highest_averages_method = function(votes, n_seats, divisors) {
 #' divisor_geometric(votes, 10, quorum = 0.05)
 #'
 #' divisor_harmonic(votes, 10)
+#' @name divisor_methods
+NULL
+
+#' @rdname divisor_methods
 #' @export
 divisor_round = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -87,7 +91,7 @@ divisor_round = function(votes, n_seats, quorum = 0) {
     highest_averages_method(votes, n_seats, 0.5)
 }
 
-#' @rdname divisor_round
+#' @rdname divisor_methods
 #' @export
 divisor_floor = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -96,7 +100,7 @@ divisor_floor = function(votes, n_seats, quorum = 0) {
     highest_averages_method(votes, n_seats, 1)
 }
 
-#' @rdname divisor_round
+#' @rdname divisor_methods
 #' @export
 divisor_harmonic = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -109,7 +113,7 @@ divisor_harmonic = function(votes, n_seats, quorum = 0) {
     highest_averages_method(votes, n_seats, divisors)
 }
 
-#' @rdname divisor_round
+#' @rdname divisor_methods
 #' @export
 divisor_geometric = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -122,7 +126,7 @@ divisor_geometric = function(votes, n_seats, quorum = 0) {
     highest_averages_method(votes, n_seats, divisors)
 }
 
-#' @rdname divisor_round
+#' @rdname divisor_methods
 #' @export
 divisor_ceiling = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))

R/quorum.R

@@ -142,9 +142,9 @@ reached_quorum_any_district = function(votes_matrix, quorum_districts) {
 #'                     must be set which indicates whether `ALL` or `ANY`
 #'                     (i.e. at least one) quorum must be reached.
 #'
-#' @note This is a low-level implementation for quorum calculations and is
-#'       called within [biproporz()]. There's generally no need to call it
-#'       directly.
+#' This is a low-level implementation for quorum calculations and is
+#' called within [biproporz()]. There's generally no need to call it
+#' directly.
 #'
 #' @seealso [quorum_all()], [quorum_any()] to create a list of quorum functions.
 #'

R/utils.R

@@ -19,21 +19,44 @@ bisect = function(f, x1, x2, tol = 1e-9) {
     stop("Exceeded maximum number of iterations (1e6)") # nocov
 }
 
-#' Pivot long data.frame to wide matrix
+#' Pivot long data.frame to wide matrix and vice versa
 #'
+#' Create a matrix in 'wide' format from a data.frame with 3 columns with
+#' [pivot_to_matrix()] or create a data.frame in long format from a matrix with
+#' [pivot_to_df()].
+#'
+#' These pivot functions are used to prepare data for [biproporz()] in
+#' [pukelsheim()]. They are not supposed to cover general use cases or provide
+#' customization. They mainly exist because reshape is hard to handle and the
+#' package should have no dependencies.
+#
 #' @param df data.frame in long format with exactly 3 columns
+#' @param matrix_wide matrix in wide format
+#' @param value_colname name for the new value column in the
+#'                      resulting data.frame
 #'
-#' @note This function exists because reshape is hard to handle and the package
-#'       should have no dependencies.
-#' @seealso [pivot_to_df()]
+#' @returns A data.frame with 3 columns or a matrix or . Note that the results are
+#'          sorted by the first and second column (data.frame) or row/column
+#'          name (matrix).
 #'
-#' @returns a matrix
 #' @examples
+#' # From data.frame to matrix
 #' df = data.frame(party = c("A", "A", "A", "B", "B", "B"),
 #'                 region = c("III", "II", "I", "I", "II", "III"),
 #'                 seats = c(5L, 3L, 1L, 2L, 4L, 6L))
 #' pivot_to_matrix(df)
 #'
+#' # from matrix to data.frame
+#' mtrx = matrix(1:6, nrow = 2)
+#' pivot_to_df(mtrx)
+#'
+#' # from matrix to data.frame using dimnames
+#' dimnames(mtrx) <- list(party = c("A", "B"), region = c("I", "II", "III"))
+#' pivot_to_df(mtrx, "seats")
+#'
+#' # Note that pivot results are sorted
+#' pivot_to_df(pivot_to_matrix(df)) == df[order(df[[1]], df[[2]]),]
+#'
 #' @export
 pivot_to_matrix = function(df) {
     stopifnot(ncol(df) == 3)
@@ -43,19 +66,7 @@ pivot_to_matrix = function(df) {
     apply(tbl, c(1,2), function(x) sum(as.numeric(names(x))*unname(x)))
 }
 
-#' Pivot wide matrix to long data.frame
-#'
-#' @param matrix_wide matrix in wide format
-#' @param value_colname name for the data.frame new column
-#' @seealso [pivot_to_matrix()]
-#' @returns data.frame with 3 columns
-#' @examples
-#' mtrx = matrix(1:6, nrow = 2)
-#' pivot_to_df(mtrx)
-#'
-#' dimnames(mtrx) <- list(party = c("A", "B"), region = c("I", "II", "III"))
-#' pivot_to_df(mtrx, "seats")
-#'
+#' @rdname pivot_to_matrix
 #' @export
 pivot_to_df = function(matrix_wide, value_colname = "values") {
     if(is.null(dimnames(matrix_wide))) {