Final Project Grading Summary

Grading for the final project is broken down into four overarching segments:

• Team Process (10 points)
  • Usage of Kanban Board and Implementation of GitHub Best Practices (all 10 points)
• Project Organization (15 points)
  • Implementing appropriate GitHub Repository directory structure and file naming best practices (all 15 points)
• Documentation (25 points)
  • Readable code (5 points)
  • License (5 points)
  • Citations/References (5 points)
  • README.md files (10 points)
• Final Deliverables (50 Points)
  • Portability/Reproducibility (10 points)
  • Data (10 points)
  • Analysis (15 points)
  • Project Website on GitHub (15 points)

This guide will walk you through the details of the project rubric, as well as how to create a GitHub Pages site.

You can scroll down to read through the tutorial step-by-step or click the links above to jump to a specific section of interest.

Table of Contents

You can think about the final deliverable as sections in a report. The table of contents will be as follows:

1. Executive Summary of entire project (4-6 sentences for each section) (Lab 07)

• Overview (Details on Tax Credit Programs, purpose of the evaluation, and hypothesis)
• Data (Description of data sources used in project)
• Methods (Description of statistical and data analytics methods used throughout the course)
• Results (Findings on whether the tax credits were effective overall)

2. Division-specific reports

• Overview of specific social vulnerabilities in division (Lab 02)
• Infographics and Maps of socially vulnerable areas in division (Lab 03)
• Visualization of distribution of tax credits in division and correlation to social vulnerability (Lab 04)
• Measuring intervention and evaluating effectiveness of tax credits with diff-in-diff models (Lab 05)
• Summary of results/findings (Lab 06)

3. Results and Conclusion (Lab 07)

• Detailed summary of findings on the effectiveness of tax credit programs across divisions
• Detailed summary of changes in social vulnerability over time across divisions
• Conclusion/suggestions fo future research

4. Team About Us Page

• Brief bios of each team member

5. References

• List of all articles/resources cited throughout the report. Can be in any citation style.

As outlined above, your team will collaboratively create an overall summary of the tax credits programs and each individual team member will be responsible for contributing an analysis of a U.S. Census division of their choice from the following list:

1. New England Division (Connecticut, Maine, Massachusetts, New Hampshire, Rhode Island, Vermont)
2. East North Central Division (Indiana, Illinois, Michigan, Ohio, Wisconsin)
3. West North Central Division (Iowa, Nebraska, Kansas, North Dakota, Minnesota, South Dakota, Missouri)
4. South Atlantic Division (Delaware, District of Columbia, Florida, Georgia, Maryland, North Carolina, South Carolina, Virginia, West Virginia)
5. East South Central Division (Alabama, Kentucky, Mississippi, Tennessee)
6. West South Central Division (Arkansas, Louisiana, Oklahoma, Texas)
7. Mountain Division (Arizona, Colorado, Idaho, New Mexico, Montana, Utah, Nevada, Wyoming)
8. Pacific Division (Alaska, California, Hawaii, Oregon, Washington)

To further illustrate this process, let’s pretend that we have a PAF 515 Team with four members (Minnie, Mickey, Nala, and Sparky):

• Minnie selects the South Atlantic Division

• Mickey selects the Pacific Division

• Nala selects the West South Central Division

• Sparky selects the Mountain Division

Thus their report will contain the following:

1. Executive Summary of entire project completed as a group (Lab 07)

• Overview (Details on Tax Credit Programs, purpose of the evaluation, and hypothesis)
• Data (Description of data sources used in project)
• Methods (Description of statistical and data analytics methods used throughout the course)
• Results (Findings on whether the tax credits were effective overall)

2. Division-specific reports:

• South Atlantic Division Report by Minnie
  • Overview of specific social vulnerabilities in division (Lab 02)
  • Infographics and Maps of socially vulnerable areas in division (Lab 03)
  • Visualization of distribution of tax credits in division and correlation to social vulnerability (Lab 04)
  • Measuring intervention and evaluating effectiveness of tax credits with diff-in-diff models (Lab 05)
  • Summary of results/findings (Lab 06)
• Pacific Division Report by Mickey
  • Overview of specific social vulnerabilities in division (Lab 02)
  • Infographics and Maps of socially vulnerable areas in division (Lab 03)
  • Visualization of distribution of tax credits in division and correlation to social vulnerability (Lab 04)
  • Measuring intervention and evaluating effectiveness of tax credits with diff-in-diff models (Lab 05)
  • Summary of results/findings (Lab 06)
• South Central Division Report by Nala
  • Overview of specific social vulnerabilities in division (Lab 02)
  • Infographics and Maps of socially vulnerable areas in division (Lab 03)
  • Visualization of distribution of tax credits in division and correlation to social vulnerability (Lab 04)
  • Measuring intervention and evaluating effectiveness of tax credits with diff-in-diff models (Lab 05)
  • Summary of results/findings (Lab 06)
