docs: edited and formatted md files using makedocs

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci 
+on:
+  push:
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -1,6 +1,7 @@
 # environment variables
 .env
 .Renviron
+/venv
 
 # Output files
 /outputs

README.md

@@ -1,12 +1,12 @@
 # Indicators of Potential Disadvantage
 
-This project automates DVRPC's Indicators of Potential Disadvantage (IPD) analysis, including data download, processing, and export. For more on IPD analysis, see [Equity Analysis for the Greater Philadelphia Region v2.0](https://www.dvrpc.org/webmaps/ipd/).
+This project automates DVRPC's Indicators of Potential Disadvantage (IPD) analysis, including data download, processing, and export. For more on IPD analysis, see [Equity Analysis for the Greater Philadelphia Region](https://www.dvrpc.org/webmaps/ipd/).
 
 ## Getting the Code and Software
 
-1. Clone the repository.
-2. Download and install R from https://www.r-project.org/
-3. Download and install R Studio from https://www.rstudio.com/products/rstudio/#Desktop
+1. Clone the [Github repository](https://github.com/dvrpc/ipd)
+2. [Download and install R](https://cran.rstudio.com/)
+3. [Download and install R Studio](https://posit.co/download/rstudio-desktop/)
 
 ## Installing Package Dependencies
 
@@ -49,14 +49,9 @@ Please provide your own API Key (this is required for the `tidycensus` package,
 
 After the code has finished, outputs are saved in the /outputs subdirectory of where you cloned the repository on your local machine, including:
 
-- ipd.csv: tract-level statistics and scores for IPD's nine indicators
-- ipd.shp: spatial version of ipd.csv
-- breaks_by_indicator.csv: bin breaks by indicator
-- counts_by_indicator.csv: census tract counts by bin and indicator
-- summary_by_indicator.csv: basic summary stats by indicator
-- mean_by_county.csv: population-weighted county means by indicator
-
-## Additional Information
-
-- [documentation/discussion.pdf](https://github.com/dvrpc/ipd/blob/master/documentation/discussion.pdf) shows the essential math required to compute IPD scores.
-- [documentation/script_reference.pdf](https://github.com/dvrpc/ipd/blob/master/documentation/script_reference.pdf) is a companion document to the script and explains the way the script downloads data and implements IPD analysis, code chunk by code chunk.
+- ipd_`ipd_year`.csv: tract-level statistics and scores for IPD's nine indicators
+- ipd_`ipd_year`.shp: spatial version of ipd.csv
+- breaks_by_indicator_`ipd_year`.csv: bin breaks by indicator
+- counts_by_indicator_`ipd_year`.csv: census tract counts by bin and indicator
+- summary_by_indicator_`ipd_year`.csv: basic summary stats by indicator
+- means_by_county_`ipd_year`.csv: population-weighted county means by indicator

docs/index.md

@@ -0,0 +1,39 @@
+## Background
+DVRPC's [Indicators of Potential Disadvantage](https://www.dvrpc.org/webmaps/ipd/#home) (IPD) identify populations of interest under Title VI of the Civil Rights Act and the Executive Order on Environmental Justice (#12898) using American Community Survey (ACS) five-year estimates from the U.S. Census Bureau. IPD analysis assists both DVRPC and outside organizations in equity work by identifying populations of interest, including youth, older adults, female, racial minority, ethnic minority, foreign-born, limited English proficiency, disabled, and low-income populations at the census tract level in DVRPC's nine-county region.
+
+Below is an overview of the calculations required to conduct IPD analysis and is meant to provide enough information to replicate prior years of IPD analysis. 
+
+## IPD Indicators and ACS Data
+| IPD Indicator | ACS Data Table | Protected Class Representation | Authorizing Source/Guiding Document |
+| ------------- | -------------- | ------------------------------ | ----------------------------------- |
+| Youth | B09001: Population Under 18 Years by Age | Age | FHWA's Title VI Program and Related Authorities: 23 CFR 200 |
+| Older Adults | S0101: Age and Sex | Age | FHWA's Title VI Program and Related Authorities: 23 CFR 200 |
+| Female | S0101: Age and Sex | Sex | FHWA's Title VI Program and Related Authorities: 23 CFR 200 |
+| Racial Minority | B02001: Race | Race and Minority | Executive Order 12898, Title VI of the Civil Rights Act of 1964, FHWA's Title VI Program and Related Authorities: 23 CFR, and Title VI Requirements and Guidelines for FTA Recipients |
+| Ethnic Minority | B03002: Hispanic or Latino Origin by Race | Minority and National Origin | Executive Order 12898, Title VI of the Civil Rights Act of 1964, FHWA's Title VI Program and Related Authorities: 23 CFR, and Title VI Requirements and Guidelines for FTA Recipients |
+| Foreign-Born | B05012: Nativity in the United States | National Origin | Title VI of the Civil Rights Act of 1964, FHWA's Title VI Program and Related Authorities: 23 CFR, and Title VI Requirements and Guidelines for FTA Recipients |
+| Limited English Proficiency | S1601: Language Spoken at Home | Limited English Proficiency and National Origin | Title VI of the Civil Rights Act of 1964, FHWA's Title VI Program and Related Authorities: 23 CFR, and Title VI Requirements and Guidelines for FTA Recipients |
+| Disabled | S1810: Disability Characteristics | Disability | FHWA's Title VI Program and Related Authorities: 23 CFR |
+| Low-Income | S1701: Poverty Status in Past 12 Months | Low-Income | Executive Order 12898 and FHWA's Title VI Program and Related Authorities: 23 CFR 200 |
+
+## IPD Score
+IPD Scores can be presented in two ways: individual IPD score and composite IPD score.
+
+### Individual IPD Score
+For each indicator, percent estimates are split into five bins, which are detailed in the table below. There is one exception to the standard deviation classification: if `mean(pop) - (1.5 * stdev(pop))` is a negative value, it is manually reassigned to 0.1. This ensures that at least some census tracts fall in the bottom bin regardless of the spread of the indicator. 
+
+`p` = percent estimate  
+`mean(pop)` = mean for indicator population  
+`stdev(pop)` = standard deviation for indicator population  
+
+| IPD Score | IPD Classification | Standard Deviations |
+|:---------:|:------------------:|:-------------------:|
+| 0 | Well Below Average | p < mean(pop) - (1.5 * stdev(pop)) |
+| 1 | Below Average | mean(pop) - (1.5 * stdev(pop)) <= p <  mean(pop) - (0.5 * stdev(pop))|
+| 2 | Average | mean(pop) - (0.5 * stdev(pop)) <= p < mean(pop) + (0.5 * stdev(pop))|
+| 3 | Above Average | mean(pop) + (0.5 * stdev(pop)) <= p < mean(pop) + (1.5 * stdev(pop))|
+| 4 | Well Above Average | p >= mean(pop) + (1.5 * stdev(pop))|
+
+### Composite IPD Score
+The composite IPD score is computed by summing the individual IPD scores. In theory, the composite IPD score can range from 0 to 36, since each indicator's IPD score can be as high as 4. In practice, the mean composite score in 2021 is 17.57, and the highest observed composite score is 32.
+