README.md
In mgunther87/ipumsPMA: Common functions for IPUMS PMA staff

The ipumsPMA R package

IPUMS PMA team 28 July, 2020

This package provides custom workflow functions for IPUMS PMA staff. Check out the Reference page on our GitHub Pages website for a full list of available functions and instructions on their use.

If you’ve never installed a package for R from GitHub before, welcome! The easiest way to do so is to obtain a personal access token for your GitHub account that applications like R can use instead of your username and password. Head over here to get one, and then assign it to an object called “auth” (e.g. auth <- "123456789abcdefghijklmnopqrstuvwxyz") to use in the code below. Installation from github also requires the package devtools, which you can get from CRAN (the easy way) with install.packages("devtools"). Our package, ipumsPMA, is not on CRAN, which is why you have to now run this:

devtools::install_github(
  repo = "krist108/ipumsPMA", 
  host = "github.umn.edu/api/v3",
  auth_token = auth,
  dependencies = TRUE
)

ipumsPMA uses the ipums-metadata Python library, such that all of the Python functions can be accessed through R via an imported object called py (e.g. py$TranslationTable("aborev", "pma")$samples() will return an R object: a character vector containing all of the samples in the Translation Table for ABOREV). The package reticulate makes this possible, and it should be installed when you follow the instructions above (if not, run install.packages("reticulate")). To get the Python library, you have two options:

Option 1) If you’re already connected to the server and have the IPUMS drive mounted, you’ll find the MPC conda channel in our programming folder and can install directly from that location:

reticulate::conda_install(
  packages = "ipums-metadata",
  channel = "Z:/programming/conda/mpc/"
)

Option 2) Install the package from GitHub using the application Git Bash for Windows or Terminal for Mac. These programs will prompt you to enter your user name and password for GitHub:

pip install git+https://github.umn.edu/mpc/ipums-metadata

Note: the ipums-metadata library may have Python dependencies (e.g. Pandas) that will not be installed automatically. Check the ipums-metadata documentation for instructions!

ipumsPMA also uses Java to pass functions from R to other applications on your system (esepcially Word and Excel) via the rJava package. To make this work, you must have a recent version of the Java Development Kit (standard Java SE won’t cut it). Since the popular Oracle JDK is no longer free for commercial use, installation from OpenJDK is highly recommended.

ipumsPMA was built with R version 3.5, but newer is better (because of the number of package dependecies involved). RStudio is strongly recommended over R, especially because it will suggest agrument options when you’re learning new functions.

While ipums macros for Excel and Word are incredibly useful on their own, ipumsPMA provides an alternative way to perform most of the tasks relevant to PMA, but in batches (and without VBA). For example:

Import frequencies for all samples in a TT skeleton and format the TT accordingly
Import variable name changes, labels, and universe statements from any PMA tracking sheet to a TT
Produce a variable DESC file from a template with language either imported from a TT or PMA tracking sheet or specified in an R script
Perform tasks on any local or remote computer (including the those with mac OS) where the IPUMS drive is mounted
(Most importantly) repeat these steps for a batch of variables, ensuring that you won’t have to open a series of TTs to run the macro on each one individually, and also that repeated language in a series of DESCs can be recycled without the use of copy/paste

An R help file contains detailed information on each function in the package, along with information about each of their arguments and examples showing how to use them. Access the help files with: