✨ Initial commit for branch "dev_morgan_denton" (ndi v0.1.6.9014) (#31)

* Added `morgan_denton()` function to compute the aspatial racial or ethnic Distance-Decay Interaction Index (_DPxy\*_) based on [Morgan (1983)](https://www.jstor.org/stable/20001935) and [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ndi
 Title: Neighborhood Deprivation Indices
-Version: 0.1.6.9013
+Version: 0.1.6.9014
 Date: 2024-09-02
 Authors@R:
     c(person(given = "Ian D.",

NAMESPACE

@@ -18,6 +18,7 @@ export(lieberson)
 export(massey)
 export(massey_duncan)
 export(messer)
+export(morgan_denton)
 export(morgan_massey)
 export(powell_wiley)
 export(sudano)

NEWS.md

@@ -1,6 +1,6 @@
 # ndi (development version)
 
-## ndi v0.1.6.9013
+## ndi v0.1.6.9014
 
 ### New Features
 
@@ -17,10 +17,11 @@
 * 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)
+* Added `morgan_denton()` function to compute the aspatial racial or ethnic Distance-Decay Interaction Index (_DPxy\*_) based on [Morgan (1983)](https://www.jstor.org/stable/20001935) and [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
 * Added `morgan_massey()` function to compute the aspatial racial or ethnic Distance-Decay Isolation Index (_DPxx\*_) based on [Morgan (1983)](https://www.jstor.org/stable/20001935) and [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
 
 #### 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()`, `denton_cuzzort()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `morgan_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()`, `denton_cuzzort()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `morgan_denton()`, `morgan_denton()`, `morgan_massey()`, `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

R/globals.R

@@ -283,6 +283,7 @@ globalVariables(
     'n_1',
     'n_2',
     't_cs',
-    'DPxx_star'
+    'DPxx_star',
+    'DPxy_star'
   )
 )

R/morgan_massey.R

@@ -39,7 +39,7 @@
 #'
 #' Use the internal \code{state} and \code{county} arguments within the \code{\link[tidycensus]{get_acs}} function to specify geographic extent of the data output.
 #'
-#' _DPxx\*_ is a measure of clustering of racial or ethnic populations within smaller geographical units that are located within larger geographical units. _DPxx\*_ is some measure of the probability that a member of one subgroup(s) will meet or interact with a member of another subgroup(s). _DPxx\*_ can range in value from 0 to 1 with higher values signifying higher probability of isolation (less isolation).
+#' _DPxx\*_ is a measure of clustering of racial or ethnic populations within smaller geographical units that are located within larger geographical units. _DPxx\*_ is some measure of the probability that a member of one racial or ethnic subgroup will meet or interact with a member of the same racial or ethnic subgroup. _DPxx\*_ can range in value from 0 to 1 with higher values signifying higher probability of isolation (less isolation).
 #' 
 #' The metric uses the exponential transform of a distance matrix (kilometers) between smaller geographical area centroids, with a diagonal defined as \code{(0.6*a_{i})^{0.5}} where \code{a_{i}} is the area (square kilometers) of smaller geographical unit \code{i} as defined by White (1983) \doi{10.1086/227768}.
 #'
@@ -293,7 +293,7 @@ morgan_massey <- function(geo_large = 'county',
       dplyr::mutate(subgroup = rowSums(as.data.frame(.)[, in_subgroup]))
   }
 
-  # Compute DPxx_star
+  # Compute DPxx*
   ## From Massey & Denton (1988) https://doi.org/10.1093/sf/67.2.281
   ## DP_{xx}^{*}=\sum_{i=1}^{n}\frac{x_{i}}{X}\sum_{j=1}^{n}\frac{K_{ij}x_{j}}{t_{j}}
   ## Where for i & j smaller geographical units:

R/ndi-package.R

@@ -44,6 +44,8 @@
 #' 
 #' \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{morgan_denton}} Computes the aspatial Distance-Decay Interaction Index (\emph{DPxy\*}) based on Morgan (1986) \url{https://www.jstor.org/stable/20001935} and Massey & Denton (1988) \doi{10.1093/sf/67.2.281}.
+#'
 #' \code{\link{morgan_massey}} Computes the aspatial Distance-Decay Isolation Index (\emph{DPxx\*}) based on Morgan (1986) \url{https://www.jstor.org/stable/20001935} and Massey & Denton (1988) \doi{10.1093/sf/67.2.281}.
 #' 
 #' \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}.

R/utils.R

@@ -221,7 +221,35 @@ djt_fun <- function(x, omit_NAs) {
   }
 }
 
-# Internal function for Distance Decay Isolation
+# Internal function for Distance-Decay Interaction Index
+## From Massey & Denton (1988) https://doi.org/10.1093/sf/67.2.281
+## Returns NA value if only one smaller geography with population in a larger geography
+dpxy_star_fun <- function(x, crs, omit_NAs) {
+  xx <- x %>%
+    dplyr::select(TotalPopE, subgroup, subgroup_ixn, ALAND) %>%
+    dplyr::filter(TotalPopE > 0)
+  if (omit_NAs == TRUE) { xx <- xx[stats::complete.cases(sf::st_drop_geometry(xx)), ] }
+  if (nrow(sf::st_drop_geometry(xx)) < 2 || any(sf::st_drop_geometry(xx) < 0) || any(is.na(sf::st_drop_geometry(xx)))) {
+    NA
+  } else {
+    xx <- xx %>% sf::st_transform(crs = crs)
+    x_i <- x_j <- xx$subgroup
+    X <- sum(x_i, na.rm = TRUE)
+    y_j <- xx$subgroup_ixn
+    t_j <- xx$TotalPopE
+    d_ij <- suppressWarnings(sf::st_distance(sf::st_centroid(xx), sf::st_centroid(xx)))
+    diag(d_ij) <- sqrt(0.6 * xx$ALAND)
+    c_ij <- -d_ij %>% 
+      units::set_units(value = km) %>%
+      units::drop_units() %>%
+      exp()
+    K_ij <- c_ij * t_j /  sum(c_ij * t_j, na.rm = TRUE)  
+    DPxx_star <- sum(x_i / X, na.rm = TRUE) * sum(K_ij * y_j / t_j, na.rm = TRUE)  
+    return(DPxx_star)
+  }
+}
+
+# Internal function for Distance-Decay Isolation Index
 ## From Massey & Denton (1988) https://doi.org/10.1093/sf/67.2.281
 ## Returns NA value if only one smaller geography with population in a larger geography
 dpxx_star_fun <- function(x, crs, omit_NAs) {

README.md

@@ -115,6 +115,10 @@ To install the development version from GitHub:
 <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>
 <tr>
+<td><a href='/R/morgan_denton.R'><code>morgan_denton</code></a></td>
+<td>Compute the aspatial racial or ethnic Distance-Decay Interaction Index (<i>DPxy*</i>) based on <a href='https://www.jstor.org/stable/20001935'>Morgan (1983)</a> and <a href='https://doi.org/10.1093/sf/67.2.281'>Massey & Denton (1988)</a>
+</tr>
+<tr>
 <td><a href='/R/morgan_massey.R'><code>morgan_massey</code></a></td>
 <td>Compute the aspatial racial or ethnic Distance-Decay Isolation Index (<i>DPxx*</i>) based on <a href='https://www.jstor.org/stable/20001935'>Morgan (1983)</a> and <a href='https://doi.org/10.1093/sf/67.2.281'>Massey & Denton (1988)</a>
 </tr>
@@ -1356,7 +1360,7 @@ ggplot() +
 # Compute aspatial racial or ethnic Isolation Index (Lieberson) #
 # ------------------------------------------------------------- #
 
-# Interaction Index based on Lieberson (1981) and Bell (1954)
+# Isolation Index based on Lieberson (1981) and Bell (1954)
 ## Selected subgroup: Not Hispanic or Latino, Black or African American alone
 ## Selected large geography: census tract
 ## Selected small geography: census block group
@@ -1492,6 +1496,53 @@ ggsave(file.path('man', 'figures', 'aco.png'), height = 7, width = 7)
 
 ![](man/figures/aco.png)
 
+```r
+# --------------------------------------------------------------------------- #
+# Compute aspatial racial or ethnic Distance-Decay Interaction Index (Morgan) #
+# --------------------------------------------------------------------------- #
+
+# Distance-Decay Interaction Index based on Morgan (1983) and Massey & Denton (1988)
+## Selected subgroup: Not Hispanic or Latino, Black or African American alone
+## Selected interaction subgroup: Not Hispanic or Latino, Black or African American alone
+## Selected large geography: census tract
+## Selected small geography: census block group
+DPxy_star_2020_DC <- morgan_denton(
+  geo_large = 'tract',
+  geo_small = 'cbg',
+  state = 'DC',
+  year = 2020,
+  subgroup = 'NHoLB',
+  subgroup_ixn = 'NHoLW'
+)
+
+# Obtain the 2020 census tracts from the 'tigris' package
+tract_2020_DC <- tracts(state = 'DC', year = 2020, cb = TRUE)
+
+# Join the DPxx* (Morgan) values to the census tract geometry
+DPxy_star_2020_DC <- tract_2020_DC %>%
+  left_join(DPxy_star_2020_DC$dpxy_star, by = 'GEOID')
+
+ggplot() +
+  geom_sf(
+    data = DPxy_star_2020_DC,
+    aes(fill = DPxy_star),
+    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(
+    'Distance-Decay Interaction Index (Morgan)\nCensus block groups within tracts of Washington, D.C.',
+    subtitle = 'Black non-Hispanic vs. white non-Hispanic'
+  )
+ggsave(file.path('man', 'figures', 'dpxy_star.png'), height = 7, width = 7)
+```
+
+![](man/figures/dpxy_star.png)
+
 ```r
 # ------------------------------------------------------------------------- #
 # Compute aspatial racial or ethnic Distance-Decay Isolation Index (Morgan) #

cran-comments.md

@@ -10,10 +10,11 @@
   * 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 `morgan_denton()` function to compute the aspatial racial or ethnic Distance-Decay Interaction Index (_DPxy\*_) based on [Morgan (1983)](https://www.jstor.org/stable/20001935) and [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
   * Added `morgan_massey()` function to compute the aspatial racial or ethnic Distance-Decay Isolation Index (_DPxx\*_) based on [Morgan (1983)](https://www.jstor.org/stable/20001935) and [Massey & Denton (1988)](https://doi.org/10.1093/sf/67.2.281)
   * 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()`, `denton_cuzzort()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `morgan_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()`, `denton_cuzzort()`, `duncan()`, `duncan_cuzzort()`, `duncan_duncan()`, `hoover()`, `james_taeuber()`, `lieberson()`, `massey()`, `massey_duncan()`, `morgan_denton()`, `morgan_massey()`, `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

inst/CITATION

@@ -3,15 +3,15 @@ bibentry(bibtype = 'manual',
   author         = as.person('Ian D. Buller'),
   publisher      = 'The Comprehensive R Archive Network',
   year           = '2024',
-  number         = '0.1.6.9013.',
+  number         = '0.1.6.9014.',
   doi            = '10.5281/zenodo.6989030',
   url            = 'https://cran.r-project.org/package=ndi',
 
   textVersion    = 
   paste('Ian D. Buller (2024).',
         'ndi: Neighborhood Deprivation Indices.',
         'The Comprehensive R Archive Network.',
-        'v0.1.6.9013.',
+        'v0.1.6.9014.',
         'DOI:10.5281/zenodo.6989030',
         'Accessed by: https://cran.r-project.org/package=ndi'),
 
@@ -460,6 +460,45 @@ bibentry(bibtype = 'Book',
   header         = 'And (2):'
 )
 
+bibentry(bibtype = 'Article',
+  title          = 'A Distance-Decay Based Interaction Index to Measure Residential Segregation',
+  author         = as.person('Barrie S. Morgan'),
+  journal        = 'Area',
+  year           = '1983',
+  volume         = '15',
+  issue          = '4',
+  pages          = '211--217',
+  url            = 'https://www.jstor.org/stable/20001935',
+
+  textVersion    =
+  paste('Barrie S. Morgan (1983).',
+        'A Distance-Decay Based Interaction Index to Measure Residential Segregation.',
+        'Area, 15(4), 211-217.',
+        'https://www.jstor.org/stable/20001935'),
+
+  header         = 'If you computed DPxy* (Morgan) values, please also cite (1):'
+)
+
+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         = 'And (2):'
+)
+
 bibentry(bibtype = 'Article',
   title          = 'A Distance-Decay Based Interaction Index to Measure Residential Segregation',
   author         = as.person('Barrie S. Morgan'),