prepare CRAN

add return value doc, usethis::use_logo, update description, add NEWS.md, use github links
polettif · Jan 31, 2024 · 100bc7e · 100bc7e
1 parent 0021ea5
commit 100bc7e
Show file tree

Hide file tree

Showing 33 changed files with 97 additions and 17 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -2,10 +2,12 @@ Package: proporz
 Type: Package
 Title: Proportional Apportionment
 Version: 1.3.1
-Author: Flavio Poletti
-Maintainer: Flavio Poletti <[email protected]>
-Description: Calculate seat apportionment for legislative bodies using 
-    different established methods, including biproportional apportionment.
+Authors@R: c(
+    person("Flavio", "Poletti", role = c("cre", "cph"), email = "[email protected]"))
+Description: Calculate seat apportionments for legislative bodies with 
+    various methods. Methods inlcude divisor methods (e.g. D'Hondt, Webster or 
+    Adams), quota methods (e.g. 'largest remainder method') and biproportional 
+    apportionment.
 License: GPL (>=3)
 Encoding: UTF-8
 LazyData: true
@@ -17,3 +19,5 @@ Suggests:
     testthat,
     shiny,
     shinyMatrix
+URL: https://github.com/polettif/proporz
+BugReports: https://github.com/polettif/proporz/issues
diff --git a/NEWS.md b/NEWS.md
@@ -0,0 +1,3 @@
+# proporz 1.3.2
+
+* Added a `NEWS.md` file to track changes to the package.
diff --git a/R/S3.R b/R/S3.R
@@ -19,6 +19,8 @@ as.matrix.proporz_matrix = function(x, ...) {
 #' @param biproportional_result a matrix created by \code{\link{biproportional}}
 #'                              or a data.frame created by \code{\link{pukelsheim}}
 #'
+#' @returns The district and party divisors in a list
+#'
 #' @examples
 #' votes_matrix = matrix(c(51,60,63,98,100,102,45,120,144), nrow = 3)
 #' district_seats = 4:6

diff --git a/R/biproportional.R b/R/biproportional.R
@@ -37,6 +37,9 @@
 #'
 #' @seealso \code{\link{biproportional}}, \code{\link{divisors}}
 #'
+#' @returns A data.frame (like votes_df) with a new column denoting the number
+#'          seats per party and district
+#'
 #' @examples
 #' # Zug 2018
 #' votes_df = unique(zug2018[c("list_id", "entity_id", "list_votes")])
@@ -143,6 +146,9 @@ pukelsheim = function(votes_df, district_seats_df,
 #' @seealso \code{\link{pukelsheim}} for usage with data frames.
 #'          \code{\link{divisors}} to access the divisors
 #'
+#' @returns Matrix with the same dimension as \code{votes_matrix} containing
+#'          the number of seats
+#'
 #' @examples
 #' votes_df = unique(zug2018[c("list_id", "entity_id", "list_votes")])
 #' votes_matrix = pivot_to_matrix(votes_df)
@@ -277,7 +283,7 @@ biproporz = biproportional
 #'
 #' @seealso \code{\link{biproportional}}, \code{\link{lower_apportionment}}
 #'
-#' @return named list with column/district seats and row/party seats
+#' @returns A named list with column/district seats and row/party seats
 #' @export
 upper_apportionment = function(votes_matrix, district_seats,
                                use_list_votes = TRUE,
@@ -356,7 +362,7 @@ upper_apportionment = function(votes_matrix, district_seats,
 #' @note The iterative process in the lower apportionment is only guaranteed to
 #'       terminate with Sainte-Laguë/Webster method.
 #'
-#' @return seat matrix with column and row divisors stored in attributes
+#' @returns A seat matrix with column and row divisors stored in attributes
 #'
 #' @seealso \code{\link{biproportional}}, \code{\link{lower_apportionment}}
 #'

diff --git a/R/divisor.R b/R/divisor.R
@@ -14,6 +14,8 @@
 #' @param divisors sequence of divisors. If it's a single number, a sequence
 #'                 is generated starting with it.
 #'
+#' @inherit proporz return
+#'
 #' @export
 highest_averages_method = function(party_votes, n_seats, divisors) {
     check_votes_vector(party_votes, deparse(substitute(party_votes)))
@@ -53,6 +55,7 @@ highest_averages_method = function(party_votes, n_seats, divisors) {
 #' German equivalent "Höchstzahlverfahren".
 #'
 #' @inheritParams highest_averages_method
+#'
 #' @export
 hzv = function(party_votes, n_seats, divisors) {
     highest_averages_method(party_votes, n_seats, divisors)
@@ -64,7 +67,7 @@ hzv = function(party_votes, n_seats, divisors) {
 #'
 #' @inheritParams proporz
 #' @seealso \code{\link{proporz}}
-#'
+#' @inherit proporz return
 #' @export
 divisor_floor = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -79,6 +82,7 @@ divisor_floor = function(votes, n_seats, quorum = 0) {
 #'
 #' @inheritParams proporz
 #' @seealso \code{\link{proporz}}
+#' @inherit proporz return
 #' @export
 divisor_round = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -93,6 +97,7 @@ divisor_round = function(votes, n_seats, quorum = 0) {
 #'
 #' @inheritParams proporz
 #' @seealso \code{\link{proporz}}
+#' @inherit proporz return
 #' @export
 divisor_harmonic = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -111,6 +116,7 @@ divisor_harmonic = function(votes, n_seats, quorum = 0) {
 #'
 #' @inheritParams proporz
 #' @seealso \code{\link{proporz}}
+#' @inherit proporz return
 #' @export
 divisor_geometric = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))
@@ -129,6 +135,7 @@ divisor_geometric = function(votes, n_seats, quorum = 0) {
 #'
 #' @inheritParams proporz
 #' @seealso \code{\link{proporz}}
+#' @inherit proporz return
 #' @export
 divisor_ceiling = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))

diff --git a/R/methods.R b/R/methods.R
@@ -3,6 +3,7 @@
 #' Names can be used in [proporz()] or [biproportional()], the list entries
 #' denote the actual implementation.
 #'
+#' @details
 #' \code{list(
 #' "divisor_floor" = "floor",
 #' "d'hondt" = "floor",
@@ -27,6 +28,7 @@
 #' "quota_largest_remainder" = "quota_largest_remainder"
 #' )}
 #'
+#' @returns Named list of methods
 #' @export
 apport_methods = list(
     "divisor_floor" = "floor",

diff --git a/R/proporz.R b/R/proporz.R
@@ -21,6 +21,8 @@
 #'          \item{huntington-hill, hill-huntington, geometric (use \code{\link{divisor_geometric}})}
 #'          \item{hare-niemeyer, hamilton, vinton, quota_largest_remainder (use \code{\link{quota_largest_remainder}})}
 #' }
+#' @returns The number of seats per party as a vector
+#'
 #' @examples
 #' votes = c("Party A" = 651, "Party B" = 349, "Party C" = 50)
 #'

diff --git a/R/quota.R b/R/quota.R
@@ -4,6 +4,7 @@
 #'
 #' @inheritParams proporz
 #' @seealso \code{\link{proporz}}
+#' @inherit proporz return
 #' @export
 quota_largest_remainder = function(votes, n_seats, quorum = 0) {
     check_votes_vector(votes, deparse(substitute(votes)))

diff --git a/R/shinyapp.R b/R/shinyapp.R
@@ -4,10 +4,10 @@
 #'
 #' @param votes_matrix optional votes_matrix to load upon start
 #' @param district_seats optional district_seats to load upon start
-#'
+#' @returns Calling the function starts the shiny app
 #' @examples
 #' if(interactive()){
-#'     # You need to have shiny and shinyMatrix installed to run the app
+#'     # You need to have the packages 'shiny' and 'shinyMatrix' installed to run the app
 #'     run_app()
 #'
 #'     # It's possible to load a matrix with the app

diff --git a/R/utils.R b/R/utils.R
@@ -26,6 +26,7 @@ bisect = function(f, x1, x2, tol = 1e-9) {
 #' @note This function exists because I wanted to have no dependencies.
 #'       Wrangling with reshape isn't fun at all and it became glaringly
 #'       apparent why better tools like tidyr exist
+#' @returns a matrix
 #' @export
 pivot_to_matrix = function(df) {
     stopifnot(ncol(df) == 3)
@@ -39,7 +40,7 @@ pivot_to_matrix = function(df) {
 #'
 #' @param matrix_wide matrix in wide format
 #' @param value_colname name for the data.frame new column
-#'
+#' @returns data.frame with 3 columns
 #' @export
 pivot_to_df = function(matrix_wide, value_colname = "values") {
     if(is.null(dimnames(matrix_wide))) {

diff --git a/README.md b/README.md
@@ -1,7 +1,8 @@
-# proporz <img src="data-raw/proporz-hexsticker.png" align="right" height="140"/>
+# proporz <img src="man/figures/logo.png" align="right" height="138" />
 
-Calculate seat apportionment for legislative bodies using different established 
-methods, including biproportional apportionment.
+Calculate seat apportionments for legislative bodies with various methods. 
+Methods inlcude divisor methods (e.g. D'Hondt, Webster or Adams), quota methods
+(e.g. largest remainder method) and biproportional apportionment.
 
 _Mit diesem R-Package können mittels verschiedener Sitzzuteilungsverfahren 
 Wählerstimmen in Abgeordnetensitze umgerechnet werden. Das Package beinhaltet 
@@ -177,7 +178,7 @@ and `shinyMatrix` installed.
 library(proporz)
 run_app()
 ```
-<img src="data-raw/shinyapp-example.gif" style = "width:70%;">
+<img src="man/figures/shinyapp-example.gif" style = "width:70%;">
 
 <br/>
 

diff --git a/data-raw/proporz-hexsticker.pdf b/data-raw/proporz-hexsticker.pdf
diff --git a/data-raw/proporz-hexsticker.png b/data-raw/proporz-hexsticker.png
diff --git a/man/apport_methods.Rd b/man/apport_methods.Rd
diff --git a/man/biproportional.Rd b/man/biproportional.Rd
diff --git a/man/biproporz.Rd b/man/biproporz.Rd
diff --git a/man/divisor_ceiling.Rd b/man/divisor_ceiling.Rd
diff --git a/man/divisor_floor.Rd b/man/divisor_floor.Rd
diff --git a/man/divisor_geometric.Rd b/man/divisor_geometric.Rd
diff --git a/man/divisor_harmonic.Rd b/man/divisor_harmonic.Rd
diff --git a/man/divisor_round.Rd b/man/divisor_round.Rd
diff --git a/man/divisors.Rd b/man/divisors.Rd
diff --git a/man/figures/logo.png b/man/figures/logo.png
diff --git a/data-raw/shinyapp-example.gif → man/figures/shinyapp-example.gif b/data-raw/shinyapp-example.gif → man/figures/shinyapp-example.gif
diff --git a/man/highest_averages_method.Rd b/man/highest_averages_method.Rd
diff --git a/man/lower_apportionment.Rd b/man/lower_apportionment.Rd
diff --git a/man/pivot_to_df.Rd b/man/pivot_to_df.Rd
diff --git a/man/pivot_to_matrix.Rd b/man/pivot_to_matrix.Rd
diff --git a/man/proporz.Rd b/man/proporz.Rd
diff --git a/man/pukelsheim.Rd b/man/pukelsheim.Rd
diff --git a/man/quota_largest_remainder.Rd b/man/quota_largest_remainder.Rd
diff --git a/man/run_app.Rd b/man/run_app.Rd
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# proporz 1.3.2

		* Added a `NEWS.md` file to track changes to the package.