• Mountain Division Report by Sparky
  • Overview of specific social vulnerabilities in division (Lab 02)
  • Infographics and Maps of socially vulnerable areas in division (Lab 03)
  • Visualization of distribution of tax credits in division and correlation to social vulnerability (Lab 04)
  • Measuring intervention and evaluating effectiveness of tax credits with diff-in-diff models (Lab 05)
  • Summary of results/findings (Lab 06)

3. Results and Conclusion (Lab 07)

• Detailed summary of findings on the effectiveness of tax credit programs across divisions
• Detailed summary of changes in social vulnerability over time across divisions
• Conclusion/suggestions fo future research

4. References (Lab 07)

The executive summary and results and conclusion sections summarizing the entire study will be completed by Lab 07 and the division-specific sections of the report will be completed in Labs 02-06 (and simply edited by Lab 07 for any necessary corrections).

Project Section Descriptions

1) Executive Summary:

The executive summary will be a written narrative where you describe the research question for this project, (Ex. Do governmental programs (NMTC and LIHTC) have an impact on social vulnerability in a community?), the data used (US Census Data from the American Community Survey, the CDC’s SVI methodology guidelines, NMTC/LIHTC eligibility and credit distribution data), the methodologies used (correlation calculations, diff-in-diff regression models, etc.), and results (Did the tax credits have an impact nationally or in all of your team’s divisions? Some of your team’s divisions? None of them? Did one program work better than the other?).

2) Division-Specific Reports:

In these sections you will present the labs you create each week and provide a detailed analysis of your specific division.

3) Results and Conclusion:

Similar to the executive summary, give an overarching written summary of the outcomes of your report. Compare and contrast between your team’s divisions and give a conclusion of your findings. You can also provide suggestions for changes you would make in a future study/other factors you would like to explore.

Overall tips to keep in mind:

Note that while the Executive Summary and Results and Conclusion sections require a succinct narrative to give context to the project, most of the sections will focus on describing your methodology to the audience and walking them through the process of generating results in the same format as your labs. These chapters will have more of a tutorial or code-through feel than a written report tone. The goal of these sections is to make your methodology as transparent as possible and allow for others to easily reproduce your work and extend it.

As you complete your labs and construct your website, you will want to annotate your code and provide brief summaries of your findings. There will be prompts given to facilitate this in the lab instructions. If you thoroughly answer those questions, there will not be a need to include much additional text for these sections of the final report. However, feel free to add additional commentary as you see fit.

In past semesters, there has been some confusion about the extent to which the labs that you complete need to be reproducible/how detailed the code-through needs to be, but one thing to keep in mind is that you don’t need to worry about getting too buried in explaining the technicalities of your process. Rather, you want to pretend that you’re presenting your research findings to an audience that is interested in the outcomes of your evaluation. You will want to provide the audience with enough context to understand your report as well as simple instructions on how they can pull your repository to their local machines and then run your labs to recreate your same findings, if needed. However, there is not a need to “teach” the audience how to code/run regressions in R. Your website can be presented as a standalone report.

README Files

You may have noticed that each of the folders in the diagram above contains a README.md. So what is a README file? Make A README.com provides a fun, general overview: https://www.makeareadme.com/. However, more specific to our course purposes, your README files will serve as a summary of each segment of your project.

The main README (listed under the root of your project/“the main folder” of your repository), should give an overview of what the project was about, who worked on the project, and how the repository can be pulled/reproduced (provide a brief overview of the steps to fork and or download the repo.)

The sub-README files that are listed under the subfolders should provide a brief summary of what’s expected in each folder. For example, the labs/wk01/README.MD file should explain that the folder contains the .RMD, .html, and utilities.R files used to analyze and create a report for Lab 01. The README should also include a brief summary of Lab 01 that includes the purpose and findings of the lab.

The READMEs that will come along with your website template are sufficient to describe the template. You do not need to create new READMEs for those folders unless you make edits to the template itself. In that case, edit the existing README to describe what changes you made to the code (CSS/HTML/SASS, etc.).

Portability and Reproducibility

Throughout this course you will learn about the here package, the benefits of relative file paths, and how to import functions from a .R file for reproducibility purposes.

This will allow you to format your final project in a way that anyone who accesses your repository can re-produce your results and run your code on their machine without having to make any changes to your code.

As long as you implement these tools in your labs, you will not need to make any changes for the final report. In addition, as you work on your labs, it will also be beneficial to be mindful of what output from your code chunks should be displayed in the report and what output should be hidden.

