Add RelativeRepresentation function

DescriptiveRepresentationCalculator/NAMESPACE

@@ -3,4 +3,5 @@
 export(ExpectedRepresentation)
 export(ObservedRepresentation)
 export(SDRepresentation)
+export(RelativeRepresentation)
 importFrom(stats,rmultinom)

DescriptiveRepresentationCalculator/R/RelativeRep.R

@@ -0,0 +1,56 @@
+#' Compute relative representation compared to random sampling
+#'
+#' Calculates the difference between observed and expected representation.
+#' Optionally standardizes this difference using the standard deviation of
+#' representation under the random sampling model.
+#'
+#' @usage
+#' RelativeRepresentation(BodyMemberCharacteristics,
+#'                        PopShares,
+#'                        a = -0.5, b = 1,
+#'                        standardize = FALSE,
+#'                        nMonte = 10000)
+#'
+#' @param BodyMemberCharacteristics A vector specifying characteristics for each
+#' member of a political body.
+#' @param PopShares A numeric vector of population group proportions. Names must
+#' correspond to identities in `BodyMemberCharacteristics`.
+#' @param a, b Parameters controlling the affine transformation of the
+#' representation index, passed to `ObservedRepresentation` and
+#' `ExpectedRepresentation`.
+#' @param standardize Logical. If `TRUE`, the difference between observed and
+#' expected representation is divided by the standard deviation of representation
+#' under random sampling.
+#' @param nMonte A positive integer denoting number of Monte Carlo iterations used
+#' for estimating the standard deviation when `standardize = TRUE`.
+#'
+#' @return A scalar giving the difference between observed and expected
+#' representation. If `standardize = TRUE`, the difference is divided by the
+#' standard deviation under the random sampling model.
+#' @seealso \code{\link{ObservedRepresentation}},
+#'          \code{\link{ExpectedRepresentation}},
+#'          \code{\link{SDRepresentation}}
+#' @export
+#' @md
+RelativeRepresentation <- function(BodyMemberCharacteristics,
+                                   PopShares,
+                                   a = -0.5, b = 1,
+                                   standardize = FALSE,
+                                   nMonte = 10000){
+  ObsRep <- ObservedRepresentation(BodyMemberCharacteristics = BodyMemberCharacteristics,
+                                   PopShares = PopShares,
+                                   a = a, b = b)
+  BodyN <- length(BodyMemberCharacteristics)
+  ExpRep <- ExpectedRepresentation(PopShares = PopShares,
+                                   BodyN = BodyN,
+                                   a = a, b = b)
+  RelRep <- ObsRep - ExpRep
+  if(standardize){
+    SDRep <- SDRepresentation(PopShares = PopShares,
+                              BodyN = BodyN,
+                              a = a, b = b,
+                              nMonte = nMonte)
+    RelRep <- RelRep / SDRep
+  }
+  return(RelRep)
+}

DescriptiveRepresentationCalculator/tests/testthat/test-calculations.R

@@ -36,3 +36,21 @@ test_that("SDRepresentation is close to theoretical value", {
                              nMonte = 10000)
   expect_equal(sd_val, 0.07904785, tolerance = 0.005)
 })
+
+# RelativeRepresentation ------------------------------------------------------
+
+test_that("RelativeRepresentation returns difference", {
+  expect_equal(
+    RelativeRepresentation(body_chars, pop_shares),
+    0.01848529,
+    tolerance = 1e-6
+  )
+})
+
+test_that("RelativeRepresentation standardized is reasonable", {
+  set.seed(123)
+  val <- RelativeRepresentation(body_chars, pop_shares,
+                                standardize = TRUE,
+                                nMonte = 10000)
+  expect_equal(val, 0.2338494, tolerance = 0.05)
+})

README.md

@@ -41,7 +41,9 @@ How much representation *should* we expect in a political body, given the compos
 ## Main Package Functions<a id="functions"></a>
 **Characterizing Expected Representation:** Among other things, this package provides a function, `ExpectedRepresentation`, that calculates the degree of representation under random sampling, where, by default, representation is calculated using the Rose Index of Proportionality. This quantifies the value of descriptive representation we should expect in a political body, given population and body characteristics. 
 
-**Characterizing Representation Variability:** The package contains another function, `SDRepresentation`, that calculates the degree of representation we would expect not to be explained by the average discrepancy value; this quantity is the standard deviation of the Rose Index of Proportionality under the random sampling model. It captures how much uncertainty we would expect over the expected representation value under the random sampling model. 
+**Characterizing Representation Variability:** The package contains another function, `SDRepresentation`, that calculates the degree of representation we would expect not to be explained by the average discrepancy value; this quantity is the standard deviation of the Rose Index of Proportionality under the random sampling model. It captures how much uncertainty we would expect over the expected representation value under the random sampling model.
+
+**Quantifying Relative Representation:** `RelativeRepresentation` compares the observed representation in a body to its expected value under random sampling. It optionally standardizes this difference by the variability captured through `SDRepresentation`.
 
 **Characterizing Observed Representation:** The package contains third function, `ObservedRepresentation`, that computes the Rose Index of Proportionality using observed data. Observed representation index scores can be compared against the expected value of the index under random sampling and also against the variability of observed represenation under that model. 
 
@@ -138,7 +140,7 @@ print(ExpectedRep_CI) # -> 0.736855 1.048397
 
 ## Other Package Uses<a id="uses"></a>
 There are several other ways in which this package could be helpful in practice: 
-- *Quantifying expected and observed descriptive representation:* If you want to explain what determines descriptive representation outcomes, you can use the package to compute relative representation---i.e., the level of representation relative to what we would expect based on random sampling alone. We'll add a function which quantifies this in a future release, but can be calculated using the quantities output from this package now. 
+- *Quantifying expected and observed descriptive representation:* If you want to explain what determines descriptive representation outcomes, you can use the package to compute relative representation---i.e., the level of representation relative to what we would expect based on random sampling alone. The `RelativeRepresentation` function computes this quantity directly.
 - *Control variable creation:* In other situations, researchers may want to use the expected degree of representation under the random sampling model in order to control for compositional factors such as body size and population composition. This expected representation measure is a direct quantification of how those factors should, under the random sampling model, affect representation and therefore is a useful control variable. 
 
 ## Feature Requests & Development Plan