atkinson: Atkinson Index based on Atkinson (1970)

View source: R/atkinson.R

atkinsonR Documentation

Atkinson Index based on Atkinson (1970)

Description

Compute the aspatial Atkinson Index of income or selected racial or ethnic subgroup(s) and U.S. geographies.

Usage

atkinson(
  geo_large = "county",
  geo_small = "tract",
  year = 2020,
  subgroup,
  epsilon = 0.5,
  holder = FALSE,
  omit_NAs = TRUE,
  quiet = FALSE,
  ...
)

Arguments

geo_large

Character string specifying the larger geographical unit of the data. The default is counties geo_large = 'county'.

geo_small

Character string specifying the smaller geographical unit of the data. The default is census tracts geo_small = 'tract'.

year

Numeric. The year to compute the estimate. The default is 2020, and the years 2009 onward are currently available.

subgroup

Character string specifying the income or racial or ethnic subgroup(s) as the comparison population. See Details for available choices.

epsilon

Numerical. Shape parameter that denotes the aversion to inequality. Value must be between 0 and 1.0 (the default is 0.5).

holder

Logical. If TRUE, will compute index using the Hölder mean. If FALSE, will not compute with the Hölder mean. The default is FALSE.

omit_NAs

Logical. If FALSE, will compute index for a larger geographical unit only if all of its smaller geographical units have values. The default is TRUE.

quiet

Logical. If TRUE, will display messages about potential missing census information. The default is FALSE.

...

Arguments passed to get_acs to select state, county, and other arguments for census characteristics

Details

This function will compute the aspatial Atkinson Index (A) of income or selected racial or ethnic subgroups and U.S. geographies for a specified geographical extent (e.g., the entire U.S. or a single state) based on Atkinson (1970) \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/0022-0531(70)90039-6")}. This function provides the computation of A for median household income and any of the U.S. Census Bureau race or ethnicity subgroups (including Hispanic and non-Hispanic individuals).

The function uses the get_acs function to obtain U.S. Census Bureau 5-year American Community Survey characteristics used for the aspatial computation. The yearly estimates are available for 2009 onward when ACS-5 data are available (2010 onward for geo_large = 'cbsa' and 2011 onward for geo_large = 'place', geo_large = 'csa', or geo_large = 'metro') but may be available from other U.S. Census Bureau surveys. When subgroup = 'MedHHInc', the metric will be computed for median household income ('B19013_001') using the Hölder mean. The twenty racial or ethnic subgroups (U.S. Census Bureau definitions) are:

  • B03002_002: not Hispanic or Latino 'NHoL'

  • B03002_003: not Hispanic or Latino, white alone 'NHoLW'

  • B03002_004: not Hispanic or Latino, Black or African American alone 'NHoLB'

  • B03002_005: not Hispanic or Latino, American Indian and Alaska Native alone 'NHoLAIAN'

  • B03002_006: not Hispanic or Latino, Asian alone 'NHoLA'

  • B03002_007: not Hispanic or Latino, Native Hawaiian and Other Pacific Islander alone 'NHoLNHOPI'

  • B03002_008: not Hispanic or Latino, Some other race alone 'NHoLSOR'

  • B03002_009: not Hispanic or Latino, Two or more races 'NHoLTOMR'

  • B03002_010: not Hispanic or Latino, Two races including Some other race 'NHoLTRiSOR'

  • B03002_011: not Hispanic or Latino, Two races excluding Some other race, and three or more races 'NHoLTReSOR'

  • B03002_012: Hispanic or Latino 'HoL'

  • B03002_013: Hispanic or Latino, white alone 'HoLW'

  • B03002_014: Hispanic or Latino, Black or African American alone 'HoLB'

  • B03002_015: Hispanic or Latino, American Indian and Alaska Native alone 'HoLAIAN'

  • B03002_016: Hispanic or Latino, Asian alone 'HoLA'

  • B03002_017: Hispanic or Latino, Native Hawaiian and Other Pacific Islander alone 'HoLNHOPI'

  • B03002_018: Hispanic or Latino, Some other race alone 'HoLSOR'

  • B03002_019: Hispanic or Latino, Two or more races 'HoLTOMR'

  • B03002_020: Hispanic or Latino, Two races including Some other race 'HoLTRiSOR'

  • B03002_021: Hispanic or Latino, Two races excluding Some other race, and three or more races 'HoLTReSOR'

