Vignette and README edits (#70)

ipums · Feb 23, 2024 · 451c0b8 · 451c0b8
1 parent ecdf6f0
commit 451c0b8
Show file tree

Hide file tree

Showing 37 changed files with 658 additions and 1,629 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing
 Thank you for considering improving this project! By participating, you
-agree to abide by the [code of conduct](https://github.com/ipums/ipumsr/blob/master/CONDUCT.md).
+agree to abide by the [code of conduct](https://tech.popdata.org/ipumsr/CODE_OF_CONDUCT.html).
 
 # Issues (Reporting a problem or suggestion)
 If you've experience a problem with the package, or have a suggestion for it, 
@@ -17,6 +17,7 @@ We'll do our best to answer your question.
 
 # Pull Requests (Making changes to the package)
 We appreciate pull requests that follow these guidelines:
+
 1) Make sure that tests pass (and add new ones if possible). 
 
 2) Do your best to conform to the code style of the package, currently

diff --git a/R/api_process_extract.R b/R/api_process_extract.R
@@ -766,7 +766,7 @@ extract_is_completed_and_has_links.micro_extract <- function(extract) {
   is_complete <- extract$status == "completed"
 
   has_codebook <- has_url(download_links, "ddi_codebook")
-  has_data <-  has_url(download_links, "data")
+  has_data <- has_url(download_links, "data")
 
   is_complete && has_codebook && has_data
 }

diff --git a/R/micro_read_chunked.R b/R/micro_read_chunked.R
@@ -168,25 +168,25 @@
 #' # the full dataset in memory
 #' if (requireNamespace("biglm")) {
 #'   lm_results <- read_ipums_micro_chunked(
-#'    ipums_example("cps_00160.xml"),
-#'    IpumsBiglmCallback$new(
-#'      INCTOT ~ AGE + HEALTH, # Model formula
-#'      function(x, pos) {
-#'        x %>%
-#'          mutate(
-#'            INCTOT = lbl_na_if(
-#'              INCTOT,
-#'              ~ grepl("Missing|N.I.U.", .lbl)
-#'            ),
-#'            HEALTH = as_factor(HEALTH)
-#'          )
-#'      }
-#'    ),
-#'    chunk_size = 1000,
-#'    verbose = FALSE
-#'  )
+#'     ipums_example("cps_00160.xml"),
+#'     IpumsBiglmCallback$new(
+#'       INCTOT ~ AGE + HEALTH, # Model formula
+#'       function(x, pos) {
+#'         x %>%
+#'           mutate(
+#'             INCTOT = lbl_na_if(
+#'               INCTOT,
+#'               ~ grepl("Missing|N.I.U.", .lbl)
+#'             ),
+#'             HEALTH = as_factor(HEALTH)
+#'           )
+#'       }
+#'     ),
+#'     chunk_size = 1000,
+#'     verbose = FALSE
+#'   )
 #'
-#'  summary(lm_results)
+#'   summary(lm_results)
 #' }
 read_ipums_micro_chunked <- function(
     ddi,

diff --git a/R/viewer.R b/R/viewer.R
@@ -61,8 +61,10 @@ ipums_view <- function(x, out_file = NULL, launch = TRUE) {
   if (is.null(out_file)) {
     if (!launch) {
       rlang::warn(c(
-        paste0("Some operating systems may have trouble opening an HTML ",
-               "file from a temporary directory."),
+        paste0(
+          "Some operating systems may have trouble opening an HTML ",
+          "file from a temporary directory."
+        ),
         "i" = "Use `out_file` to specify an alternate output location."
       ))
     }

diff --git a/README.Rmd b/README.Rmd
@@ -53,15 +53,15 @@ remotes::install_github("ipums/ipumsr")
 
 ## What is IPUMS?
 
-[IPUMS](https://www.ipums.org/mission-purpose) is the world's largest
+[IPUMS](https://www.ipums.org) is the world's largest
 publicly available population database, providing census and survey data
 from around the world integrated across time and space. IPUMS
 integration and documentation make it easy to study change, conduct
 comparative research, merge information across data types, and analyze
 individuals within family and community context. Data and services are
 available free of charge.
 
-IPUMS consists of multiple projects, or collections, that provide
+IPUMS consists of multiple projects, or *collections*, that provide
 different data products.
 
 -   **Microdata** projects distribute data for individual survey units,
@@ -71,7 +71,7 @@ statistics for particular geographic units along with corresponding
 GIS mapping files.
 
 ipumsr supports different levels of functionality for each IPUMS project, as
-summarized in the following table:
+summarized in the table below.
 
 ```{r}
 #| echo: false
@@ -88,90 +88,90 @@ tbl_config <- list(
   list(
     img = "<a href='https://usa.ipums.org/usa/'><img src='man/figures/logo-square_usa_50x50.png'></a>",
     proj = "<a href='https://usa.ipums.org/usa/'>IPUMS USA</a>",
-    type = "Microdata", 
-    desc = "U.S. Census and American Community Survey microdata (1850-present)", 
-    read = checkmark(), 
-    request = checkmark(), 
+    type = "Microdata",
+    desc = "U.S. Census and American Community Survey microdata (1850-present)",
+    read = checkmark(),
+    request = checkmark(),
     metadata = ""
   ),
   list(
     img = "<a href='https://cps.ipums.org/cps/'><img src='man/figures/logo-square_cps_50x50.png'></a>",
-    proj = "<a href='https://cps.ipums.org/cps/'>IPUMS CPS</a>", 
-    type = "Microdata", 
-    desc = "Current Population Survey microdata including basic monthly surveys and supplements (1962-present)", 
-    read = checkmark(), 
-    request = checkmark(), 
+    proj = "<a href='https://cps.ipums.org/cps/'>IPUMS CPS</a>",
+    type = "Microdata",
+    desc = "Current Population Survey microdata including basic monthly surveys and supplements (1962-present)",
+    read = checkmark(),
+    request = checkmark(),
     metadata = ""
   ),
   list(
     img = "<a href='https://international.ipums.org/international/'><img src='man/figures/logo-square_international_50x50.png'></a>",
     proj = "<a href='https://international.ipums.org/international/'>IPUMS International</a>",
-    type = "Microdata", 
-    desc = "Census microdata covering over 100 countries, contemporary and historical", 
-    read = checkmark(), 
-    request = checkmark(), 
+    type = "Microdata",
+    desc = "Census microdata covering over 100 countries, contemporary and historical",
+    read = checkmark(),
+    request = checkmark(),
     metadata = ""
   ),
   list(
     img = "<a href='https://www.nhgis.org/'><img src='man/figures/logo-square_nhgis50x50.png'></a>",
-    proj = "<a href='https://www.nhgis.org/'>IPUMS NHGIS</a>", 
-    type = "Aggregate Data", 
-    desc = "Tabular U.S. Census data and GIS mapping files (1790-present)", 
+    proj = "<a href='https://www.nhgis.org/'>IPUMS NHGIS</a>",
+    type = "Aggregate Data",
+    desc = "Tabular U.S. Census data and GIS mapping files (1790-present)",
     read = checkmark(),
-    request = checkmark(), 
+    request = checkmark(),
     metadata = checkmark()
   ),
   list(
     img = "<a href='https://ihgis.ipums.org/'><img src='man/figures/logo-square_ihgis_50x50.png'></a>",
-    proj = "<a href='https://ihgis.ipums.org/'>IPUMS IHGIS</a>", 
-    type = "Aggregate Data", 
-    desc = "Tabular and GIS data from population, housing, and agricultural censuses around the world", 
-    read = "", 
-    request = "", 
+    proj = "<a href='https://ihgis.ipums.org/'>IPUMS IHGIS</a>",
+    type = "Aggregate Data",
+    desc = "Tabular and GIS data from population, housing, and agricultural censuses around the world",
+    read = "",
+    request = "",
     metadata = ""
   ),
   list(
     img = "<a href='https://timeuse.ipums.org/'><img src='man/figures/logo-square_time-use_50x50.png'></a>",
-    proj = "<a href='https://timeuse.ipums.org/'>IPUMS Time Use</a>", 
-    type = "Microdata", 
-    desc = "Time use microdata from the U.S. (1930-present) and thirteen other countries (1965-present)", 
-    read = checkmark(), 
-    request = "", 
+    proj = "<a href='https://timeuse.ipums.org/'>IPUMS Time Use</a>",
+    type = "Microdata",
+    desc = "Time use microdata from the U.S. (1930-present) and thirteen other countries (1965-present)",
+    read = checkmark(),
+    request = "",
     metadata = ""
   ),
   list(
     img = "<a href='https://healthsurveys.ipums.org/'><img src='man/figures/logo-square_health-surveys_50x50.png'></a>",
-    proj = "<a href='https://healthsurveys.ipums.org/'>IPUMS Health Surveys</a>", 
-    type = "Microdata", 
+    proj = "<a href='https://healthsurveys.ipums.org/'>IPUMS Health Surveys</a>",
+    type = "Microdata",
     desc = paste0(
       "Microdata from the U.S. ",
       "<a href='https://nhis.ipums.org/nhis/'>National Health Interview Survey (NHIS)</a> (1963-present) and ",
       "<a href='https://meps.ipums.org/meps/'>Medical Expenditure Panel Survey (MEPS)</a> (1996-present)"
     ),
-    read = checkmark(), 
-    request = "", 
+    read = checkmark(),
+    request = "",
     metadata = ""
   ),
   list(
     img = "<a href='https://globalhealth.ipums.org/'><img src='man/figures/logo-square_global-health_50x50.png'></a>",
-    proj = "<a href='https://globalhealth.ipums.org/'>IPUMS Global Health</a>", 
+    proj = "<a href='https://globalhealth.ipums.org/'>IPUMS Global Health</a>",
     type = "Microdata",
     desc = paste0(
       "Health survey microdata for low- and middle-income countries, including ",
       "harmonized data collections for <a href='https://www.idhsdata.org/'>Demographic and Health Surveys (DHS)</a> ",
       "and <a href='https://pma.ipums.org/'>Performance Monitoring for Action (PMA)</a> surveys"
     ),
-    read = checkmark(), 
-    request = "", 
+    read = checkmark(),
+    request = "",
     metadata = ""
   ),
   list(
     img = "<a href='https://highered.ipums.org/highered/'><img src='man/figures/logo-square_higher-ed_50x50.png'></a>",
-    proj = "<a href='https://highered.ipums.org/highered/'>IPUMS Higher Ed</a>", 
-    type = "Microdata", 
-    desc = "Survey microdata on the science and engineering workforce in the U.S. from 1993 to 2013", 
-    read = checkmark(), 
-    request = "", 
+    proj = "<a href='https://highered.ipums.org/highered/'>IPUMS Higher Ed</a>",
+    type = "Microdata",
+    desc = "Survey microdata on the science and engineering workforce in the U.S. from 1993 to 2013",
+    read = checkmark(),
+    request = "",
     metadata = ""
   )
 )
@@ -196,25 +196,28 @@ knitr::kable(
 
 ipumsr uses the [IPUMS API](https://developer.ipums.org/) to submit data
 requests, download data extracts, and get metadata, so the scope of
-ipumsr functionality generally corresponds to the [available API
-functionality](https://developer.ipums.org/docs/v2/apiprogram/apis/). As
+functionality generally corresponds to that [available via the API](https://developer.ipums.org/docs/v2/apiprogram/apis/). As
 the IPUMS team extends the API to support more functionality for more
 projects, we aim to extend ipumsr capabilities accordingly.
 
 ## Getting started
 
 If you're new to IPUMS data, learn more about what's available through
-the [IPUMS Projects Overview](https://www.ipums.org/overview).
+the [IPUMS Projects Overview](https://www.ipums.org/overview). Then, see
+`vignette("ipums")` for an overview of how to obtain IPUMS data.
 
-The package vignettes are the best place to learn about what's available in 
-ipumsr itself:
+The package vignettes are the best place to explore what ipumsr has to offer:
 
 -   To read IPUMS data extracts into R, see `vignette("ipums-read")`.
--   To interact with the IPUMS extract system via the IPUMS API, see 
-    `vignette("ipums-api")`.
+
+-   To interact with the IPUMS extract and metadata system via the IPUMS API, 
+    see `vignette("ipums-api")`.
+
 -   For additional details about microdata and NHGIS extract requests, see 
     `vignette("ipums-api-micro")` and `vignette("ipums-api-nhgis")`.
+
 -   To work with labelled values in IPUMS data, see `vignette("value-labels")`.
+
 -   For techniques for working with large data extracts, see
     `vignette("ipums-bigdata")`.
 
@@ -243,9 +246,9 @@ We greatly appreciate feedback and development contributions. Please
 submit any bug reports, pull requests, or other suggestions on
 [GitHub](https://github.com/ipums/ipumsr/issues). Before contributing,
 please be sure to read the [Contributing
-Guidelines](https://github.com/ipums/ipumsr/blob/master/CONTRIBUTING.md)
-and the [Code of
-Conduct](https://github.com/ipums/ipumsr/blob/master/CONDUCT.md).
+Guidelines](https://tech.popdata.org/ipumsr/CONTRIBUTING.html)
+and the 
+[Code of Conduct](https://tech.popdata.org/ipumsr/CODE_OF_CONDUCT.html).
 
 If you have general questions or concerns about IPUMS data, check out
 our [user forum](https://forum.ipums.org) or send an email to

diff --git a/README.md b/README.md
@@ -42,15 +42,15 @@ remotes::install_github("ipums/ipumsr")
 
 ## What is IPUMS?
 
-[IPUMS](https://www.ipums.org/mission-purpose) is the world’s largest
-publicly available population database, providing census and survey data
-from around the world integrated across time and space. IPUMS
-integration and documentation make it easy to study change, conduct
-comparative research, merge information across data types, and analyze
-individuals within family and community context. Data and services are
-available free of charge.
-
-IPUMS consists of multiple projects, or collections, that provide
+[IPUMS](https://www.ipums.org) is the world’s largest publicly available
+population database, providing census and survey data from around the
+world integrated across time and space. IPUMS integration and
+documentation make it easy to study change, conduct comparative
+research, merge information across data types, and analyze individuals
+within family and community context. Data and services are available
+free of charge.
+
+IPUMS consists of multiple projects, or *collections*, that provide
 different data products.
 
 - **Microdata** projects distribute data for individual survey units,
@@ -60,7 +60,7 @@ different data products.
   GIS mapping files.
 
 ipumsr supports different levels of functionality for each IPUMS
-project, as summarized in the following table:
+project, as summarized in the table below.
 
 <table class="table-hover table-proj-summary">
 <thead>
@@ -298,26 +298,31 @@ from 1993 to 2013
 
 ipumsr uses the [IPUMS API](https://developer.ipums.org/) to submit data
 requests, download data extracts, and get metadata, so the scope of
-ipumsr functionality generally corresponds to the [available API
-functionality](https://developer.ipums.org/docs/v2/apiprogram/apis/). As
-the IPUMS team extends the API to support more functionality for more
-projects, we aim to extend ipumsr capabilities accordingly.
+functionality generally corresponds to that [available via the
+API](https://developer.ipums.org/docs/v2/apiprogram/apis/). As the IPUMS
+team extends the API to support more functionality for more projects, we
+aim to extend ipumsr capabilities accordingly.
 
 ## Getting started
 
 If you’re new to IPUMS data, learn more about what’s available through
-the [IPUMS Projects Overview](https://www.ipums.org/overview).
+the [IPUMS Projects Overview](https://www.ipums.org/overview). Then, see
+`vignette("ipums")` for an overview of how to obtain IPUMS data.
 
-The package vignettes are the best place to learn about what’s available
-in ipumsr itself:
+The package vignettes are the best place to explore what ipumsr has to
+offer:
 
 - To read IPUMS data extracts into R, see `vignette("ipums-read")`.
-- To interact with the IPUMS extract system via the IPUMS API, see
-  `vignette("ipums-api")`.
+
+- To interact with the IPUMS extract and metadata system via the IPUMS
+  API, see `vignette("ipums-api")`.
+
 - For additional details about microdata and NHGIS extract requests, see
   `vignette("ipums-api-micro")` and `vignette("ipums-api-nhgis")`.
+
 - To work with labelled values in IPUMS data, see
   `vignette("value-labels")`.
+
 - For techniques for working with large data extracts, see
   `vignette("ipums-bigdata")`.
 
@@ -346,9 +351,8 @@ We greatly appreciate feedback and development contributions. Please
 submit any bug reports, pull requests, or other suggestions on
 [GitHub](https://github.com/ipums/ipumsr/issues). Before contributing,
 please be sure to read the [Contributing
-Guidelines](https://github.com/ipums/ipumsr/blob/master/CONTRIBUTING.md)
-and the [Code of
-Conduct](https://github.com/ipums/ipumsr/blob/master/CONDUCT.md).
+Guidelines](https://tech.popdata.org/ipumsr/CONTRIBUTING.html) and the
+[Code of Conduct](https://tech.popdata.org/ipumsr/CODE_OF_CONDUCT.html).
 
 If you have general questions or concerns about IPUMS data, check out
 our [user forum](https://forum.ipums.org) or send an email to