✨ Initial commit for branch "dev_massey_duncan" (ndi v0.1.6.9011) (#28)

* Added `massey_duncan()` function to compute the aspatial racial or ethnic Absolute Concentration (*ACO*) based on [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281) and Duncan, Cuzzort, & Duncan (1961; LC:60007089)

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: ndi
 Title: Neighborhood Deprivation Indices
-Version: 0.1.6.9010
-Date: 2024-08-30
+Version: 0.1.6.9011
+Date: 2024-08-31
 Authors@R:
     c(person(given = "Ian D.",
              family = "Buller",

NAMESPACE

@@ -15,6 +15,7 @@ export(james_taeuber)
 export(krieger)
 export(lieberson)
 export(massey)
+export(massey_duncan)
 export(messer)
 export(powell_wiley)
 export(sudano)

NEWS.md

@@ -1,6 +1,6 @@
 # ndi (development version)
 
-## ndi v0.1.6.9010
+## ndi v0.1.6.9011
 
 ### New Features
 
@@ -15,9 +15,10 @@
 * Added `denton()` function to compute the aspatial racial or ethnic Relative Clustering (*RCL*) based on [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
 * Added `duncan_duncan()` function to compute the aspatial racial or ethnic Relative Centralization (*RCE*) based on [Duncan & Duncan (1955b)](https://doi.org/10.1086/221609) and [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
 * Added `massey()` function to compute the aspatial racial or ethnic Absolute Clustering (*ACL*) based on [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
+* Added `massey_duncan()` function to compute the aspatial racial or ethnic Absolute Concentration (*ACO*) based on [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281) and Duncan, Cuzzort, & Duncan (1961; LC:60007089)
 
 #### New Function Capabilities
-* Added `geo_large = 'place'` for census-designated places, `geo_large = 'cbsa'` for core-based statistical areas, `geo_large = 'csa'` for combined statistical areas, and `geo_large = 'metro'` for metropolitan divisions as the larger geographical unit in `atkinson()`, `bell()`, `bemanian_beyer()`, `denton()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `sudano()`, `theil()`, and `white()`, `white_blau()` functions.
+* Added `geo_large = 'place'` for census-designated places, `geo_large = 'cbsa'` for core-based statistical areas, `geo_large = 'csa'` for combined statistical areas, and `geo_large = 'metro'` for metropolitan divisions as the larger geographical unit in `atkinson()`, `bell()`, `bemanian_beyer()`, `denton()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `sudano()`, `theil()`, and `white()`, `white_blau()` functions.
 * Added census block group computation for `anthopolos()` by specifying `geo == 'cbg'` or `geo == 'block group'`
 * Added `holder` argument to `atkinson()` function to toggle the computation with or without the Hölder mean. The function can now compute *A* without the Hölder mean. The default is `holder = FALSE`.
 * Added `crs` argument to `anthopolos()`, `bravo()`, and `white_blau()` functions to provide spatial projection of the distance-based metrics
@@ -43,7 +44,7 @@
 * Re-formatted code and documentation throughout for consistent readability
 * Renamed 'race/ethnicity' or 'racial/ethnic' to 'race or ethnicity' or 'racial or ethnic' throughout documentation to use more modern, inclusive, and appropriate language
 * Updated documentation about value range of *V* (White) from `{0 to 1}` to `{-Inf to Inf}`
-* Added examples for `atkinson()`, `duncan_cuzzort()`, `duncan_duncan()`, `gini()`, `hoover()`, `james_taeuber()`, `lieberson()`, `theil()`, and `white_blau()` functions in vignettes and README
+* Added examples for `atkinson()`, `duncan_cuzzort()`, `duncan_duncan()`, `gini()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `theil()`, and `white_blau()` functions in vignettes and README
 * Added example for `holder` argument in `atkinson()` function in README
 * Reordered the contents of 'ndi-package.R' thematically
 * Reordered the README examples alphabetically

R/globals.R

@@ -271,6 +271,12 @@ globalVariables(
     'crs',
     'RCE',
     'ACL',
-    'RCL'
+    'RCL',
+    'ACO',
+    'ALAND',
+    'TotalPopE',
+    'n_1',
+    'n_2',
+    't_cs'
   )
 )

R/ndi-package.R

@@ -36,11 +36,11 @@
 #'
 #' \code{\link{james_taeuber}} Computes the aspatial Dissimilarity Index (\emph{D}) based on James & Taeuber (1985) \doi{10.2307/270845}.
 #' 
-#' \code{\link{krieger}} Computes the aspatial Index of Concentration at the Extremes based on Feldman et al. (2015) \doi{10.1136/jech-2015-205728} and Krieger et al. (2016) \doi{10.2105/AJPH.2015.302955}.
-#' 
 #' \code{\link{lieberson}} Computes the aspatial Isolation Index (\emph{xPx\*}) based on Lieberson (1981; ISBN-13:978-1-032-53884-6) and Bell (1954) \doi{10.2307/2574118}.
 #' 
 #' \code{\link{massey}} Computes the aspatial Absolute Clustering (\emph{ACL}) based on Massey & Denton (1988) \doi{10.1093/sf/67.2.281}.
+#' 
+#' \code{\link{massey_duncan}} Computes the aspatial Absolute Concentration (\emph{ACO}) based on Massey & Denton (1988) \doi{10.1093/sf/67.2.281} and Duncan, Cuzzort, & Duncan (1961; LC:60007089).
 #'
 #' \code{\link{sudano}} Computes the aspatial Location Quotient (\emph{LQ}) based on Merton (1939) \doi{10.2307/2084686} and Sudano et al. (2013) \doi{10.1016/j.healthplace.2012.09.015}.
 #' 
@@ -58,6 +58,8 @@
 #' 
 #' \code{\link{gini}} Also retrieves the aspatial Gini Index (\emph{G}) of income inequality based on Gini (1921) \doi{10.2307/2223319}.
 #' 
+#' \code{\link{krieger}} Computes the aspatial Index of Concentration at the Extremes based on Feldman et al. (2015) \doi{10.1136/jech-2015-205728} and Krieger et al. (2016) \doi{10.2105/AJPH.2015.302955}.
+#' 
 #' \strong{Pre-formatted U.S. Census Data}
 #' 
 #' \code{\link{DCtracts2020}} A sample dataset containing information about U.S. Census American Community Survey 5-year estimate data for the District of Columbia census tracts (2020). The data are obtained from the \code{\link[tidycensus]{get_acs}} function and formatted for the \code{\link{messer}} and \code{\link{powell_wiley}} functions input.

R/utils.R

@@ -397,3 +397,73 @@ rcl_fun <- function(x, crs, omit_NAs) {
     return(RCL)
   }
 }
+
+# Internal function for Absolute Concentration
+## From Denton & Massey (1988) https://doi.org/10.1093/sf/67.2.281
+## Returns NA value if only one smaller geography in a larger geography
+aco_fun <- function(x, omit_NAs) {
+  # x <- out_tmp[[12]]
+  xx <- x[ , c('TotalPopE', 'subgroup', 'ALAND')]
+  if (omit_NAs == TRUE) { xx <- xx[stats::complete.cases(sf::st_drop_geometry(xx)), ] }
+  if (nrow(sf::st_drop_geometry(x)) < 2 || any(sf::st_drop_geometry(xx) < 0) || any(is.na(sf::st_drop_geometry(xx)))) {
+    NA
+  } else {
+    a_i <- xx$ALAND
+    x_i <- xx$subgroup
+    X <- sum(x_i, na.rm = TRUE)
+    xx_tmp <- xx %>% 
+      sf::st_drop_geometry(xx) %>%
+      dplyr::arrange(ALAND) %>%
+      dplyr::mutate(
+        t_cs = cumsum(TotalPopE),
+        n_1 = t_cs <= X,
+      ) 
+    if (!(TRUE %in% xx_tmp$n_1)) { 
+      xx_1 <- xx_tmp %>% 
+        dplyr::slice(1) 
+    } else {
+      xx_1 <- xx_tmp %>%
+        dplyr::filter(n_1 == TRUE)
+    }
+    if (nrow(xx_1) == 1 & 0 %in% xx_1$TotalPopE) { 
+      xx_1 <- xx_tmp %>%
+        dplyr::filter(TotalPopE > 0) %>%
+        dplyr::slice(1) 
+    }
+    T_1 <- xx_1 %>%
+      dplyr::summarise(
+        T_1 = sum(TotalPopE)
+      ) %>%
+      unlist()
+    xx_tmp <- xx %>% 
+      sf::st_drop_geometry(xx) %>%
+      dplyr::arrange(-ALAND) %>%
+      dplyr::mutate(
+        t_cs = cumsum(TotalPopE),
+        n_2 = t_cs <= X,
+      )
+    if (!(TRUE %in% xx_tmp$n_2)) { 
+      xx_2 <- xx_tmp %>% 
+        dplyr::slice(1) 
+    } else {
+      xx_2 <- xx_tmp %>%
+        dplyr::filter(n_2 == TRUE)
+    }
+    if (nrow(xx_2) == 1 & 0 %in% xx_2$TotalPopE) { 
+      xx_2 <- xx_tmp %>%
+        dplyr::filter(TotalPopE > 0) %>%
+        dplyr::slice(1) 
+    }
+    T_2 <- xx_2 %>%
+      dplyr::summarise(
+        T_2 = sum(TotalPopE)
+      ) %>%
+      unlist()
+    num <- sum((x_i * a_i) / X, na.rm = TRUE) - sum((xx_1$TotalPopE * xx_1$ALAND) / T_1, na.rm = TRUE) 
+    denom <- sum((xx_2$TotalPopE * xx_2$ALAND) / T_2, na.rm = TRUE) - sum((xx_1$TotalPopE * xx_1$ALAND) / T_1, na.rm = TRUE) 
+    ACO_tmp <- (num / denom)
+    if (is.infinite(ACO_tmp) | is.na(ACO_tmp)) { ACO_tmp <- 0 }
+    ACO <- 1 - ACO_tmp
+    return(ACO)
+  }
+}

README.md

@@ -12,7 +12,7 @@
 [![DOI](https://zenodo.org/badge/521439746.svg)](https://zenodo.org/badge/latestdoi/521439746)
 <!-- badges: end -->
 
-**Date repository last updated**: 2024-08-30
+**Date repository last updated**: 2024-08-31
 
 ### Overview
 
@@ -103,6 +103,10 @@ To install the development version from GitHub:
 <td>Compute the aspatial racial or ethnic Absolute Clustering (<i>ACL</i>) based on <a href='https://doi.org/10.1093/sf/67.2.281'>Massey & Denton (1988)</a></td>
 </tr>
 <tr>
+<td><a href='/R/massey_duncan.R'><code>massey_duncan</code></a></td>
+<td>Compute the aspatial racial or ethnic Absolute Concentration (<i>ACO</i>) based on <a href='https://doi.org/10.1093/sf/67.2.281'>Massey & Denton (1988)</a> and Duncan, Cuzzort, & Duncan (1961; LC:60007089)</td>
+</tr>
+<tr>
 <td><a href='/R/messer.R'><code>messer</code></a></td>
 <td>Compute the aspatial Neighborhood Deprivation Index (<i>NDI</i>) based on <a href='https://doi.org/10.1007/s11524-006-9094-x'>Messer et al. (2006)</a></td>
 </tr>
@@ -1368,6 +1372,51 @@ ggplot() +
 
 ![](man/figures/acl.png)
 
+```r
+# --------------------------------------------------------- #
+# Compute aspatial Absolute Concentration (Massey & Denton) #
+# --------------------------------------------------------- #
+
+# Absolute Concentration based on Massey & Denton (1988) and Duncan, Cuzzort, & Duncan (1961)
+## Selected subgroup: Not Hispanic or Latino, Black or African American alone
+## Selected large geography: census tract
+## Selected small geography: census block group
+ACO_2020_DC <- massey_duncan(
+  geo_large = 'tract',
+  geo_small = 'cbg',
+  state = 'DC',
+  year = 2020,
+  subgroup = 'NHoLB'
+)
+
+# Obtain the 2020 census tracts from the 'tigris' package
+tract_2020_DC <- tracts(state = 'DC', year = 2020, cb = TRUE)
+
+# Join the ACO (Massey & Denton) values to the census tract geometry
+ACO_2020_DC <- tract_2020_DC %>%
+  left_join(ACO_2020_DC$aco, by = 'GEOID')
+
+ggplot() +
+  geom_sf(
+    data = ACO_2020_DC,
+    aes(fill = ACO),
+    color = 'white'
+  ) +
+  theme_bw() +
+  scale_fill_viridis_c(limits = c(0, 1)) +
+  labs(
+    fill = 'Index (Continuous)',
+    caption = 'Source: U.S. Census ACS 2016-2020 estimates'
+  ) +
+  ggtitle(
+    'Absolute Concentration (Massey & Denton)\n
+    Washington, D.C. census block groups to tracts',
+    subtitle = 'Black non-Hispanic'
+  )
+```
+
+![](man/figures/aco.png)
+
 ```r
 # ------------------------------------------------------------ #
 # Compute aspatial racial or ethnic Location Quotient (Sudano) #

cran-comments.md

@@ -8,9 +8,10 @@
   * Added `james_taeuber()` function to compute the aspatial racial or ethnic Dissimilarity Index (*D*) based on [James & Taeuber (1985)](https://doi.org/10.2307/270845)
   * Added `lieberson()` function to compute the aspatial racial or ethnic Isolation Index (_xPx\*_) based on Lieberson (1981; ISBN-13:978-1-032-53884-6) and and [Bell (1954)](https://doi.org/10.2307/2574118)
   * Added `massey()` function to compute the aspatial racial or ethnic Absolute Clustering (*ACL*) based on [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
+  * Added `massey_duncan()` function to compute the aspatial racial or ethnic Absolute Concentration (*ACO*) based on [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281) and Duncan, Cuzzort, & Duncan (1961; LC:60007089)
   * Added `theil()` function the aspatial racial or ethnic Entropy (*H*) based on Theil (1972; ISBN:978-0-444-10378-9) and [Theil & Finizza (1971)](https://doi.org/110.1080/0022250X.1971.9989795)
   * Added `white_blau()` function to compute an index of spatial proximity (*SP*) based on [White (1986)](https://doi.org/10.2307/3644339) and Blau (1977; ISBN-13:978-0-029-03660-0)
-  * Added `geo_large = 'place'` for census-designated places, `geo_large = 'cbsa'` for core-based statistical areas, `geo_large = 'csa'` for combined statistical areas, and `geo_large = 'metro'` for metropolitan divisions as the larger geographical unit in `atkinson()`, `bell()`, `bemanian_beyer()`, `denton()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `sudano()`, `theil()`, and `white()`, `white_blau()` functions.
+  * Added `geo_large = 'place'` for census-designated places, `geo_large = 'cbsa'` for core-based statistical areas, `geo_large = 'csa'` for combined statistical areas, and `geo_large = 'metro'` for metropolitan divisions as the larger geographical unit in `atkinson()`, `bell()`, `bemanian_beyer()`, `denton()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `sudano()`, `theil()`, and `white()`, `white_blau()` functions.
   * Added census block group computation for `anthopolos()` by specifying `geo == 'cbg'` or `geo == 'block group'`
   * Added `holder` argument to `atkinson()` function to toggle the computation with or without the Hölder mean. The function can now compute *A* without the Hölder mean. The default is `holder = FALSE`.
   * Added `crs` argument to `anthopolos()`, `bravo()`, and `white_blau()` functions to provide spatial projection of the distance-based metrics
@@ -28,7 +29,7 @@
   * Renamed 'race/ethnicity' or 'racial/ethnic' to 'race or ethnicity' or 'racial or ethnic' throughout documentation to use more modern, inclusive, and appropriate language
   * Updated documentation about value range of *V* (White) from `{0 to 1}` to `{-Inf to Inf}`
   * Split up vignette into three separate vignettes: 'ndi1', 'ndi2', and 'ndi3' for the *NDI*, racial or ethnic residential segregation, and additional socioeconomic disparity indices, respectively
-  * Added examples for `atkinson()`, `duncan_cuzzort()`, `duncan_duncan()`, `gini()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `theil()`, and `white_blau()` functions in vignettes and README
+  * Added examples for `atkinson()`, `duncan_cuzzort()`, `duncan_duncan()`, `gini()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `theil()`, and `white_blau()` functions in vignettes and README
   * Added example for `holder` argument in `atkinson()` function in README
   * Reordered the README examples alphabetically
   * Reordered the vignette examples to group the racial or ethnic residential segregation indices
@@ -45,7 +46,7 @@
   * <https://doi.org/10.2307/3644339>
   * <https://doi.org/10.2307/2084686>
 
-* Some tests and examples for `anthopolos()`, `atkinson()`, `bell()`, `bemanian_beyer()`, `bravo()`, `denton()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `gini()`, `hoover()`, `james_taeuber()`, `krieger()`, `lieberson()`, `massey()`, `messer()`, `powell_wiley()`, `sudano()`, `theil()`, `white()`, and `white_blau()` functions require a Census API key so they are skipped if NULL or not run
+* Some tests and examples for `anthopolos()`, `atkinson()`, `bell()`, `bemanian_beyer()`, `bravo()`, `denton()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `gini()`, `hoover()`, `james_taeuber()`, `krieger()`, `lieberson()`, `massey()`, `massey_duncan()`, `messer()`, `powell_wiley()`, `sudano()`, `theil()`, `white()`, and `white_blau()` functions require a Census API key so they are skipped if NULL or not run
 
 ## Test environments
 * local Windows install, R 4.4.1

inst/CITATION

@@ -3,7 +3,7 @@ bibentry(bibtype = 'manual',
   author         = as.person('Ian D. Buller'),
   publisher      = 'The Comprehensive R Archive Network',
   year           = '2024',
-  number         = '0.1.6.9010.',
+  number         = '0.1.6.9011.',
   doi            = '10.5281/zenodo.6989030',
   url            = 'https://cran.r-project.org/package=ndi',
 
@@ -422,6 +422,44 @@ bibentry(bibtype = 'Article',
   header         = 'If you computed ACL (Massey & Denton) values, please also cite:'
 )
 
+bibentry(bibtype = 'Article',
+  title          = 'The Dimensions of Residential Segregation',
+  author         = c(as.person('Douglas S. Massey'),
+                   as.person('Nancy A. Denton')),
+  journal        = 'Social Forces',
+  year           = '1988',
+  volume         = '67',
+  issue          = '2',
+  pages          = '281--315',
+  doi            = '10.1093/sf/67.2.281',
+
+  textVersion    =
+  paste('Douglas S. Massey & Nancy A. Denton (1988).',
+        'The Dimensions of Residential Segregation.',
+        'Social Forces, 67(1), 281-315.',
+        'DOI:10.1093/sf/67.2.281'),
+
+  header         = 'If you computed ACO (Massey & Denton) values, please also cite (1):'
+)
+
+bibentry(bibtype = 'Book',
+  title          = 'Statistical Geography: Problems in Analyzing Area Data',
+  author         = c(as.person('Otis D. Duncan'),
+                    as.person('Ray P. Cuzzort'),
+                    as.person('Beverly Duncan')),
+  year           = '1961',
+  publisher      = 'Free Press',
+  lc             = '60007089',
+
+  textVersion    =
+  paste('Otis D. Duncan, Ray P. Cuzzort, & Beverly Duncan (1961).',
+        'Statistical Geography: Problems in Analyzing Area Data.',
+        'Free Press',
+        'LC:60007089'),
+
+  header         = 'And (2):'
+)
+
 bibentry(bibtype = 'Article',
   title          = 'The Dimensions of Residential Segregation',
   author         = c(as.person('Douglas S. Massey'),