Use the internal state and county arguments within the get_acs function to specify geographic extent of the data output.

A is a measure of the evenness of residential inequality (e.g., racial or ethnic segregation) when comparing smaller geographical units to larger ones within which the smaller geographical units are located. A can range in value from 0 to 1 with smaller values indicating lower levels of inequality (e.g., less segregation).

The epsilon argument that determines how to weight the increments to inequality contributed by different proportions of the Lorenz curve. A user must explicitly decide how heavily to weight smaller geographical units at different points on the Lorenz curve (i.e., whether the index should take greater account of differences among units of over- or under-representation). The epsilon argument must have values between 0 and 1.0. For 0 <= epsilon < 0.5 or less 'inequality-averse,' smaller geographical units with a subgroup proportion smaller than the subgroup proportion of the larger geographical unit contribute more to inequality ('over-representation'). For 0.5 < epsilon <= 1.0 or more 'inequality-averse,' smaller geographical units with a subgroup proportion larger than the subgroup proportion of the larger geographical unit contribute more to inequality ('under-representation'). If epsilon = 0.5 (the default), units of over- and under-representation contribute equally to the index. See Section 2.3 of Saint-Jacques et al. (2020) \Sexpr[results=rd]{tools:::Rd_expr_doi("10.48550/arXiv.2002.05819")} for one method to select epsilon.

Larger geographical units available include states geo_large = 'state', counties geo_large = 'county', census tracts geo_large = 'tract', census-designated places geo_large = 'place', core-based statistical areas geo_large = 'cbsa', combined statistical areas geo_large = 'csa', and metropolitan divisions geo_large = 'metro'. Smaller geographical units available include, counties geo_small = 'county', census tracts geo_small = 'tract', and census block groups geo_small = 'cbg'. If a larger geographical unit is comprised of only one smaller geographical unit (e.g., a U.S county contains only one census tract), then the A value returned is NA. If the larger geographical unit is census-designated places geo_large = 'place', core-based statistical areas geo_large = 'cbsa', combined statistical areas geo_large = 'csa', or metropolitan divisions geo_large = 'metro', only the smaller geographical units completely within a larger geographical unit are considered in the A computation (see internal st_within function for more information) and recommend specifying all states within which the interested larger geographical unit are located using the internal state argument to ensure all appropriate smaller geographical units are included in the A computation.

Value

An object of class 'list'. This is a named list with the following components:

a

An object of class 'tbl' for the GEOID, name, and A at specified larger census geographies.

a_data

An object of class 'tbl' for the raw census values at specified smaller census geographies.

missing

An object of class 'tbl' of the count and proportion of missingness for each census variable used to compute A.

References

Atkinson, AB (1970) On the Measurement of Inequality. Journal of Economic Theory, 2(3):244-263. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/0022-0531(70)90039-6")}

James, D, & Taeuber, KE (1985) Measures of Segregation. Sociological Methodology, 15:1-32. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.2307/270845")}

Massey, DS, & Denton, NA (1988) The Dimensions of Residential Segregation. Social Forces, 67(1):281-315. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/sf/67.2.281")}

See Also

get_acs for additional arguments for geographic extent selection (i.e., state and county).

Other one-group evenness indices: gini, james_taeuber, sudano, theil

Between groups dissimilarity indices: duncan

Examples

## Not run: 
# Wrapped in \dontrun{} because these examples require a Census API key.

  # Atkinson Index (a measure of the evenness) 
  ## of Black populations
  ## in census tracts within counties of Georgia, U.S.A. (2020)
  atkinson(
    geo_large = 'county',
    geo_small = 'tract',
    state = 'GA',
    year = 2020,
    subgroup = c('NHoLB', 'HoLB')
  )
 
  # Atkinson Index (a measure of the evenness) 
  ## of median household income
  ## in census tracts within counties of Georgia, U.S.A. (2020)
  atkinson(
    geo_large = 'county',
    geo_small = 'tract',
    state = 'GA',
    year = 2020,
    subgroup = 'MedHHInc'
  )


## End(Not run)


ndi documentation built on Sept. 9, 2025, 5:26 p.m.