👨‍👩‍👧 Immigrant Households

How has the size and configuration of U.S. immigrant households changed since the 1970s? We examine this question, building upon our previous work on American headship rate and housing supply as well as the demographics of American households.

📊 Key Findings

Forthcoming.

⚡ Quick Start

For experienced users who just want to get the project running right away. If you have trouble following these steps, please follow the Detailed Start guide below.

1. Navigate to the directory where you want the repo

   cd your/path/to/parent/directory

2. Clone both required repos side by side

   git clone https://github.com/lorae/immigrant-households immigrant-households
   git clone https://github.com/lorae/demographr demographr

3. Enter the main project

   cd immigrant-households

4. Copy the environment file and edit it with your own IPUMS API key

   cp example.Renviron .Renviron
   # (Windows PowerShell: Copy-Item example.Renviron .Renviron)
   # IMPORTANT: open .Renviron and replace "your_ipums_api_key" with your actual key

5. Restore dependencies and run the analysis

   Open immigrant-households.Rproj in your preferred IDE, then in the R console:

   renv::restore()
   source("run-all.R")

📎 Detailed Start

Detailed instructions for how to fully install and run this project code on your computer.

Part A: Clone the repo and configure the R project

These steps will allow you to install the code on your computer that runs this project and set up the environment so that it mimics the environment on which the code was developed.

1. Clone the repo: Open a terminal on your computer. Navigate to the directory you would like to be the parent directory of the repo, then clone the repo.

   MacOS/Linux:

   cd your/path/to/parent/directory

   git clone https://github.com/lorae/immigrant-households immigrant-households

   Windows:

   cd your\path\to\parent\directory

   git clone https://github.com/lorae/immigrant-households immigrant-households

2. Open the R project: Navigate into the directory, now located at your/path/to/parent/directory/immigrant-households. Open immigrant-households.Rproj using your preferred IDE for R. (We use R Studio.)

   Every subsequent time you work with the project code, you should always open the immigrant-households.Rproj file at the beginning of your work session. This will avoid common issues with broken file paths or an incorrect working directory.

3. Initialize R environment: Install all the dependencies (packages) needed to make the code run on your computer.

   First, ensure you have the package manager, renv, installed. Run the following in your R console:

   install.packages("renv") # Safe to run, even if you're not sure if you already have renv

   library("renv")

   Then restore the project:

   renv::restore()

4. Clone the sibling repo, demographr: This project makes use of a bundle of functions that are unit-tested and generalized in a package called demographr. Clone this repo in the same parent directory where you cloned immigrant-households.

   🛑 Important: Do not clone this inside of the immigrant-households repo: instead, it should be a sibling: it should contained in the same folder structure as immigrant-households.

   MacOS/Linux:

   cd your/path/to/parent/directory

   git clone https://github.com/lorae/demographr demographr

   Windows:

   cd your\path\to\parent\directory

   git clone https://github.com/lorae/demographr demographr

Part B: Configure API Access

The IPUMS Terms of Use precludes us from directly sharing the raw microdata extract, however, the data used in this analysis is freely available after setting up an IPUMS USA account, and we provide an automated script that writes the API call and downloads the exact data used in this analysis.

5. Copy the file example.Renviron to a new file named .Renviron in the project root directory. You can do this manually or use the following terminal commands:

   MacOS/Linux:

   cp example.Renviron .Renviron

   Windows (use PowerShell):

   Copy-Item example.Renviron .Renviron

6. Set up your IPUMS USA API key: If you don't already have one, set up a free account on IPUMS USA. Use the new account to login to the IPUMS API key webpage. Copy your API key from this webpage.

7. Open .Renviron (‼️not example.Renviron!) and replace your_ipums_api_key with your actual key. Do not include quotation marks. R will automatically load .Renviron when you start a new session. This keeps your API key private and separate from the codebase.

   🛑 Important: .Renviron is listed in .gitignore, so it will not be tracked or uploaded to GitHub — but example.Renviron is tracked, so do not put your actual API key in the example file.

Part C: Run the analysis scripts

The code for this project is stored in the src folder:

• scripts/: executable analysis scripts

• utils/: accessory modules (functions), subject to unit tests

8. Run all code by sourcing the run-all.R script in your R console:

   source("run-all.R")

📜 License

MIT License (see LICENSE file).

📚 Citation

This repository accompanies ongoing research on immigrant household configurations.

For now, please cite as:
Immigrant Households: Replication Code and Analysis. Maintained by Lorae Stojanovic and Peter Hepburn.
GitHub. https://github.com/lorae/immigrant-households