From 389c547f2b0e41a02faf747f2f58fd9db1d10c63 Mon Sep 17 00:00:00 2001 From: Benjamin Elbers Date: Thu, 14 Jun 2018 11:01:36 +0200 Subject: [PATCH] add website --- NEWS.md | 6 +- README.Rmd | 9 +- docs/LICENSE-text.html | 128 ++++++++++ docs/authors.html | 131 +++++++++++ docs/docsearch.css | 148 ++++++++++++ docs/docsearch.js | 85 +++++++ docs/index.html | 238 +++++++++++++++++++ docs/link.svg | 12 + docs/news/index.html | 155 ++++++++++++ docs/pkgdown.css | 232 ++++++++++++++++++ docs/pkgdown.js | 110 +++++++++ docs/pkgdown.yml | 5 + docs/reference/entropy.html | 184 +++++++++++++++ docs/reference/index.html | 201 ++++++++++++++++ docs/reference/ipf.html | 254 ++++++++++++++++++++ docs/reference/mutual_difference.html | 323 ++++++++++++++++++++++++++ docs/reference/mutual_local.html | 230 ++++++++++++++++++ docs/reference/mutual_total.html | 254 ++++++++++++++++++++ docs/reference/mutual_within.html | 243 +++++++++++++++++++ docs/reference/schools00.html | 160 +++++++++++++ docs/reference/schools05.html | 160 +++++++++++++ docs/reference/segregation.html | 171 ++++++++++++++ render_README.R | 3 + 23 files changed, 3433 insertions(+), 9 deletions(-) create mode 100644 docs/LICENSE-text.html create mode 100644 docs/authors.html create mode 100644 docs/docsearch.css create mode 100644 docs/docsearch.js create mode 100644 docs/index.html create mode 100644 docs/link.svg create mode 100644 docs/news/index.html create mode 100644 docs/pkgdown.css create mode 100644 docs/pkgdown.js create mode 100644 docs/pkgdown.yml create mode 100644 docs/reference/entropy.html create mode 100644 docs/reference/index.html create mode 100644 docs/reference/ipf.html create mode 100644 docs/reference/mutual_difference.html create mode 100644 docs/reference/mutual_local.html create mode 100644 docs/reference/mutual_total.html create mode 100644 docs/reference/mutual_within.html create mode 100644 docs/reference/schools00.html create mode 100644 docs/reference/schools05.html create mode 100644 docs/reference/segregation.html diff --git a/NEWS.md b/NEWS.md index b847f8d..87d4968 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -Development version +# segregation 0.0.1.9000 * switch group and unit definitions, to be consistent with the literature * add Theil's Information Index (H) @@ -9,7 +9,7 @@ Development version * "mrc_adjusted" difference decomposition is defined only on overlap sample of units and groups * internal refactoring -v0.0.1 -====== +# segregation 0.0.1 Initial release. + diff --git a/README.Rmd b/README.Rmd index 7611d74..a24627e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -117,13 +117,10 @@ Theil, Henri. (1971). Principles of Econometrics. New York: Wiley. Frankel, D. M., & Volij, O. (2011). Measuring school segregation. Journal of Economic Theory, 146(1), 1-38. https://doi.org/10.1016/j.jet.2010.10.008 -Mora, R., & Ruiz-Castillo, J. (2009). The Invariance Properties of the - Mutual Information Index of Multigroup Segregation, in: Yves Flückiger, Sean F. Reardon, Jacques Silber (eds.) Occupational and Residential Segregation (Research on Economic Inequality, Volume 17), 33-53. +Mora, R., & Ruiz-Castillo, J. (2009). The Invariance Properties of the Mutual Information Index of Multigroup Segregation, in: Yves Flückiger, Sean F. Reardon, Jacques Silber (eds.) Occupational and Residential Segregation (Research on Economic Inequality, Volume 17), 33-53. Mora, R., & Ruiz-Castillo, J. (2011). Entropy-based Segregation Indices. Sociological Methodology, 41(1), 159–194. https://doi.org/10.1111/j.1467-9531.2011.01237.x -Karmel, T. & Maclachlan, M. (1988). Occupational Sex Segregation — Increasing or Decreasing? - Economic Record 64: 187-195. https://doi.org/10.1111/j.1475-4932.1988.tb02057.x +Karmel, T. & Maclachlan, M. (1988). Occupational Sex Segregation — Increasing or Decreasing? Economic Record 64: 187-195. https://doi.org/10.1111/j.1475-4932.1988.tb02057.x -Watts, M. The Use and Abuse of Entropy Based Segregation Indices. Working Paper. - URL: http://www.ecineq.org/ecineq_lux15/FILESx2015/CR2/p217.pdf +Watts, M. The Use and Abuse of Entropy Based Segregation Indices. Working Paper. URL: http://www.ecineq.org/ecineq_lux15/FILESx2015/CR2/p217.pdf diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html new file mode 100644 index 0000000..74d8d19 --- /dev/null +++ b/docs/LICENSE-text.html @@ -0,0 +1,128 @@ + + + + + + + + +License • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

License

+
+ +
YEAR: 2018
+COPYRIGHT HOLDER: Benjamin Elbers
+
+ +
+ +
+ + +
+
+

Developed by Benjamin Elbers.

+
+ +
+

Site built with pkgdown.

+
+ +
+
+ + + + + + diff --git a/docs/authors.html b/docs/authors.html new file mode 100644 index 0000000..0b279ad --- /dev/null +++ b/docs/authors.html @@ -0,0 +1,131 @@ + + + + + + + + +Authors • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

Authors

+
+ +
    +
  • +

    Benjamin Elbers. Author, maintainer. +

    +
    • +
+ +
+ +
+ + +
+
+

Developed by Benjamin Elbers.

+
+ +
+

Site built with pkgdown.

