Git and GitHub tutorial

This is the repository for the Git and GitHub scalable collaborative workflow and methods tutorial prepared and presented by Richard Evans (University of Chicago) for the NYU predoctoral economics training program hosted at New York University Stern School of Business, September 20-22, 2019 and cosponsored by Schmidt Futures. This tutorial focuses on how to use Git and GitHub an a scalable collaborative workflow and as a medium for open source, transparent, and replicable research.

This README.md serves as a syllabus, outline, and reference for the training. This document has ? sections.

1. Schedule
2. Git and GitHub Setup
3. Instructions for installing the Anaconda distribution of Python
4. Jupyter Notebooks
5. Text editor suggestions
6. PEP 8, docstring commenting, and module structure
7. References and Resources

1. Schedule

Friday, September 20

| Time | Topic | Materials | |:----:|:----- |:--------- | 9:00a-12:00p | Git, GitHub, Python setup | Day 1 Slides | | | Openness and collaboration in Econ | | | | Git and GitHub basics | | 12:00-1:00p | Lunch | | 1:00-5:00p | Evaluating GitHub repositories | Project 1 |

Saturday, September 21

| Time | Topic | Materials | |:----:|:----- |:--------- | 9:00a-12:00p | git merge and merge conflicts | Day 2 Slides | | | Data best practices | | 12:00-1:00p | Lunch | | 1:00-5:00p | Collaborative economic modeling project | Project 2 | | | | Exercises 1, 2, 3, 4 |

Sunday, September 22

| Time | Topic | Materials | |:----:|:----- |:--------- | 9:00a-12:00p | Code cleanliness, documentation | Day 3 Slides | | | Tools for extending open models | | | | ParamTools and compute.studio | | 12:00-1:00p | Lunch | | 1:00-3:00p | PEP8, Docstrings, and Sphinx | Project 3 |

2. Git and GitHub Setup

2.1. Install Git

Git is powerful version control software that must be installed on your local computer. You can check if Git is already installed on your machine by typing the following command in your terminal window

git --version

You can install or Git by following the appropriate operating system instructions on the Git download page.

2.2. Sign up for a GitHub account

You should sign up for a GitHub account by going to https://github.com/join. Choose a username that is not too long but that represents you. Be careful on what username you choose. That will be your GitHub handle and will be the main name by which you will be recognized in your interactions on GitHub. And the goal is for you to have many productive interactions on GitHub. My advice is to choose a username that is not "too" silly and not "too" cute.

2.3. Git and GitHub readings and tutorial resources

Some nice Git and GitHub tutorial matierial is available from the following resources.

• Evans (2019) Git and GitHub tutorial chapter
• Chacon and Straub (2014), Pro Git [Fittingly, this book is available open access online at the this link.]
• Sood, Arnav (2019) “Git, GitHub, and Version Control" QuantEcon lecture
• Atlassian Git tutorial. This is a good Git tutorial for interaction with Atlassian's Bitbucket platform, a GitHub competitor. Atlassiang git merge conflict tutorial

3. Instructions for installing the Anaconda distribution of Python

We will be using the Python programming language and many of its powerful libraries for writing the code that will run most of the computational methods we will use during the Boot Camp. Using an open source language, such as Python, has the advantage of being free and accessible for anyone who wishes to learn these materials or contribute to these projects. Being open source also allows Python users to go into the source code of any function to modify it to suit one's needs.

We recommend that each participant download the Anaconda distribution of Python provided by Anaconda, Inc.. We recommend the most recent stable version of Python, which is currently Python 3.7. This can be done from the Anaconda download page for Windows, Mac OSX, and Linux machines.

Python tutorial materials

For this training, we have included in this repository six basic Python tutorials in the Tutorials directory.

1. PythonReadIn.ipynb. This Jupyter notebook provides instruction on basic Python I/O, reading data into Python, and saving data to disk.
2. PythonNumpyPandas.ipynb. This Jupyter notebook provides instruction on working with data using NumPy as well as Python's powerful data library pandas.
3. PythonDescribe.ipynb. This Jupyter notebook provides instruction on describing, slicing, and manipulating data in Python.
4. PythonFuncs.ipynb. This Jupyter notebook provides instruction on working with and writing Python functions.
5. PythonVisualize.ipynb. This Jupyter notebook provides instruction on creating visualizations in Python.
6. PythonRootMin.ipynb. This Jupyter notebook provides instruction on implementing univariate and multivariate root finders and unconstrained and constrained minimizers using functions in the scipy.optimize sub-library.

To further one's Python programming skills, a number of other great resources exist.

• The official Python 3 tutorial site
• QuantEcon.net is a site run by Thomas Sargent (NYU Stern) and John Stachurski (Australia National University). QuantEcon has a very large number of high-quality economics focused computational tutorials in Python. The first three sections provide a good introduction to Python programming.
• Python computational labs of the Applied and Computational Mathematics Emphasis at Brigham Young University.
• Code Academy's Python learning module

4. Jupyter Notebooks

Because we are using Python in this training, students might want to use a Jupyter notebook as their development environment. Furthermore, many of the Python tutorials in the Tutorials folder are Jupyter notebooks. Jupyter notebooks are files that end with the *.ipynb suffix. These notebooks are opened in a browser environment and are an open source web application that combines instructional text with live executable and modifyable code for many different programming platforms (e.g., Python, R, Julia). Jupyter notebooks are an ideal tool for teaching programming as they provide the code for a user to execute and they also provide the context and explanation for the code.

These notebooks used to be Python-specific, and were therefore called iPython notebooks (hence the *.ipynb suffix). But Jupyter notebooks now support many programming languages, although the name still pays homage to Python with the vestigal "py" in "Jupyter". The notebooks execute code from the kernel of the specific programming language on your local machine.

Jupyter notebooks capability will be automatically installed with your download of the Anaconda distribution of Python. If you did not download the Anaconda distribution of Python, you can download Jupyter notebooks separately by following the instructions on the Jupyter install page.

4.1. Opening a Jupyter notebook

Once Jupyter is installed--whether through Anaconda or through the Jupyter website--you can open a Jupyter notebook by the following steps.

1. Navigate in your terminal to the folder in which the Jupyter notebook files reside. In the case of the Jupyter notebook tutorials in this repository, you would navigate to the ~/BootCamp2019/Tutorials/ directory.
2. Type jupyter notebook at the terminal prompt.
3. A Jupyter notebook session will open in your browser, showing the available *.ipynb files in that directory.

• In some cases, you might receive a prompt in the terminal telling you to paste a url into your browser.

4. Double click on the Jupyter notebook you would like to open.

It is worth noting that you can also simply navig