For example, while it is important to display numbers that have been calculated, it is not good practice to include warnings and messages from loading packages or downloading data from an API in your report. You can control what you would like to include and exclude in your report by adjusting the settings of your R chunks in RStudio before you knit your .RMD file to an .HTML file.

The resources below can assist you with implementing these concepts:

Data

Almost all of the data needed for this project will be provided in the labs. The only additional step that you will need to take (if you have not already done it for past courses) is to request a census API key: https://api.census.gov/data/key_signup.html.

You will want to keep this API private (think of it as a password), so you will need to store it in a separate password.R file that you create and then import it into your .RMD file where you conduct the rest of your analyses.

To do this you will want to follow these steps:

1. Create a password.R file in the root of the repository folder on your local computer and add one line:

   census_api_key = "YOUR_API_KEY"

2. Save the password.R file and then import it into the .RMD file where you will be working with the Census data:

# Load here package
library(here) 

# Find relative file path to password.R file
my_api <- here::here("password.r")

# Load census_api_key from password.R file
source(my_api)

# Print loaded census_api_key variable to check that the key is correct 
# (remember that you will not want to include this step in your final report 
# as it will reveal the key, but it will allow you as the developer
# to check that you're getting your expected output)
print(census_api_key)

## [1] "abcdefghi"

Note: As an example of the code chunk options mentioned in the Portability and Reproducibility section, the code chunk listed here is written as follows:

Alt-text: Screenshot of R code chunk with options

Important Note: In order for the here package to work properly, you need to always ensure that you are working within your RStudio Project. You can check this by seeing if the name of your repo is next to the blue box on the top right-hand corner of RStudio (click the image below to enlarge):

Alt-text: Screenshot of opened RStudio Project

3. Add the following to your .gitignore file:

# Ignore password file 
password.R

Additional details on how to pull API keys from a separate file are available in the following tutorial Accessing Web APIs:https://info201.github.io/apis.html.

Once you have access to your API key and you have processed/uploaded the data for your individual labs, you will not need to make any additional changes for the final project.

Analysis

All analyses for the final project will be completed in your weekly labs. Besides writing/editing the summaries of these analyses for the final project, you will not need to do any additional analysis work.

Set-Up

In addition to storing your lab files in the repository, you will also use the repository to create your GitHub Pages website.

To begin, you and your teammates will select a GitHub Pages template to serve as the basis for your website. A pre-customized template for the course has been created that you can download here.

This is the template that will be utilized in the Lab 07 tutorial code-through and is suggested for the easiest set-up process.