+
+ +
+
+ + + + + + diff --git a/docs/docsearch.css b/docs/docsearch.css new file mode 100644 index 0000000..e5f1fe1 --- /dev/null +++ b/docs/docsearch.css @@ -0,0 +1,148 @@ +/* Docsearch -------------------------------------------------------------- */ +/* + Source: https://github.com/algolia/docsearch/ + License: MIT +*/ + +.algolia-autocomplete { + display: block; + -webkit-box-flex: 1; + -ms-flex: 1; + flex: 1 +} + +.algolia-autocomplete .ds-dropdown-menu { + width: 100%; + min-width: none; + max-width: none; + padding: .75rem 0; + background-color: #fff; + background-clip: padding-box; + border: 1px solid rgba(0, 0, 0, .1); + box-shadow: 0 .5rem 1rem rgba(0, 0, 0, .175); +} + +@media (min-width:768px) { + .algolia-autocomplete .ds-dropdown-menu { + width: 175% + } +} + +.algolia-autocomplete .ds-dropdown-menu::before { + display: none +} + +.algolia-autocomplete .ds-dropdown-menu [class^=ds-dataset-] { + padding: 0; + background-color: rgb(255,255,255); + border: 0; + max-height: 80vh; +} + +.algolia-autocomplete .ds-dropdown-menu .ds-suggestions { + margin-top: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion { + padding: 0; + overflow: visible +} + +.algolia-autocomplete .algolia-docsearch-suggestion--category-header { + padding: .125rem 1rem; + margin-top: 0; + font-size: 1.3em; + font-weight: 500; + color: #00008B; + border-bottom: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--wrapper { + float: none; + padding-top: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--subcategory-column { + float: none; + width: auto; + padding: 0; + text-align: left +} + +.algolia-autocomplete .algolia-docsearch-suggestion--content { + float: none; + width: auto; + padding: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--content::before { + display: none +} + +.algolia-autocomplete .ds-suggestion:not(:first-child) .algolia-docsearch-suggestion--category-header { + padding-top: .75rem; + margin-top: .75rem; + border-top: 1px solid rgba(0, 0, 0, .1) +} + +.algolia-autocomplete .ds-suggestion .algolia-docsearch-suggestion--subcategory-column { + display: block; + padding: .1rem 1rem; + margin-bottom: 0.1; + font-size: 1.0em; + font-weight: 400 + /* display: none */ +} + +.algolia-autocomplete .algolia-docsearch-suggestion--title { + display: block; + padding: .25rem 1rem; + margin-bottom: 0; + font-size: 0.9em; + font-weight: 400 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--text { + padding: 0 1rem .5rem; + margin-top: -.25rem; + font-size: 0.8em; + font-weight: 400; + line-height: 1.25 +} + +.algolia-autocomplete .algolia-docsearch-footer { + width: 110px; + height: 20px; + z-index: 3; + margin-top: 10.66667px; + float: right; + font-size: 0; + line-height: 0; +} + +.algolia-autocomplete .algolia-docsearch-footer--logo { + background-image: url("data:image/svg+xml;utf8,"); + background-repeat: no-repeat; + background-position: 50%; + background-size: 100%; + overflow: hidden; + text-indent: -9000px; + width: 100%; + height: 100%; + display: block; + transform: translate(-8px); +} + +.algolia-autocomplete .algolia-docsearch-suggestion--highlight { + color: #FF8C00; + background: rgba(232, 189, 54, 0.1) +} + + +.algolia-autocomplete .algolia-docsearch-suggestion--text .algolia-docsearch-suggestion--highlight { + box-shadow: inset 0 -2px 0 0 rgba(105, 105, 105, .5) +} + +.algolia-autocomplete .ds-suggestion.ds-cursor .algolia-docsearch-suggestion--content { + background-color: rgba(192, 192, 192, .15) +} diff --git a/docs/docsearch.js b/docs/docsearch.js new file mode 100644 index 0000000..b35504c --- /dev/null +++ b/docs/docsearch.js @@ -0,0 +1,85 @@ +$(function() { + + // register a handler to move the focus to the search bar + // upon pressing shift + "/" (i.e. "?") + $(document).on('keydown', function(e) { + if (e.shiftKey && e.keyCode == 191) { + e.preventDefault(); + $("#search-input").focus(); + } + }); + + $(document).ready(function() { + // do keyword highlighting + /* modified from https://jsfiddle.net/julmot/bL6bb5oo/ */ + var mark = function() { + + var referrer = document.URL ; + var paramKey = "q" ; + + if (referrer.indexOf("?") !== -1) { + var qs = referrer.substr(referrer.indexOf('?') + 1); + var qs_noanchor = qs.split('#')[0]; + var qsa = qs_noanchor.split('&'); + var keyword = ""; + + for (var i = 0; i < qsa.length; i++) { + var currentParam = qsa[i].split('='); + + if (currentParam.length !== 2) { + continue; + } + + if (currentParam[0] == paramKey) { + keyword = decodeURIComponent(currentParam[1].replace(/\+/g, "%20")); + } + } + + if (keyword !== "") { + $(".contents").unmark({ + done: function() { + $(".contents").mark(keyword); + } + }); + } + } + }; + + mark(); + }); +}); + +/* Search term highlighting ------------------------------*/ + +function matchedWords(hit) { + var words = []; + + var hierarchy = hit._highlightResult.hierarchy; + // loop to fetch from lvl0, lvl1, etc. + for (var idx in hierarchy) { + words = words.concat(hierarchy[idx].matchedWords); + } + + var content = hit._highlightResult.content; + if (content) { + words = words.concat(content.matchedWords); + } + + // return unique words + var words_uniq = [...new Set(words)]; + return words_uniq; +} + +function updateHitURL(hit) { + + var words = matchedWords(hit); + var url = ""; + + if (hit.anchor) { + url = hit.url_without_anchor + '?q=' + escape(words.join(" ")) + '#' + hit.anchor; + } else { + url = hit.url + '?q=' + escape(words.join(" ")); + } + + return url; +} diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..c5013fb --- /dev/null +++ b/docs/index.html @@ -0,0 +1,238 @@ + + + + + + + +Entropy-Based Segregation Indices • segregation + + + + + + + + + +
+
+ + + +
+
+ + + + + +
+

+segregation

+ +

An R package to calculate and decompose entropy-based, multigroup segregation indices, with a focus on the Mutual Information Index (M) and Theil’s Information Index (H).

+
    +
  • calculate total, between, within, and local segregation
    • +
  • decompose differences in total segregation over time
    • +
  • estimate standard errors via bootstrapping
    • +
  • every method returns a tidy data frame (or tibble, if the package is loaded) for easy post-processing and plotting
    • +
  • it’s fast, because it uses the data.table package internally
    • +
+
+

+Usage

+

The package provides an easy way to calculate segregation measures, based on the Mutual Information Index (M) and Theil’s Entropy Index (H).

+ +

Standard errors in all functions can be estimated via boostrapping:

+
mutual_total(schools00, "race", "school", weight = "n", se = TRUE)
+#> ..........
+#>   stat   est       se
+#> M    M 0.429 0.000935
+#> H    H 0.422 0.000985
+

Decompose segregation into a between-state and a within-state term (the sum of these equals total segregation):

+
# between states
+mutual_total(schools00, "race", "state", weight = "n")
+#>   stat    est
+#> M    M 0.0992
+#> H    H 0.0977
+
+# within states
+mutual_total(schools00, "race", "school", within = "state", weight = "n")
+#>   stat   est
+#> M    M 0.326
+#> H    H 0.321
+

Local segregation (ls) is a decomposition by units (here racial groups). The sum of the proportion-weighted local segregation scores equals M:

+ +

Decompose the difference in M between 2000 and 2005, using iterative proportional fitting (IPF), as suggested by Karmel and Maclachlan (1988):

+ +
+
+

+How to install

+

To install the package from CRAN, use

+ +

To install the development version, use

+
devtools::install_github("elbersb/segregation")
+

To access the documentation (PDF), type

+ +
+
+

+Papers using the Mutual information index

+

(list incomplete)

+

DiPrete, T. A., Eller, C. C., Bol, T., & van de Werfhorst, H. G. (2017). School-to-Work Linkages in the United States, Germany, and France. American Journal of Sociology, 122(6), 1869-1938. https://doi.org/10.1086/691327

+

Forster, A. G., & Bol, T. (2017). Vocational education and employment over the life course using a new measure of occupational specificity. Social Science Research, 70, 176-197. https://doi.org/10.1016/j.ssresearch.2017.11.004

+

Van Puyenbroeck, T., De Bruyne, K., & Sels, L. (2012). More than ‘Mutual Information’: Educational and sectoral gender segregation and their interaction on the Flemish labor market. Labour Economics, 19(1), 1-8. https://doi.org/10.1016/j.labeco.2011.05.002

+

Mora, R., & Ruiz-Castillo, J. (2003). Additively decomposable segregation indexes. The case of gender segregation by occupations and human capital levels in Spain. The Journal of Economic Inequality, 1(2), 147-179. https://doi.org/10.1023/A:1026198429377

+
+
+

+References on entropy-based segregation indices

+

Theil, Henri. (1971). Principles of Econometrics. New York: Wiley.

+

Frankel, D. M., & Volij, O. (2011). Measuring school segregation. Journal of Economic Theory, 146(1), 1-38. https://doi.org/10.1016/j.jet.2010.10.008

+

Mora, R., & Ruiz-Castillo, J. (2009). The Invariance Properties of the Mutual Information Index of Multigroup Segregation, in: Yves Flückiger, Sean F. Reardon, Jacques Silber (eds.) Occupational and Residential Segregation (Research on Economic Inequality, Volume 17), 33-53.

+

Mora, R., & Ruiz-Castillo, J. (2011). Entropy-based Segregation Indices. Sociological Methodology, 41(1), 159–194. https://doi.org/10.1111/j.1467-9531.2011.01237.x

+

Karmel, T. & Maclachlan, M. (1988). Occupational Sex Segregation — Increasing or Decreasing? Economic Record 64: 187-195. https://doi.org/10.1111/j.1475-4932.1988.tb02057.x

+

Watts, M. The Use and Abuse of Entropy Based Segregation Indices. Working Paper. URL: http://www.ecineq.org/ecineq_lux15/FILESx2015/CR2/p217.pdf

+
+
+
+ + + +
+ + +
+

Developed by Benjamin Elbers.

+
+ +
+

Site built with pkgdown.

+
+ +
+
+ + + + + diff --git a/docs/link.svg b/docs/link.svg new file mode 100644 index 0000000..88ad827 --- /dev/null +++ b/docs/link.svg @@ -0,0 +1,12 @@ + + + + + + diff --git a/docs/news/index.html b/docs/news/index.html new file mode 100644 index 0000000..f71ffe8 --- /dev/null +++ b/docs/news/index.html @@ -0,0 +1,155 @@ + + + + + + + + +Changelog • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

Changelog

+ Source: NEWS.md +
+ +
+

+segregation 0.0.1.9000 Unreleased +

+
    +
  • switch group and unit definitions, to be consistent with the literature
    • +
  • add Theil’s Information Index (H)
    • +
  • add entropy function
    • +
  • add mutual_within function to decompose weighted within indices
    • +
  • add “wide” option to mutual_local and mutual_within
    • +
  • add “ipf” (iterative proportional fitting) function and a difference decomposition based on IPF
    • +
  • “mrc_adjusted” difference decomposition is defined only on overlap sample of units and groups
    • +
  • internal refactoring
    • +
+
+
+

+segregation 0.0.1 2018-04-17 +

+

Initial release.

+
+
+ + + +
+ +
+
+

Developed by Benjamin Elbers.

+
+ +
+

Site built with pkgdown.

+
+ +
+
+ + + + + + diff --git a/docs/pkgdown.css b/docs/pkgdown.css new file mode 100644 index 0000000..6ca2f37 --- /dev/null +++ b/docs/pkgdown.css @@ -0,0 +1,232 @@ +/* Sticky footer */ + +/** + * Basic idea: https://philipwalton.github.io/solved-by-flexbox/demos/sticky-footer/ + * Details: https://github.com/philipwalton/solved-by-flexbox/blob/master/assets/css/components/site.css + * + * .Site -> body > .container + * .Site-content -> body > .container .row + * .footer -> footer + * + * Key idea seems to be to ensure that .container and __all its parents__ + * have height set to 100% + * + */ + +html, body { + height: 100%; +} + +body > .container { + display: flex; + height: 100%; + flex-direction: column; + + padding-top: 60px; +} + +body > .container .row { + flex: 1 0 auto; +} + +footer { + margin-top: 45px; + padding: 35px 0 36px; + border-top: 1px solid #e5e5e5; + color: #666; + display: flex; + flex-shrink: 0; +} +footer p { + margin-bottom: 0; +} +footer div { + flex: 1; +} +footer .pkgdown { + text-align: right; +} +footer p { + margin-bottom: 0; +} + +img.icon { + float: right; +} + +img { + max-width: 100%; +} + +/* Typographic tweaking ---------------------------------*/ + +.contents h1.page-header { + margin-top: calc(-60px + 1em); +} + +/* Section anchors ---------------------------------*/ + +a.anchor { + margin-left: -30px; + display:inline-block; + width: 30px; + height: 30px; + visibility: hidden; + + background-image: url(./link.svg); + background-repeat: no-repeat; + background-size: 20px 20px; + background-position: center center; +} + +.hasAnchor:hover a.anchor { + visibility: visible; +} + +@media (max-width: 767px) { + .hasAnchor:hover a.anchor { + visibility: hidden; + } +} + + +/* Fixes for fixed navbar --------------------------*/ + +.contents h1, .contents h2, .contents h3, .contents h4 { + padding-top: 60px; + margin-top: -40px; +} + +/* Static header placement on mobile devices */ +@media (max-width: 767px) { + .navbar-fixed-top { + position: absolute; + } + .navbar { + padding: 0; + } +} + + +/* Sidebar --------------------------*/ + +#sidebar { + margin-top: 30px; +} +#sidebar h2 { + font-size: 1.5em; + margin-top: 1em; +} + +#sidebar h2:first-child { + margin-top: 0; +} + +#sidebar .list-unstyled li { + margin-bottom: 0.5em; +} + +.orcid { + height: 16px; + vertical-align: middle; +} + +/* Reference index & topics ----------------------------------------------- */ + +.ref-index th {font-weight: normal;} + +.ref-index td {vertical-align: top;} +.ref-index .alias {width: 40%;} +.ref-index .title {width: 60%;} + +.ref-index .alias {width: 40%;} +.ref-index .title {width: 60%;} + +.ref-arguments th {text-align: right; padding-right: 10px;} +.ref-arguments th, .ref-arguments td {vertical-align: top;} +.ref-arguments .name {width: 20%;} +.ref-arguments .desc {width: 80%;} + +/* Nice scrolling for wide elements --------------------------------------- */ + +table { + display: block; + overflow: auto; +} + +/* Syntax highlighting ---------------------------------------------------- */ + +pre { + word-wrap: normal; + word-break: normal; + border: 1px solid #eee; +} + +pre, code { + background-color: #f8f8f8; + color: #333; +} + +pre code { + overflow: auto; + word-wrap: normal; + white-space: pre; +} + +pre .img { + margin: 5px 0; +} + +pre .img img { + background-color: #fff; + display: block; + height: auto; +} + +code a, pre a { + color: #375f84; +} + +a.sourceLine:hover { + text-decoration: none; +} + +.fl {color: #1514b5;} +.fu {color: #000000;} /* function */ +.ch,.st {color: #036a07;} /* string */ +.kw {color: #264D66;} /* keyword */ +.co {color: #888888;} /* comment */ + +.message { color: black; font-weight: bolder;} +.error { color: orange; font-weight: bolder;} +.warning { color: #6A0366; font-weight: bolder;} + +/* Clipboard --------------------------*/ + +.hasCopyButton { + position: relative; +} + +.btn-copy-ex { + position: absolute; + right: 0; + top: 0; + visibility: hidden; +} + +.hasCopyButton:hover button.btn-copy-ex { + visibility: visible; +} + +/* mark.js ----------------------------*/ + +mark { + background-color: rgba(255, 255, 51, 0.5); + border-bottom: 2px solid rgba(255, 153, 51, 0.3); + padding: 1px; +} + +/* vertical spacing after htmlwidgets */ +.html-widget { + margin-bottom: 10px; +} diff --git a/docs/pkgdown.js b/docs/pkgdown.js new file mode 100644 index 0000000..de9bd72 --- /dev/null +++ b/docs/pkgdown.js @@ -0,0 +1,110 @@ +/* http://gregfranko.com/blog/jquery-best-practices/ */ +(function($) { + $(function() { + + $("#sidebar") + .stick_in_parent({offset_top: 40}) + .on('sticky_kit:bottom', function(e) { + $(this).parent().css('position', 'static'); + }) + .on('sticky_kit:unbottom', function(e) { + $(this).parent().css('position', 'relative'); + }); + + $('body').scrollspy({ + target: '#sidebar', + offset: 60 + }); + + $('[data-toggle="tooltip"]').tooltip(); + + var cur_path = paths(location.pathname); + var links = $("#navbar ul li a"); + var max_length = -1; + var pos = -1; + for (var i = 0; i < links.length; i++) { + if (links[i].getAttribute("href") === "#") + continue; + var path = paths(links[i].pathname); + + var length = prefix_length(cur_path, path); + if (length > max_length) { + max_length = length; + pos = i; + } + } + + // Add class to parent
  • , and enclosing
  • if in dropdown + if (pos >= 0) { + var menu_anchor = $(links[pos]); + menu_anchor.parent().addClass("active"); + menu_anchor.closest("li.dropdown").addClass("active"); + } + }); + + function paths(pathname) { + var pieces = pathname.split("/"); + pieces.shift(); // always starts with / + + var end = pieces[pieces.length - 1]; + if (end === "index.html" || end === "") + pieces.pop(); + return(pieces); + } + + function prefix_length(needle, haystack) { + if (needle.length > haystack.length) + return(0); + + // Special case for length-0 haystack, since for loop won't run + if (haystack.length === 0) { + return(needle.length === 0 ? 1 : 0); + } + + for (var i = 0; i < haystack.length; i++) { + if (needle[i] != haystack[i]) + return(i); + } + + return(haystack.length); + } + + /* Clipboard --------------------------*/ + + function changeTooltipMessage(element, msg) { + var tooltipOriginalTitle=element.getAttribute('data-original-title'); + element.setAttribute('data-original-title', msg); + $(element).tooltip('show'); + element.setAttribute('data-original-title', tooltipOriginalTitle); + } + + if(Clipboard.isSupported()) { + $(document).ready(function() { + var copyButton = ""; + + $(".examples, div.sourceCode").addClass("hasCopyButton"); + + // Insert copy buttons: + $(copyButton).prependTo(".hasCopyButton"); + + // Initialize tooltips: + $('.btn-copy-ex').tooltip({container: 'body'}); + + // Initialize clipboard: + var clipboardBtnCopies = new Clipboard('[data-clipboard-copy]', { + text: function(trigger) { + return trigger.parentNode.textContent; + } + }); + + clipboardBtnCopies.on('success', function(e) { + changeTooltipMessage(e.trigger, 'Copied!'); + e.clearSelection(); + }); + + clipboardBtnCopies.on('error', function() { + changeTooltipMessage(e.trigger,'Press Ctrl+C or Command+C to copy'); + }); + }); + } +})(window.jQuery || window.$) diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml new file mode 100644 index 0000000..7908647 --- /dev/null +++ b/docs/pkgdown.yml @@ -0,0 +1,5 @@ +pandoc: 2.2.1 +pkgdown: 1.1.0 +pkgdown_sha: ~ +articles: [] + diff --git a/docs/reference/entropy.html b/docs/reference/entropy.html new file mode 100644 index 0000000..faf633b --- /dev/null +++ b/docs/reference/entropy.html @@ -0,0 +1,184 @@ + + + + + + + + +Calculates the entropy of a distribution — entropy • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Calculates the entropy of a distribution

    + Source: R/segregation.R + +
    + +
    + +

    Returns the entropy of the distribution defined by +group.

    + +
    + + 
    entropy(data, group, weight = NULL, base = exp(1))
    + +

    Arguments

    + + + + + + + + + + + + + + + + + + +
    data

    A data frame.

    group

    A categorical variable or a vector of variables +contained in data.

    weight

    Numeric. Only frequency weights are allowed. +(Default NULL)

    base

    Base of the logarithm that is used in the entropy +calculation. Defaults to the natural logarithm.

    + +

    Value

    + +

    A single number, the entropy.

    + + +

    Examples

    + 
    d <- data.frame(cat = c("A", "B"), n = c(25, 75))
+entropy(d, "cat", weight = "n") # => .56
    #> [1] 0.5623351
    # this is equivalent to -.25*log(.25)-.75*log(.75)
+
+d <- data.frame(cat = c("A", "B"), n = c(50, 50))
+# use base 2 for the logarithm, then entropy is maximized at 1
+entropy(d, "cat", weight = "n", base = 2) # => 1
    #> [1] 1
    +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/index.html b/docs/reference/index.html new file mode 100644 index 0000000..e2df55a --- /dev/null +++ b/docs/reference/index.html @@ -0,0 +1,201 @@ + + + + + + + + +Function reference • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Reference

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +

    All functions

    +

    +
    +

    entropy()

    +

    Calculates the entropy of a distribution

    +

    ipf()

    +

    Adjustment of marginal distributions using iterative proportional fitting

    +

    mutual_difference()

    +

    Decomposes the difference between two M indices

    +

    mutual_local()

    +

    Calculates local segregation indices based on M

    +

    mutual_total()

    +

    Calculate total segregation for M and H

    +

    mutual_within()

    +

    Calculate detailed within-category segregation scores for M and H

    +

    schools00

    +

    Ethnic/racial composition of schools for 2000/2001

    +

    schools05

    +

    Ethnic/racial composition of schools for 2005/2006

    +

    segregation

    +

    segregation: Entropy-based segregation indices

    +
    + + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/ipf.html b/docs/reference/ipf.html new file mode 100644 index 0000000..8354e1e --- /dev/null +++ b/docs/reference/ipf.html @@ -0,0 +1,254 @@ + + + + + + + + +Adjustment of marginal distributions using iterative proportional fitting — ipf • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Adjustment of marginal distributions using iterative proportional fitting

    + Source: R/ipf.R + +
    + +
    + +

    Adjusts the marginal distributions for group and unit +in source to the respective marginal distributions in target, using the iterative +proportional fitting algorithm (IPF).

    + +
    + + 
    ipf(source, target, group, unit, weight = NULL, max_iterations = 100,
+  precision = 0.001)
    + +

    Arguments

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    source

    A "source" data frame. The marginals of this +dataset are adjusted to the marginals of target.

    target

    A "target" data frame. The function returns a dataset +where the marginal distributions of group and unit categories +are approximated by those of target.

    group

    A categorical variable or a vector of variables +contained in source and target. Defines the first distribution +for adjustment.

    unit

    A categorical variable or a vector of variables +contained in source and target. Defines the second distribution +for adjustment.

    weight

    Numeric. Only frequency weights are allowed. +(Default NULL)

    max_iterations

    Maximum number of iterations used for the IPF algorithm.

    precision

    Convergence criterion for the IPF algorithm. In every iteration, +the ratio of the source and target marginals are calculated for every category of +group and unit. The algorithm converges when all ratios are smaller +than 1 + precision.

    + +

    Value

    + +

    Returns a dataset that retains + the association structure of source while approximating + the marginal distributions for group and unit of target. + The dataset identifies each combination of group and unit, and categories that only + occur in either source or target are dropped. The adjusted + frequency of each combination is given by the column n, while n_target and + n_source contain the zero-adjusted frequencies in the target and source dataset, respectively.

    + +

    Details

    + +

    The algorithm works by scaling +the marginal distribution of group in the source data frame towards the +marginal distribution of target; then repeating this process for unit. The +algorithm then keeps alternating between group and unit until the marginals +of the adjusted data frame are within the allowed precision. This results in a dataset that +retains the association structure of source while approximating +the marginal distribution of target. If the number of unit and +group categories is different in source and target, the data frame returns +the combination of unit and group categories that occur in both datasets. +Zero values are replaced by a small, non-zero number (1e-4).

    + +

    References

    + +

    W. E. Deming and F. F. Stephan. 1940. + "On a Least Squares Adjustment of a Sampled Frequency Table + When the Expected Marginal Totals are Known". + Annals of Mathematical Statistics. 11 (4): 427–444.

    +

    T. Karmel and M. Maclachlan. 1988. + "Occupational Sex Segregation — Increasing or Decreasing?" Economic Record 64: 187-195.

    + + +

    Examples

    + 
    # adjusts the marginals of group and unit categories so that
+# schools00 has similar marginals as schools05
+adj <- ipf(schools00, schools05, "race", "school", weight = "n")
    #> ........
    
+# check that the new "race" marginals are similar to the target marginals
+# (the same could be done for schools)
+aggregate(adj$n, list(adj$race), sum)
    #>   Group.1          x
+#> 1   asian  22510.224
+#> 2   black 117453.068
+#> 3    hisp 147040.573
+#> 4  native   6085.647
+#> 5   white 441132.529
    aggregate(adj$n_target, list(adj$race), sum)
    #>   Group.1          x
+#> 1   asian  22508.008
+#> 2   black 117527.007
+#> 3    hisp 147052.003
+#> 4  native   6085.021
+#> 5   white 441050.002
    
+# note that the adjusted dataset contains fewer
+# schools than either the source or the target dataset,
+# because the marginals are only defined for the overlap 
+# of schools
+length(unique(schools00$school))
    #> [1] 2045
    length(unique(schools05$school))
    #> [1] 1920
    length(unique(adj$school))
    #> [1] 1710
    +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/mutual_difference.html b/docs/reference/mutual_difference.html new file mode 100644 index 0000000..209d61c --- /dev/null +++ b/docs/reference/mutual_difference.html @@ -0,0 +1,323 @@ + + + + + + + + +Decomposes the difference between two M indices — mutual_difference • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Decomposes the difference between two M indices

    + Source: R/mutual_difference.R + +
    + +
    + +

    Uses either a method based on the IPF algorithm (recommended and the default) or +the method developed by Mora and Ruiz-Castillo (2009).

    + +
    + + 
    mutual_difference(data1, data2, group, unit, weight = NULL, method = "ipf",
+  forward_only = FALSE, se = FALSE, n_bootstrap = 50, base = exp(1),
+  ...)
    + +

    Arguments

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    data1

    A data frame with same structure as data2.

    data2

    A data frame with same structure as data1.

    group

    A categorical variable or a vector of variables +contained in data. Defines the first dimension +over which segregation is computed.

    unit

    A categorical variable or a vector of variables +contained in data. Defines the second dimension +over which segregation is computed.

    weight

    Numeric. Only frequency weights are allowed. +(Default NULL)

    method

    Either "ipf" (the default) (Karmel and Machlachlan 1988), or +"mrc" / "mrc_adjusted" (Mora and Ruiz-Castillo 2009). See below for an explanation.

    forward_only

    Only relevant for "ipf". If set to TRUE, the decomposition will +only adjust the margins of data2 to those data1, and not vice versa. This +is recommended when data1 and data2 are measurements at different points in time. +(Default FALSE)

    se

    If TRUE, standard errors are estimated via bootstrap. +(Default FALSE)

    n_bootstrap

    Number of bootstrap iterations. (Default 50)

    base

    Base of the logarithm that is used in the calculation. +Defaults to the natural logarithm.

    ...

    Only used for additional arguments when +when method is set to ipf. See ipf for details.

    + +

    Value

    + +

    Returns a data frame with columns stat and est. The data frame contains + the following rows defined by stat: + M1 contains the M for data1. + M2 contains the M for data2. + diff is the difference between M2 and M1.

    +

    The sum of all rows following diff equal diff.

    +

    When using "ipf" or "mrc_adjusted", two additionals rows are reported: + additions contains the change in M induces by unit and codegroup categories + present in data2 but not data1, and removals the reverse.

    +

    When using "ipf", four additional rows are returned: + unit_marginal is the contribution of unit composition differences. + group_marginal is the contribution of group composition differences. + interaction is the contribution of differences in the joint marginal distribution + of unit and group. The total effect of changes in the margins is the sum + of unit_marginal, group_marginal, and interaction. + structural is the contribution unexplained by the marginal changes, i.e. the structural + difference.

    +

    When using "mrc" or "mrc_adjusted", three additional rows are returned: + unit_marginal is the contribution of unit composition differences. + group_marginal is the difference in group entropy. + structural is the contribution of unit composition-invariant differences. + For details on the interpretation of these terms, see Mora and Ruiz-Castillo (2009).

    +

    If se is set to TRUE, an additional column se contains + the associated bootstrapped standard errors, and the column est contains + bootstrapped estimates.

    + +

    Details

    + +

    The IPF method (Karmel and Maclachlan 1988) adjusts the margins of data2 to be similar +to the margins of data1. This is an iterative process, and may take of few seconds depending +on the size of the dataset (see ipf for details). +The difference in M between data1 and the margins-adjusted data2 +is the structural difference between data1 and data2. +The remaining, unexplained difference is due to changes in the marginal distribution. +Unless forward_only is set to TRUE, the process +is then repeated the other way around, and the differences are averaged.

    +

    A problem arises when there are group and/or unit categories in data1 +that are not present in data2 (or vice versa). The IPF method estimates the difference only +for categories that are present in both datasets, and reports additionally +the change in M that is induced by these cases as +additions (present in data2, but not in data1) and +removals (present in data1, but not in data2). For the method developed +by Mora and Ruiz-Castillo (2009), there are two options provided: When using "mrc", the +categories not present in the other data source are set 0. When using "mrc_adjusted", the same +procedure as for the IPF method is used, and additions and removals are reported.

    +

    Note that the IPF method is symmetric, i.e. the reversal of group and unit +definitions will yield the same results. The method developed by Mora and Ruiz-Castillo (2009) +is not symmetric, and will yield different results based on what is defined as the group +and unit categories.

    + +

    References

    + +

    T. Karmel and M. Maclachlan. 1988. + "Occupational Sex Segregation — Increasing or Decreasing?" Economic Record 64: 187-195.

    +

    R. Mora and J. Ruiz-Castillo. 2009. "The Invariance Properties of the + Mutual Information Index of Multigroup Segregation". Research on Economic Inequality 17: 33-53.

    + + +

    Examples

    + 
    # decompose the difference in school segregation between 2000 and 2005
+mutual_difference(schools00, schools05, group = "race", unit = "school",
+    weight = "n", method = "ipf", precision = .01)
    #> ....
+#> .....
    #>                          stat          est
+#> M1                         M1  0.425538976
+#> M2                         M2  0.413385092
+#> diff                     diff -0.012153884
+#> additions           additions -0.003412776
+#> removals             removals -0.011405093
+#> unit_marginal   unit_marginal -0.020197053
+#> group_marginal group_marginal  0.017229147
+#> interaction       interaction  0.001993649
+#> structural         structural  0.003638243
    # => the structural component is close to zero, thus most change is in the marginals.
+# note that this method gives identical results when we switch the unit and group definitions
+mutual_difference(schools00, schools05, group = "school", unit = "race",
+    weight = "n", method = "ipf", precision = .01)
    #> ....
+#> ....
    #>                          stat          est
+#> M1                         M1  0.425538976
+#> M2                         M2  0.413385092
+#> diff                     diff -0.012153884
+#> additions           additions -0.003412776
+#> removals             removals -0.011405093
+#> unit_marginal   unit_marginal  0.017229147
+#> group_marginal group_marginal -0.020197053
+#> interaction       interaction  0.001993927
+#> structural         structural  0.003637965
    
+# the MRC method indicates a much higher structural change
+mutual_difference(schools00, schools05, group = "race", unit = "school",
+    weight = "n", method = "mrc_adjusted")
    #>                          stat          est
+#> M1                         M1  0.425538976
+#> M2                         M2  0.413385092
+#> diff                     diff -0.012153884
+#> additions           additions -0.003412776
+#> removals             removals -0.011405093
+#> unit_marginal   unit_marginal -0.004207757
+#> group_marginal group_marginal  0.062334448
+#> structural         structural -0.055462706
    # ...and is not symmetric
+mutual_difference(schools00, schools05, group = "school", unit = "race",
+    weight = "n", method = "mrc_adjusted")
    #>                          stat          est
+#> M1                         M1  0.425538976
+#> M2                         M2  0.413385092
+#> diff                     diff -0.012153884
+#> additions           additions -0.003412776
+#> removals             removals -0.011405093
+#> unit_marginal   unit_marginal  0.017236954
+#> group_marginal group_marginal -0.004209936
+#> structural         structural -0.010363032
    +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/mutual_local.html b/docs/reference/mutual_local.html new file mode 100644 index 0000000..c59d59c --- /dev/null +++ b/docs/reference/mutual_local.html @@ -0,0 +1,230 @@ + + + + + + + + +Calculates local segregation indices based on M — mutual_local • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Calculates local segregation indices based on M

    + Source: R/mutual.R + +
    + +
    + +

    Returns local segregation indices for each category defined +by unit.

    + +
    + + 
    mutual_local(data, group, unit, weight = NULL, se = FALSE,
+  n_bootstrap = 10, base = exp(1), wide = FALSE)
    + +

    Arguments

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    data

    A data frame.

    group

    A categorical variable or a vector of variables +contained in data. Defines the dimension +over which segregation is computed.

    unit

    A categorical variable or a vector of variables +contained in data. Defines the group for which local +segregation indices are calculated.

    weight

    Numeric. Only frequency weights are allowed. +(Default NULL)

    se

    If TRUE, standard errors are estimated via bootstrap. +(Default FALSE)

    n_bootstrap

    Number of bootstrap iterations. (Default 10)

    base

    Base of the logarithm that is used in the calculation. +Defaults to the natural logarithm.

    wide

    Returns a wide dataframe instead of a long dataframe. +(Default FALSE)

    + +

    Value

    + +

    Returns a data frame with two rows for each category defined by unit, + for a total of 2*(number of units) rows. The column est contains two statistics that + are provided for each unit: ls, the local segregation score, and + p, the proportion of the unit from the total number of cases. + If se is set to TRUE, an additional column se contains + the associated bootstrapped standard errors, and the column est contains + bootstrapped estimates. + If wide is set to TRUE, returns instead a wide dataframe, with one + row for each unit, and the associated statistics in separate columns.

    + +

    References

    + +

    Henri Theil. 1971. Principles of Econometrics. New York: Wiley.

    +

    Ricardo Mora and Javier Ruiz-Castillo. 2011. + "Entropy-based Segregation Indices". Sociological Methodology 41(1): 159–194.

    + + +

    Examples

    + 
    # which racial groups are most segregated?
+(localseg = mutual_local(schools00, "school", "race",
+                         weight="n", wide = TRUE))
    #>     race        ls           p
+#> 1  asian 0.6287673 0.022553401
+#> 2  black 0.8805413 0.190149919
+#> 3   hisp 0.7766327 0.151696575
+#> 4  white 0.1836393 0.628092178
+#> 5 native 1.4342644 0.007507927
    
+sum(localseg$p) # => 1
    #> [1] 1
    
+# the sum of the weighted local segregation scores equals
+# total segregation
+sum(localseg$ls * localseg$p) # => .425
    #> [1] 0.425539
    mutual_total(schools00, "school", "race", weight="n") # M => .425
    #>   stat        est
+#> M    M 0.42553898
+#> H    H 0.05642991
    +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/mutual_total.html b/docs/reference/mutual_total.html new file mode 100644 index 0000000..f251655 --- /dev/null +++ b/docs/reference/mutual_total.html @@ -0,0 +1,254 @@ + + + + + + + + +Calculate total segregation for M and H — mutual_total • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Calculate total segregation for M and H

    + Source: R/mutual.R + +
    + +
    + +

    Returns the total segregation between group and unit. +If within is given, calculates segregation within each +within category separately, and takes the weighted average. +Also see mutual_within for detailed within calculations.

    + +
    + + 
    mutual_total(data, group, unit, within = NULL, weight = NULL, se = FALSE,
+  n_bootstrap = 10, base = exp(1))
    + +

    Arguments

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    data

    A data frame.

    group

    A categorical variable or a vector of variables +contained in data. Defines the first dimension +over which segregation is computed.

    unit

    A categorical variable or a vector of variables +contained in data. Defines the second dimension +over which segregation is computed.

    within

    A categorical variable or a vector of variables +contained in data. The variable(s) should be a superset of either +the unit or the group for the calculation to be meaningful. +If provided, segregation is +computed within the groups defined by the variable, and then averaged. +(Default NULL)

    weight

    Numeric. Only frequency weights are allowed. +(Default NULL)

    se

    If TRUE, standard errors are estimated via bootstrap. +(Default FALSE)

    n_bootstrap

    Number of bootstrap iterations. (Default 10)

    base

    Base of the logarithm that is used in the calculation. +Defaults to the natural logarithm.

    + +

    Value

    + +

    Returns a data frame with two rows. The column est contains + the Mutual Information Index, M, and Theil's Entropy Index, H. The H is the + the M divided by the group entropy. If within was given, + M and H are weighted averages of the within-category segregation scores. + If se is set to TRUE, an additional column se contains + the associated bootstrapped standard errors, and the column est contains + bootstrapped estimates.

    + +

    References

    + +

    Henri Theil. 1971. Principles of Econometrics. New York: Wiley.

    +

    Ricardo Mora and Javier Ruiz-Castillo. 2011. + "Entropy-based Segregation Indices". Sociological Methodology 41(1): 159–194.

    + + +

    Examples

    + 
    # calculate school racial segregation
+mutual_total(schools00, "school", "race", weight="n") # M => .425
    #>   stat        est
+#> M    M 0.42553898
+#> H    H 0.05642991
    
+# note that the definition of groups and units is arbitrary
+mutual_total(schools00, "race", "school", weight="n") # M => .425
    #>   stat       est
+#> M    M 0.4255390
+#> H    H 0.4188083
    
+# if groups or units are defined by a combination of variables,
+# vectors of variable names can be provided -
+# here there is no difference, because schools
+# are nested within districts
+mutual_total(schools00, "race", c("district", "school"),
+             weight="n") # M => .424
    #>   stat       est
+#> M    M 0.4255390
+#> H    H 0.4188083
    
+# estimate standard errors for M and H
+mutual_total(schools00, "race", "school", weight="n", se=TRUE)
    #> ..........
    #>   stat       est           se
+#> M    M 0.4292964 0.0008481508
+#> H    H 0.4225426 0.0007260637
    
+# estimate segregation within school districts
+mutual_total(schools00, "race", "school",
+             within="district", weight="n") # M => .087
    #>   stat        est
+#> M    M 0.08758648
+#> H    H 0.08620114
    
+# estimate between-district racial segregation
+mutual_total(schools00, "race", "district", weight="n") # M => .338
    #>   stat       est
+#> M    M 0.3379525
+#> H    H 0.3326072
    # note that the sum of within-district and between-district
+# segregation equals total school-race segregation;
+# here, most segregation is between school districts
+
    +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/mutual_within.html b/docs/reference/mutual_within.html new file mode 100644 index 0000000..2dc0cfc --- /dev/null +++ b/docs/reference/mutual_within.html @@ -0,0 +1,243 @@ + + + + + + + + +Calculate detailed within-category segregation scores for M and H — mutual_within • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Calculate detailed within-category segregation scores for M and H

    + Source: R/mutual.R + +
    + +
    + +

    Calculates the segregation between group and unit +within each category defined by within.

    + +
    + + 
    mutual_within(data, group, unit, within, weight = NULL, se = FALSE,
+  n_bootstrap = 10, base = exp(1), wide = FALSE)
    + +

    Arguments

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    data

    A data frame.

    group

    A categorical variable or a vector of variables +contained in data. Defines the first dimension +over which segregation is computed.

    unit

    A categorical variable or a vector of variables +contained in data. Defines the second dimension +over which segregation is computed.

    within

    A categorical variable or a vector of variables +contained in data that defines the within-segregation categoriess.

    weight

    Numeric. Only frequency weights are allowed. +(Default NULL)

    se

    If TRUE, standard errors are estimated via bootstrap. +(Default FALSE)

    n_bootstrap

    Number of bootstrap iterations. (Default 10)

    base

    Base of the logarithm that is used in the calculation. +Defaults to the natural logarithm.

    wide

    Returns a wide dataframe instead of a long dataframe. +(Default FALSE)

    + +

    Value

    + +

    Returns a data frame with four rows for each category defined by within. + The column est contains four statistics that + are provided for each unit: + M is the within-category M, and p is the proportion of the category. + Multiplying M and p gives the contribution of each within-category + towards the total M. + H is the within-category H, and h_weight provides the weight. + Multiplying H and h_weight gives the contribution of each within-category + towards the total H. h_weight is defined as p * EW/E, where EW is the + within-category entropy, and E is the overall entropy. + If se is set to TRUE, an additional column se contains + the associated bootstrapped standard errors, and the column est contains + bootstrapped estimates. + If wide is set to TRUE, returns instead a wide dataframe, with one + row for each within category, and the associated statistics in separate columns.

    + +

    References

    + +

    Henri Theil. 1971. Principles of Econometrics. New York: Wiley.

    +

    Ricardo Mora and Javier Ruiz-Castillo. 2011. + "Entropy-based Segregation Indices". Sociological Methodology 41(1): 159–194.

    + + +

    Examples

    + 
    (within <- mutual_within(schools00, "race", "school", within = "state",
+                         weight = "n", wide = TRUE))
    #>   state         M         p         H  h_weight
+#> 1     A 0.4085965 0.2768819 0.4969216 0.2240667
+#> 2     B 0.2549959 0.4035425 0.2680884 0.3777638
+#> 3     C 0.3450221 0.3195756 0.3611257 0.3004955
    # the M for "AL" is .409
+# manual calculation
+schools_AL <- schools00[schools00$state=="AL",]
+mutual_total(schools_AL, "race", "school", weight = "n") # M => .409
    #>   stat est
+#> M    M   0
+#> H    H NaN
    
+# to recover the within M and H from the output, multiply
+# p * M and h_weight * H, respectively
+sum(within$p * within$M) # => .326
    #> [1] 0.3262953
    sum(within$H * within$h_weight) # => .321
    #> [1] 0.3211343
    # compare with:
+mutual_total(schools00, "race", "school", within = "state", weight = "n")
    #>   stat       est
+#> M    M 0.3262953
+#> H    H 0.3211343
    +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/schools00.html b/docs/reference/schools00.html new file mode 100644 index 0000000..0c6660f --- /dev/null +++ b/docs/reference/schools00.html @@ -0,0 +1,160 @@ + + + + + + + + +Ethnic/racial composition of schools for 2000/2001 — schools00 • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Ethnic/racial composition of schools for 2000/2001

    + Source: R/data.R + +
    + +
    + +

    Fake dataset used for examples. Loosely based on data provided by +the National Center for Education Statistics, Common Core of Data, +with information on U.S. primary schools in three U.S. states. +The original data can be downloaded free of charge at https://nces.ed.gov/ccd/.

    + +
    + + 
    schools00
    + +

    Format

    + +

    A data frame with 8,142 rows and 5 variables:

    +
    state

    either A, B, or C

    +
    district

    school agency/district ID

    +
    school

    school ID

    +
    race

    either native, asian, hispanic, black, or white

    +
    n

    n of students by school and race

    +
    + + +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/schools05.html b/docs/reference/schools05.html new file mode 100644 index 0000000..ee8b45c --- /dev/null +++ b/docs/reference/schools05.html @@ -0,0 +1,160 @@ + + + + + + + + +Ethnic/racial composition of schools for 2005/2006 — schools05 • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Ethnic/racial composition of schools for 2005/2006

    + Source: R/data.R + +
    + +
    + +

    Fake dataset used for examples. Loosely based on data provided by +the National Center for Education Statistics, Common Core of Data, +with information on U.S. primary schools in three U.S. states. +The original data can be downloaded free of charge at https://nces.ed.gov/ccd/.

    + +
    + + 
    schools05
    + +

    Format

    + +

    A data frame with 8,013 rows and 5 variables:

    +
    state

    either A, B, or C

    +
    district

    school agency/district ID

    +
    school

    school ID

    +
    race

    either native, asian, hispanic, black, or white

    +
    n

    n of students by school and race

    +
    + + +
    + +
    + +
    +
    +

    Developed by Benjamin Elbers.

    +
    + +
    +

    Site built with pkgdown.

    +
    + +
    +
    + + + + + + diff --git a/docs/reference/segregation.html b/docs/reference/segregation.html new file mode 100644 index 0000000..7359e5a --- /dev/null +++ b/docs/reference/segregation.html @@ -0,0 +1,171 @@ + + + + + + + + +segregation: Entropy-based segregation indices — segregation • segregation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    segregation: Entropy-based segregation indices

    + Source: R/segregation.R + +
    + +
    + +

    Calculate and decompose entropy-based, multigroup segregation indices, with a focus +on the Mutual Information Index (M) and Theil's Information Index (H). +Provides tools to decompose the measures by groups and units, and by within +and between terms. Includes standard error estimation by bootstrapping.

    + +
    + + +

    Methods

    + + +
      +

    • mutual_total Computes M and H.

      • +

    • mutual_within Computes detailed within-category segregation.

      • +

    • mutual_local Computes local segregation based on M.

      • +

    • mutual_difference Decomposes difference between two M indices.

      • +

    • entropy Calculates the entropy of a distribution.

      • +

    • ipf Uses iterative proportional fitting to adjust + the marginal distributions in one dataset to those of another dataset.

      • +
    + +

    Data

    + + + + + +
    + +
    + + +
    + + + + + + diff --git a/render_README.R b/render_README.R index d9ecf46..62d5a32 100644 --- a/render_README.R +++ b/render_README.R @@ -6,3 +6,6 @@ rmarkdown::render("README.Rmd", output_format = rmarkdown::github_document( df_print = function(...) { print(..., row.names=FALSE) }, html_preview = FALSE)) + +pkgdown::build_site() +