However, if your team has experience with website development using GitHub Pages/Jekyll and would like to customize your own template, you are welcome to use any of the GitHub Pages approved templates (https://pages.github.com/themes/) or the templates listed under GitHub Pages Resources. The Minima theme is a simple one with a built-in navigation bar (https://github.com/jekyll/minima) and Minimal Mistakes is the template used to create the pre-customized template (https://github.com/mmistakes/minimal-mistakes).

It is not a requirement to have a navigation bar if you include a table of contents on the first page of your site, but if you select your own template that does not have a built in navigation bar and would like to add one, there will be an example of how to create one in this tutorial.

Once you have selected your template, you will need to download and copy the following folders and files from the theme repository to your team’s repository (do NOT change any of the folder names, they may differ slightly from what’s listed below ex. minima’s _sass folder is called _sass/minima and cayman’s assets folder is called assets/css. This is because the themes do not have any files stored in between those folders):

• _includes
• _layouts
• _posts (if applicable, some themes do not have this folder & have docs instead)
• _sass
• assets
• docs (if applicable, some themes do not have this folder & have _posts instead)
• script
• _config.yml
• index.md

Now, if you did not download the course template, you may be curious how to download the folders for other templates. There are two options:

1. The first way is the simplest and will allow you to practice using GitHub Desktop:

   When you navigate to the repository of your choice, you will see a green ‘CODE’ button on the right-hand side of the screen. Click this button and you will get the following dialog box:

   

   Alt-text: Image of green code button on GitHub repos and subsequent dialog box

   Here, you can either select ‘Open with GitHub Desktop’ and your computer application will automatically magically pull the repo to your local computer. Or you can copy the HTTPS link (ex. https://github.com/jekyll/minima.git) and then open GitHub Desktop manually.

   Once in GitHub Desktop, select ‘File’ and ‘Clone Repository’:

   

   Alt-text: Image of GitHub Desktop file dialog menu

   Next, select ‘URL’ and copy and paste the HTTPS link. Select a file location on your local machine and then click ‘Clone’.

   

   Alt-text: Image of GitHub Desktop clone a repository dialog menu

   You will now have all of the files/folders for the template on your local computer and you can copy and paste these into your team’s GitHub repo and then push and commit them to your repository.

   If you do not already have your team’s GitHub repo on your local computer, then you can repeat the steps to pull that repository first and then copy and paste the template folders into the team’s repository, push, and commit them.

2. Alternatively, when you navigate to the repository of your choice and click the green ‘CODE’ button on the right-hand side of the screen, you can select ‘Download ZIP’ to download the files manually.

   You will then need to un-zip the files.

   Afterwards, copy and paste them into your repo folder and push and commit them to your team’s repo using GitHub Desktop OR manually on the GitHub website.

Customization

After you have completed option 1 or 2 above, you will need to navigate to the ‘Settings’ of your GitHub Repository:

Alt-text: Image of GitHub repo settings button

Here, you will want to select the ‘PAGES’ option under ‘Code and Automation’:

Alt-text: Image of GitHub repo settings navigation bar

Next, when you reach the GitHub Pages settings page, you will want to set Source to Deploy from a branch and Branch to main and /(root):

Alt-text: Image of GitHub Pages deployment settings

After this, select ‘Save’. Your website will begin to build. You can return to the main page of your repository and check the building progress under environments on the right-hand side of the page. When it is complete, the environment will be listed as active:

Alt-text: Image of GitHub Pages environments active status

When your site is active, return to the settings page to find the link to your website:

Alt-text: Image of GitHub Pages site link live in settings

Copy and paste the link into a new tab in your browser. Your website should appear with the default index.md file as your home page.

Now that your website is up and going, you can start to customize it and your repository description.

Repository Description

To customize your repository description, you will want to select the settings gear next to ‘About’ on your repository’s main page:

Alt-text: Image of GitHub repository about settings button

This will open a dialog where you can enter a description (briefly describe your project for CPP 528/PAF 515) and select to use your GitHub Pages site or copy and paste the link:

Alt-text: Image of GitHub repository about settings dialog

License

Next, you will want to select a license for your project. Instructions for how to do this are here:

• https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository
• https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository

The MIT License is a popular one for this project, but feel free to choose one amongst your team. You will also want to be sure that you include all of your teammates’ names on the license.

Website Pages

Finally, you can begin customizing your website by changing the contents of the index.md file. You can also upload additional .md and .html files to your repository and update the _config.yml file to include these pages on your website.

You can use your index.md file to create a table of contents for your report.

Example Index.md page:

---
layout: page
title: "Introduction"
---

<p> Brief intro message/summary of project </p>

<h2> Table of Contents </h2>
- [Executive Summary](insert executive summary page URL)
- [South Atlantic Division](insert South Atlantic Division Report URL)
- [Pacific Division](insert Pacific Division URL)
- [West South Central Division](insert West South Central Division URL)
- [Mountain Division](insert Mountain Division URL)
- [Results and Conclusion](insert results and conclusion URL)
- [References](insert references URL)
- [About Us](insert about us URL)
- [Project Repository](insert URL to page that lists project repository URL)

The pages of your website do not have to exactly follow the layout listed above, but this gives an overview of how to plan your sections.

For instance, you can omit the references page if you choose to include a references section at the end of each part of your report. Similarly, if your template includes a GitHub icon that allows you to link to your repository, you can use that instead of creating a separate page with the link. You can also choose to break down the parts of the report into more than 3 sections.

As long as you’ve covered all required sections of the report and clearly labeled them, feel free to be creative in designing your website layout.

---
layout: page
title: "Navigation example"
---

<ul class="nav">
  <li><a href="https://r-class.github.io/cpp-528-example-repo/exec">Executive Summary</a></li>
  <li><a href="https://r-class.github.io/cpp-528-example-repo/partone">Part I</a></li>
  <li><a href="https://r-class.github.io/cpp-528-example-repo/parttwo">Part II</a></li>
  <li><a href="https://r-class.github.io/cpp-528-example-repo/partthree">Part III</a></li>
  <li><a href="https://r-class.github.io/cpp-528-example-repo/references">References</a></li>  
  <li><a href="https://r-class.github.io/cpp-528-example-repo/about_new">About Us</a></li> 
</ul>

****************************
INSERT YOUR PAGE CONTENT
****************************

<style>
  ul.nav {
    margin:0;
    padding:0;
    list-style:none;
    height:36px; line-height:36px;
    background:#0d7963; /* you can change the backgorund color here. */
    font-family:Arial, Helvetica, sans-serif;
    font-size:13px;
}
ul.nav li {
    border-right:1px solid #189b80; /* you can change the border color matching to your background color */
    float:left;
}
ul.nav a {
    display:block;
    padding:0 28px;
    color:#ccece6;
    text-decoration:none;
}
ul.nav a:hover,
ul.nav li.current a {
    background:#086754;
}
</style>