# Text Normalization

The process of taking a list of words and transforming it into a more uniform sequence.

# Text editor 

A program for creating and editing plain text files. Unlike word processors such as LibreOffice and Word, which create complex documents in the form of archives that include formatting information and other metadata, a plain text editor creates a single file. Programmers tend to use plain text files because computers can work with them easily. Sublime Text, Nano, and VI are examples of text editors.



# Firefox

## What it is

[Firefox](https://www.mozilla.org/en-US/exp/firefox/) is a free to download web browser built by the [Mozilla Foundation](https://foundation.mozilla.org/en/about/), a non profit organization. Firefox allows users to access websites on the internet. 

## Why we use it

For the Digital Humanities Research Institute, we use Firefox because it works on Windows and Mac operating systems, it is frequently updated, and it values user privacy. 

## Installation instructions: macOS

### Step 1: Go to the Firefox download webpage

Visit the [Firefox download page](https://www.mozilla.org/en-US/firefox/new/?utm_medium=referral&utm_source=support.mozilla.org) in your pre-installed browser, such as Safari.

![Image showing the Firefox download page for Mac](/images/guides/firefox_mac_01.png)

### Step 2: Download Firefox Installer

Click on the `Download Firefox` button.

![Image showing where to click to download Firefox](/images/guides/firefox_mac_02.png)

### Step 3: Move Firefox to the Applications folder

Once the download has finished, the file should open by itself and pop open a Finder window containing the Firefox application. Drag the Firefox icon on top of the Applications folder in order to copy it there. This action will begin the installation, which should only take a few seconds to complete.

![Image showing how to drag Firefox and drop it in Applications folder](/images/guides/firefox_mac_03.png)

### Step 4: Eject the Firefox installation file

After dragging the Firefox app to the Applications folder, go back to the desktop screen, move the mouse cursor over the Firefox icon, and click it while holding down the `control` key on your keyboard. Then select the `Eject Firefox` option.

![Image showing how to eject the Firefox installation file](/images/guides/firefox_mac_04.png)

### Step 5: Open Firefox 

You can now start Firefox by double-clicking on it in the Applications folder. The first time you open Firefox, you should receive a dialogue box that asks you if you are sure you would like to open Firefox. Here you should click `Open`. 

![Image showing the dialogue box that opens only on the first time starting Firefox](/images/guides/firefox_mac_05.png)

### Step 6: Finished!

Firefox will now open. Congratulations, you have completed installing Firefox!

![Image showing a fresh install of Firefox](/images/guides/firefox_mac_06.png)

## Installation instructions: Microsoft Windows 10

### Step 1: Go to the Firefox download webpage

Visit the [Firefox download page](https://www.mozilla.org/en-US/firefox/windows/?utm_medium=referral&utm_source=support.mozilla.org) in your pre-installed browser, such Internet Explorer or Edge.

![Image showing the Firefox download page for Windows](/images/guides/firefox01.png)

### Step 2: Download Firefox Installer

Click the `Download Now` button. This will prompt a notification bar at the top or bottom of your screen with an option to open, run, or save the Firefox Installer file. 

![Image showing the Firefox Installer download page for Windows](/images/guides/firefox02.PNG)

### Step 3: Run Firefox Installer

Click on the `Run` or `Open` option in the notification bar to start the process. 

![Image showing the Open file option for the Firefox Installer in the notification bar](/images/guides/firefox03.png)

### Step 4: _User Account Control_ Settings

A _User Account Control_ dialogue may open that asks you to allow the Firefox Installer to make changes to your device. Click `Yes` to start the installation.

![Image showing the User Account Control dialogue](/images/guides/firefox04.PNG)

### Step 5: Firefox Installation

Wait for Firefox to finish installing.

![Image showing the Firefox installer running](/images/guides/firefox05.PNG)

### Step 6: Completing Firefox Installation

When the installation is complete, Firefox will open. 

Congratulations, you have successfully installed Firefox! 

![Image showing a fresh install of Firefox](/images/guides/firefox06.PNG)


Installing Firefox


# Git (and Git Bash)

## What it is

Git is a version control software used to manage and track changes made to files and project folders over time. We will be installing it on our local machine and live on the hard drive on your laptop. 

Note that Git is a separate software than GitHub. Alternatively, GitHub is a web-based software that lives on the Internet. You can create an account at [github.com](https://github.com).

These instructions are for Git, not GitHub.

## Why we use it

For the Digital Humanities Research Institute, we use Git because it is an open-source tool that was built to support individual version control needs as well as collaborations across time and space. In our curriculum, it is one of the foundational tools we teach because through understanding how Git works, we learn a lot more about how computers and different softwares work.

## Installation instructions: macOS Catalina

### Step 1: Open a terminal

The terminal, also known as command line or bash, is a text interface for interacting with - or talking to - your computer. 

This is different from how we usually interact with our computers. Usually, we use softwares that come with a graphical user interface - GUI, pronounced *gooey* - and we point and click on buttons, or drag and drop things. We might also type, like in Microsoft Word. However, in Word, you're not really talking to your computer until you click "Save" and name the file. It's at this point that you're telling your computer to perform a task in relation to the document or file you are creating or working on. 

With Git, we talk to the computer through the terminal, so let's go ahead and open that now.

To open the terminal, open spotlight search (default way to do this is by hitting command and the space bar) and type in “terminal”. Select the application called terminal and press the return key. This should open up an app with a black background. When you see your username followed by a dollar sign, you’re ready to start using command line.

![Image shows terminal, a black box in which you can enter text to interact with your computer. Look for your username and the dollar sign at the top.](/images/guides/terminal.png)

### Step 1: Type the following command into the terminal

Using the terminal, we will use a set of specific phrases - or commands - that tell the computer what we want it to do. 

First, we want to tell the computer to install the Command Line Tool Package. This give Mac users many commonly used tools, utilities, and compilers, including make, GCC, clang, perl, svn, size, strip, strings, libtool, cpp, what--and Git.

Install this package by typing the following command into your terminal and clicking enter.

```bash
$ xcode-select --install
```

![Image shows terminal with the above command typed in.](/images/guides/commandlinetools.png)

### Step 2: Test the Install

Now, let's make sure Git has been installed successfully. 

- Type the following command into the terminal:

```bash
$ git
```

The terminal should print something like (note that this is truncated):

```bash
usage: git [--version] [--help] [-C <path>] [-c name=value]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]


```

[shows terminal on mac osx](/images/guides/osxterminalgit.png) 

## Installation instructions: Microsoft Windows 10

### Step 1: Download Git for Windows

First, go to this website: https://git-scm.com/download/win

From the option, select "Click here to download manually" and save the file. 

![Image shows webpage with downloads and circles the desired option](/images/guides/windowsdlgit.png)

### Step 2: *Click* on the git installer:

![git installation icon, looks like a tree branch inside 4 colored squares](/images/guides/git00.png)

### Step 3: Accept the license and *click* `Next`:

 ![license acceptance window](/images/guides/git01.png)

### Step 4: Select the installation folder:

The default folder should be fine. *Click* `Next`.

![installation folder browser with text window showing folder path](/images/guides/git02.png)

### Step 5: Select the components to be installed: 

Again, the default is fine here.

![list of check boxes showing install options: additional icons, on the desktop, Windows Explorer integration, Git Bash, Git GUI, Git LFS, Associate *.git configuration files with the default text editor, associate .sh files to be run with bash,  use a true type font in all console windows, check daily for git for windows, check daily for git console updates](/images/guides/git03.png)

- Windows Only: select start menu folder (default is fine):

![textbox with browse button listing start menu folder options](/images/guides/git04.png)

### Step 6: Choose the default editor used by Git. 

Select `Visual Studio Code` as the default editor. (Note that you must install `Visual Studio Code` first before you can move forward past this step of the Git install.) 

*Click* `Next` when you're ready.

![installation menu containing drop down of editor options: nano, vim, notepad++, visual studio code, visual studio code insiders](/images/guides/git06.png)

### Step 7: Choose the "Use Git from the Windows Command Prompt" radio button.

*Click* `Next` when you're ready.

![three radio buttons: use git from git bash, use git from windows command prompt, use git and optional unix tools from the windows command prompt](/images/guides/git07.png) 

### Step 8: Choose the HTTPS transport backend (the default is fine).

*Click* `Next` when you're ready.

![list of radio button optionsL 1) use the OpenSSL library, 2) use the native windows secure channel library](/images/guides/git08.png)

### Step 9: Configure the line ending conversions.

Again, the default is fine. *Click* `Next` when you're ready.

![list of radio button options: 1) checkout Windows-style, commit unix-style , 2) checkout is as is, commit is unix style, 3)checkout as is, commit is as is](/images/guides/git09.png)

### Step 10: Configure the terminal emulator.

On the 'configuring the terminal emulator to use with Git Bash' window, choose the "Use Windows default console window" option.

![two radio buttons: 1) Use MinTTY, 2) use Windows default console window](/images/guides/git10.png)
Note: Do not choose "Use MinTTY (the default terminal of MSYS2)" as that MinTTY wil break Python. 

### Step 11: Configure the extra options. 

Again, the defaults are fine. *Click* `Next` when you are ready.

![check boxes: 1) enable file system caching, 2) enable git credential manager, 3) enable symbolic links](/images/guides/git11.png)

### Step 12: Git should now be installing.
 
![image of progress bar](/images/guides/git12.png)

### Step 13: Finish the installation.

*Click* through the rest of the install, leaving the defaults, and then *click* `Finish` on the last window.

![final installation window that says "completing the git setup wizard"](/images/guides/git13.png)

### Step 14: Test the install.

Now, let's make sure Git has been installed successfully. 

- Open Your terminal 

- Type the following into the terminal:

```bash
$ git
```

The terminal should print something like (note that this is truncated):

```bash
usage: git [--version] [--help] [-C <path>] [-c name=value]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]
```

## Updating an earlier development version of Git (that is already installed) 

If you already have Git installed, but want to check the version or update it, these instructions are for you!

### Step 1: Check which development version of Git is currently installed on the computer.  

Open your terminal and type the following command into the terminal:

```bash 
$ git --version
```

Check for the most recent development version of Git on their website [here](https://git-scm.com/downloads).

**How do I open the terminal again?**
To open the terminal, open spotlight search (default way to do this is by hitting command and the space bar) and type in “terminal”. Select the application called terminal and press the return key.

### Step 2: Update your version - if needed.

If you already have Git, but you want to update it, open [the Git website downloads page](https://git-scm.com/downloads) in you browser and follow the posted download instructions according to the computer type: Mac, Linux/Unix, or Windows.  

### Step 3: Recheck your development version by repeating step 1.

When you think you've updated your software, it is good practice to check in with you computer to make sure its been updated. 

First, close, and re-open your terminal. 

Then type the following command into the terminal:

```bash 
$ git --version
```

If the version you are seeing is not correct, retry step 2.


Installing Git


# Natural Language Toolkit

## What it is

[NLTK](http://www.nltk.org/) stands for Natural Language Tool Kit, and it is an open source Python library for analyzing language data. It is used for Python programs that work with text in statistical natural language processing (NLP). In plain terms, NLTK allows users to work with collections of text to clean, categorize, and analyze that text. As such, it is an excellent tool for text analysis.

ATTENTION: NLTK comes installed with the [conda](conda.md) package management system and may already be installed in your environment.

## Why we use it

For the Digital Humanities Research Institute, we use NLTK because it is a rich library of natural language processing tools and datasets. It works very well with Python, allowing users to write powerful natural language processing programs with relatively short sections of code. 

## Installation instructions: macOS Catalina

Before getting started, there are some things to note about software versions. First, these installation instructions work with recent versions of Mac OS X, like Catalina, Mojave, High Sierra, and they *should* work with older versions as well. 

Second, if you have completed the Python workshop, you have probably downloaded the Anaconda package. Therefore, you may already have NLTK installed on your computer. The below instructions begin with an NLTK check and, in the case that you do not have NLTK installed, walk you through the installation.

Finally, NLTK requires Python versions 3.5, 3.6, 3.7, or 3.8. The most recent Anaconda installation (which you downloaded for the Python workshop) comes with Python 3.8, so you should already have the relevant version of Python.

### Step 1: Checking if NLTK is already installed

Open an OSX terminal and type `python` to launch a Python interpreter. You should get something like this:

![image of starting python interpreter](/images/guides/nltk_mac_1.png)

Load NLTK by typing the following in your environment and *pressing* 'enter':

![image of importing nltk](/images/guides/nltk_mac_2.png)

If this step fails, you will get an error, and you should  follow the next step, Install NLTK. If it is already installed, nothing will happen and you'll see the three `>>>` in the window. In that case, skip to Step 3, [Install NLTK Data](#step-3:-install-nltk-data-with-the-gui-(mac)).

### Step 2: Install NLTK (MAC)

Exit the Python interpreter (`control-d` or `quit()`. Once you're back in your terminal, type:

```console
$ conda install nltk -y
```

When you press enter, the terminal should look something like the following:

![image of installing nltk](/images/guides/nltk_mac_3.png)

When it's finished, go back into the Python interpreter to import NLTK, typing `import NLTK` after the `>>>`. If it downloaded correctly, nothing will happen and you'll see the three `>>>` in the window.  In that case, continue to step 3.

### Step 3: Install NLTK Data with the GUI (MAC)

You then need to install the data that NLTK relies on to function. This may take several minutes (depending on your internet connection). Some packages may fail installation due to being outdated - this is alright, and will not be a problem for our lessons. If you get an error about a package failing, just shut down the install and skip to [installing NLTK with the command line](#step-4:-install-nltk-data-with-the-command-line-(mac)).

In your Python environment run the following command *after* import nltk:

```pycon
>>> nltk.download()
```

For example, the interpreter above would now look like:

![image of downloading nltk on interpreter](/images/guides/nltk_mac_4.png)

The Python environment that the GUI was launched from should now have a message that looks something like this:

```pycon
showing info https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/index.xml
``` 

Now, look for the NLTK download GUI - this will appear automatically but may appear hidden behind your browser window or behind where you are working in Python.

![NLTK downloader interface with four tabs: collections, corpora, models, all packages](/images/guides/nltk_downloader.png)

Click on the first tab (collections), and on the first record on that tab: all. Then, click the "download" button on the left hand side of that window.

This may take several minutes (depending on your internet connection). *Press* the refresh button if the install is stalling and ignore errors.

If something goes wrong, proceed to [installing NLTK with the command line](#step-4:-install-nltk-data-with-the-command-line). If nothing happens, then skip to the [install test](#step-5:-test-installation-(mac)).

### Step 4: Install NLTK Data with the Command Line (MAC)

NLTK also provides a text based download tool, which you can download with the Command Line.

In your interactive Python environment, type the following commands after importing nltk

```pycon
nltk.download('all', halt_on_error=False)
```

The interpreter above should now look something like:

![image of entering nltk data download command on command line](/images/guides/nltk_mac_5.png)

If the command is successful, the terminal will print out something like:

![image of downloading nltk data on command line](/images/guides/nltk_mac_6.png)

It will take a few minutes to download. At the end, your terminal should look like this, bringing you back to the python interpreter prompt:

![image of completing the nltk data download on command line](/images/guides/nltk_mac_7.png)

### Step 5: Test Installation (MAC)

When the installation is complete, close the NLTK Downloader and check your installation. You need to be in a Python environment such as an interpreter or Jupyter notebook.

**Brown**

In your Python environment, run the following code:

```pycon
from nltk.corpus import brown
``` 

If your code runs and nothing happens (no error message and nothing printed to the screen), congratulations! 

***Book**

Check that the books corpus installed properly by typing:

```pycon
from nltk.book import *
```

If installed successfully, you should see the following:

![images of nltk books imported into command line](/images/guides/nltk_mac_8.png)

**Penn Parts of speech**

Check that the parts of speech tagger is installed correctly by typing the following:

```pycon
nltk.help.upenn_tagset('NN')
```

If installed successfully, you should see the following:

![image of nltk Part of Speech tagger installed into command line](/images/guides/nltk_mac_9.png)

---

## Installation instructions: Microsoft Windows 10

Before getting started, there are some things to note about software versions. First, these installation instructions work with Microsoft Windows 10.

Second, if you have completed the Python workshop, you have probably downloaded the Anaconda package. Therefore, you may already have NLTK installed on your computer. The below instructions begin with an NLTK check and, in the case that you do not have NLTK installed, walk you through the installation.

Finally, NLTK requires Python versions 3.5, 3.6, 3.7, or 3.8. The most recent Anaconda installation (which you downloaded for the Python workshop) comes with Python 3.8, so you should already have the relevant version of Python.

### Step 1: Checking if NLTK is already installed

Open a Windows terminal (your `command line`) and type `python` to launch a Python interpreter. You should get something like this:

```pycon
$ python
Python 3.6.5 |Anaconda, Inc.| (default, Apr 26 2018, 08:42:37) 
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> 
```
Load NLTK by typing the following in your environment and *pressing* 'enter':

```pycon
Python 3.6.5 |Anaconda, Inc.| (default, Apr 26 2018, 08:42:37) 
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import nltk
```

If this step fails, you will get an error, and you should follow the next step, Install NLTK. If it is already installed, nothing will happen and you'll see the three `>>>` in the window. In that case, skip to Step 3, [Install NLTK Data](#step-3:-install-nltk-data-with-the-gui-(windows)).

### Step 2: Install NLTK (Windows)

Exit the Python interpreter (`control-d` or `quit()`. Once you're back in your terminal, type:

```console
$ conda install nltk -y
```

The terminal should print something like the following:

```pycon
Collecting package metadata (current_repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: /Users/filipacalado/opt/anaconda3

  added / updated specs:
    - nltk
```

When it's finished, go back into the Python interpreter to import NLTK, typing `import NLTK` after the `>>>`. If it downloaded correctly, nothing will happen and you'll see the three `>>>` in the window.  In that case, continue to step 3.

### Step 3: Install NLTK Data with the GUI (Windows)

You then need to install the data that NLTK relies on to function. This may take several minutes (depending on your internet connection). Some packages may fail installation due to being outdated - this is alright, and will not be a problem for our lessons. If you get an error about a package failing, just shut down the install and skip to [installing NLTK with the command line](#step-4:-install-nltk-data-with-the-command-line-(windows)).

In your Python environment run the following command *after* import nltk:

```pycon
>>> nltk.download()
```

For example, the interpreter above would now look like:

```pycon
Python 3.6.5 |Anaconda, Inc.| (default, Apr 26 2018, 08:42:37) 
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import nltk
>>> nltk.download()

The Python environment that the GUI was launched from should now have a message that looks something like this:

```pycon
showing info https://raw.githubusercontent.com/nltk/nltk_data/gh-pages/index.xml
``` 

Now, look for the NLTK download GUI - this will appear automatically but may appear hidden behind your browser window or behind where you are working in Python.

![NLTK downloader interface with four tabs: collections, corpora, models, all packages](/images/guides/nltk_downloader.png)

Click on the first tab (collections), and on the first record on that tab: all. Then, click the "download" button on the left hand side of that window.

This may take several minutes (depending on your internet connection). *Press* the refresh button if the install is stalling and ignore errors.

If something goes wrong, proceed to [installing NLTK with the command line](#step-4:-install-nltk-data-with-the-command-line-(windows)). If nothing happens, then skip to the [install test](#step-5:-test-installation-(windows)).

### Step 4: Install NLTK Data with the Command Line (Windows)

NLTK also provides a text based download tool, which you can download with the Command Line.

In your interactive Python environment, type the following commands after importing nltk

```pycon
nltk.download('all', halt_on_error=False)
```

The interpreter above should now look something like:

```pycon
Python 3.6.5 |Anaconda, Inc.| (default, Apr 26 2018, 08:42:37) 
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import nltk
>>> nltk.download('all', halt_on_error=False)
```

If the command is successful, the terminal will print out something like:

```pycon
[nltk_data] Downloading collection 'all'
[nltk_data]    | 
[nltk_data]    | Downloading package abc to
[nltk_data]    |     /usr/local/share/nltk_data...
[nltk_data]    |   Package abc is already up-to-date!
                ...omitted...
[nltk_data]    | Downloading package mwa_ppdb to
[nltk_data]    |     /usr/local/share/nltk_data...
[nltk_data]    |   Package mwa_ppdb is already up-to-date!
[nltk_data]    | 
[nltk_data]  Downloaded collection 'all' with errors
Out[2]: True
```

### Step 5: Test Installation (Windows)

When the installation is complete, close the NLTK Downloader and check your installation. You need to be in a Python environment such as an interpreter or Jupyter notebook.

**Brown**

In your Python environment, run the following code:

```pycon
from nltk.corpus import brown
``` 

If your code runs and nothing happens (no error message and nothing printed to the screen), congratulations! 

***Book**

Check that the books corpus installed properly by typing:

```pycon
from nltk.book import *
```

If installed successfully, you should see the following:

![images of nltk books imported into command line](/images/guides/nltk_mac_8.png)

**Penn Parts of speech**

Check that the parts of speech tagger is installed correctly by typing the following:

```pycon
nltk.help.upenn_tagset('NN')
```

If installed successfully, you should see the following:

![image of nltk Part of Speech tagger installed into command line](/images/guides/nltk_mac_9.png)


Installing NLTK


# Python (and Anaconda)

## What it is

[Anaconda](https://www.anaconda.com/download/) is a distribution of Python. It provides a Python programming environment, the Jupyter notebook environment, and the conda package management system. 

## Why we use it

For the Digital Humanities Research Institute, we are choosing to use and download Anaconda as it allow us to get all the required software for this institute (python, conda, and the Jupyter notebook environment) in a single download. Anaconda also includes many useful packages for machine learning, and data analysis that will be helpful should you choose to go further in your Python journey!. 

## Before we begin...

Let's check if you have Anaconda already installed on your computer.

Try to open the Anaconda Prompt (On Mac, click on the "magnifying glass" icon (also known as Spotlight) on the upper-right hand corner of your menubar and type `Anaconda`. On Windows, press the <kbd>Windows</kbd> key and type `Anaconda`). If no option comes up, you most likely don't have it installed.

If you don't have Anaconda installed on your computer, you can follow either the macOS Catalina or Windows instructions. If you do have Anaconda and only need to update Anaconda to the newest version for this workshop, you can go to our Insight section for [Keeping your Anaconda installation up to date](https://github.com/DHRI-Curriculum/insights/blob/v2.0/pages/anaconda.md).

## Installation instructions: macOS (Mojave, Catalina, Big Sur etc.)

While the installation instructions below is for macOS Catalina (10.15) and above, this installation instruction should work for older macOS versions. Older macOS versions (10.13 (High Sierra) to 10.14 (Mojave)) can also skip step 3 in the installation process. For older versions, please check out the [Anaconda documentation](https://docs.anaconda.com/anaconda/install/#old-os). You can check your macOS version by clicking the "apple" icon on the upper-left corner of your menu bar and choose "About This Mac." You should see the macOS name followed by the version number. Should you run into any trouble, you can also find solution to common installation issues [here](https://docs.anaconda.com/anaconda/user-guide/troubleshooting/).

Another note, for MacOS Catalina and Big Sur, the Terminal window will likely show the `%` (percent sign) prompt, which is default for the newest version of Terminal. If you have an older version, it will show the `$` (dollar sign) prompt. Either prompt works the exact same, so it does not matter if yours is different from the instructions. Just be aware that they are interchangeable in these instructions.
 
### Step 1: Download Python 3.+

Visit the [Anaconda website](https://www.anaconda.com/products/individual) on your internet browser, such as Firefox or Chrome, and scroll to the bottom of the page. Here, click on the **64-Bit Graphical Installer** under the MacOS Python 3.+ version menu. Our screenshot below shows python 3.8, but any latest **python 3.+** version will work with our instructions and the institute.  

![Screenshot: Anaconda download webpage with 3.8 button highlighted](/images/guides/conda_installer_mac.png)

You can ignore this. Just close this screen.  

![Screenshot: Anaconda thank you image](/images/guides/anaconda01.png)

You can either let your browser open with the Installer, or save it and open it yourself.

### Step 2: Run Anaconda Installer

After the download has completed, if it doesn't open automatically, double-click on the installer file you just saved on your computer. Click `Continue`:  

![Screenshot: Anaconda installer: security image](/images/guides/anaconda02-5.png)

You should then see the initial install screen. Click `Continue`:  
 
 ![Screenshot: initial installation image](/images/guides/anaconda03.png)

Click `Continue` again:  

![Screenshot: software licence agreement image](/images/guides/anaconda04.png)

Accept the license by clicking `I Agree`:  
 
![Screenshot: licence agreement](/images/guides/anaconda05.png)

Click `Install`. Only change the install location if you know what you are doing:  

![Screenshot: standard install on macintosh](/images/guides/anaconda06.png)

Click `Install Microsoft VSCode`. If it is already installed, click `Continue`:  

![Screenshot: menu option to also install vscode](/images/guides/anaconda08.png)

This is the final installation window. Just click `Close`:  

![Screenshot: final installation window for anaconda](/images/guides/anaconda09.png)

You can move the installer to the Trash to save space on your hard drive by clicking `Move to Trash`:  

![Screenshot: move to trash image](/images/guides/anaconda10.png)

### Step 3: Run conda from your terminal

**NOTE: this step only applies to MacOS Catalina and Big Sur. For all previous version of MacOS, skip to Step 4**

This step ensures that you will be able to run anaconda directly from your terminal.  

Open your macOS terminal. You can find your terminal by clicking the "magnifying glass" icon (also known as `Spotlight`) on the upper-right hand corner of your menubar or press <kbd>command</kbd> + <kbd>space</kbd>, type `Terminal` and press <kbd>enter</kbd>. In your terminal, you will run a few lines of code to make sure that the terminal knows how to start Anaconda. Type in the following lines of code, after the `%`, pressing <kbd>enter</kbd> after each line:  

```console
cd ~
bash
source .bash_profile
conda init zsh
```

If this step is successful, when you close and re-open terminal, your command prompt `%` should have (base) in front of it.

### Step 4: Check if Anaconda and Python are successfully installed

Open the macOS terminal. You can find your terminal by clicking the "magnifying glass" icon (also known as Spotlight) on the upper-right hand corner of your menubar or press <kbd>command</kbd> + <kbd>space</kbd>, type `Terminal` and press <kbd>enter</kbd>. In your terminal, type `python` and press <kbd>enter</kbd>. The terminal should print something like:

```console
~$ python
Python 3.7.7 (default, May  6 2020, 04:59:01) 
[Clang 4.0.1 (tags/RELEASE_401/final)] :: Anaconda, Inc. on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> 
```

Type `exit()` to leave Python.

### Step 5: Ensure Anaconda Is Up-to-Date

Now that Anaconda is installed, you need to ensure that Anaconda is updated to the newest version for this workshop. Go to our Insight section for [Keeping your Anaconda installation up to date](https://github.com/DHRI-Curriculum/insights/blob/v2.0/pages/anaconda.md) to learn more about how to keep your Anaconda installation up-to-date.

## Installation instructions: Microsoft Windows 10

While the installation instructions below is for Windows 10, this installation instruction should work for Windows 8 as well. For older version, please check out the [Anaconda documentation](https://docs.anaconda.com/anaconda/install/#old-os). Should you run into any trouble, you can also find solution to common installation issues [here](https://docs.anaconda.com/anaconda/user-guide/troubleshooting/).

### Step 1: Download Python 3.+:

We **strongly** recommend that you follow the screens below step by step. Paying particular attention to Step 3 in the installation process.

Visit the [Anaconda website](https://www.anaconda.com/products/individual) on your internet browser, such as Firefox or Chrome, and scroll to the bottom of the page. Here, click on the **64-Bit Graphical Installer** under the Windows Python 3.+ menu. Our screenshot below shows python 3.8, but any latest **python 3.+** version will work with our instructions and the institute.

![Screenshot: Anaconda download webpage with 3.8 button highlighted](/images/guides/conda_installer_windows.png)

You can ignore this. Just close this screen and wait for your donwload to finish.

![Screenshot: Anaconda thank you for downloading](/images/guides/anaconda01w.png)

### Step 2: Run Anaconda Installer

After the download has completed, if it doesn't open automatically, double-click on the installer file you just saved on your computer. Click `Continue`:
 
 ![Screenshot: initial installation setup image](/images/guides/anaconda02w.png)

Accept the license by clicking `I Agree`:
 
![Screenshot: installation licence agreement](/images/guides/anaconda03w.png)

Install Anaconda only for yourself by choosing the just for me radio button. Click `Next`:

![Screenshot: radio menu, select the 1st "just me" option](/images/guides/anaconda04w.png)

Choose the location to install anaconda (the default is fine). Click `Next`:

![Screenshot: text box with path for default Anaconda install and browse button ](/images/guides/anaconda05w.png)

### Step 3: Run Anaconda Installer Part 2: BE CAREFUL WITH THIS OPTION!

This step is so that you will be able to run anaconda directly from your terminal. 

On the Advanced Installation Options page, select **BOTH boxes**: "Add Anaconda to my PATH environment variable" and "Register Anaconda as my default Python". Then click `Next`: 

![Screenshot: advanced installation options window. Has two check boxes: Add anaconda to PATH environment variables, and `Register Anaconda as my default Python`](/images/guides/anaconda06w.png)

The installation may take a while, so go grab a snack or check your email: 

When installation is completed, the window will list the location of the Anaconda installer. Click `Next`:

![Screenshot: Full progress bar and printed output listing location of Anaconda files](/images/guides/anaconda07w.png)

Click `Install Microsoft VSCode`. If it is already installed, click `Skip`:

![Screenshot: menu option to also install vscode](/images/guides/anaconda08w.png)

This is the final window. You can uncheck all the boxes and click `Finish`:

![Screenshot: final installation window for anaconda, has two check boxes: learn more and learn how to get started](/images/guides/anaconda09w.png)

### Step 4: Check if Anaconda and Python are successfully installed

Open a Windows terminal. You can open the terminal by pressing <kbd>windows</kbd> + <kbd>R</kbd> to open the `Run` box. Type `cmd` and then click `OK` to open the Command Prompt. Once it is open, type `python` and press <kbd>enter</kbd> on your keyboard. The terminal should print something like:

```console
~$ python
Python 3.7.7 (default, May  6 2020, 04:59:01) 
[Clang 4.0.1 (tags/RELEASE_401/final)] :: Anaconda, Inc. on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> 
```

Type `exit()` to leave Python.

### Step 5: Ensure Anaconda Is Up-to-Date

Now that Anaconda is installed, you need to ensure that Anaconda is updated to the newest version for this workshop. Go to our Insight section for [Keeping your Anaconda installation up to date](https://github.com/DHRI-Curriculum/insights/blob/v2.0/pages/anaconda.md) to learn more about how to keep your Anaconda installation up-to-date.


Installing Python


# QGIS

## What it is

[QGIS](http://www.qgis.org/en/site/) is a program that you download onto your computer, which can be used to perform spatial operations (analyze and manipulate your data), and make composite maps. 

## Why we use it

For the Digital Humanities Research Institute, we use QGIS because it is free and open source, compared to many other tools available for macOS and Windows users.

## Installation instructions: macOS

### Step 1: Download

Download the latest version of QGIS from the [QGIS download page](https://qgis.org/en/site/forusers/download.html)

![List of QGIS download options ](/images/guides/qgis-install.png)

### Step 2: Follow the installation instructions

After opening the install package, you will be taken through a prompt. Follow the instructions.

![Screenshot depicting the QGIS Installer](/images/guides/qgis-download-prompt.png)

### Step 3: Move the application into your Applications folder

After the package installs, move the QGIS application into your applications.

![QGIS move to apps](/images/guides/qgis-into-apps.png)

### Step 4: Open the QGIS Application

Start by navigate to your Applications folder and double-click on QGIS.

You will likely receive an error that says “QGIS can’t be opened because Apple cannot check it for malicious software.” To solve this, go back to your applications and this time instead of double-clicking on the QGIS app, right-click and select “Open.” Then when prompted again, select “Open.”

From this point onward, you will not have to go through allowing the software to run every time. You will simply be able to open the app by double-clicking on it. 
 
Launch QGIS. A new project will look like this:

![QGIS installer](/images/guides/qgis-interface.png)

## Installation instructions: Windows

### Step 1: Download

Download the latest version of QGIS from the [QGIS download page](https://qgis.org/en/site/forusers/download.html)

### Step 2: Install

Follow the instructions provided by the installer you downloaded.  




Installing QGIS


# Microsoft Visual Studio Code

## What it is

Visual Studio Code is a text editor that allows us to write code in a variety of computational languages such as python, HTML, javascript, among others.

## Why we use it

For the Digital Humanities Research Institute, we use Visual Studio Code because it supports [syntax highlighting](https://en.wikipedia.org/wiki/Syntax_highlighting), it is free and built on open source, and it is consistent across Mac, Windows, and Linux systems.

## Installation instructions: macOS Catalina

### Step 1: Download Visual Studio Code Installer

Visit the [Visual Studio Code website](https://code.visualstudio.com/) on your internet browser, such as Firefox or Safari, and click `Download for Mac`. Then click `Save File` in the dialogue box that asks if you would like to save the file

![Screenshot showing the Visual Studio Code website with the link to download for Mac](/images/guides/vscode_mac_1.png)

### Step 2: Run Visual Studio Code Installer

After the download has completed, double click on the file called `VSCode-darwin-stable.zip` in your Downloads folder. 

![Screenshot showing Visual Studio Code installer in the Downloads folder](/images/guides/vscode_mac_2.png)

### Step 3: Move Visual Studio Code to Applications Folder

Drag the Visual Studio Code application (it will have a blue logo next to it) from your Downloads folder to Applications folder.

![Screenshot showing Visual Studio Code application being moved from the Downloads folder to the Applications folder](/images/guides/vscode_mac_3.png)

### Step 4: Start Visual Studio Code application

Double click the Visual Studio Code application in your Applications folder. The first time you open Visual Studio Code, you should receive a dialogue box that asks you if you are sure you would like to open it. Here you should click `Open`. 

![Screenshot showing Visual Studio Code in the Applications folder with a dialogue box asking if the app should be opened](/images/guides/vscode_mac_4.png)

### Step 5: Configure Visual Studio Code I

Navigate to the `View` option in the topmost menu and click `Command Palette`. This will make a text bar appear.

![Screenshot of Visual Studio Code's "View" menu option with the Command Palette highlighted](/images/guides/vscode_mac_5.png)

### Step 6: Configure Visual Studio Code II

Type "shell" into the text bar that appears. Then choose `Shell Command: Install code command in PATH`. Click `OK` on the dialogue box that appears saying "Code will now prompt with 'osascript' for Administrator privileges to install the shell command." You may also be asked to provide the password to your computer at this stage.

![Screenshot showing textbox with "shell" typed in and the "Shell Command: Install 'code' command in PATH" option highlighted](/images/guides/vscode_mac_6.png)

### Step 7: Complete

Congratulations, Visual Studio Code is now installed in your computer!

![Screeshot showing Visual Studio Code running successfully](/images/guides/vscode_mac_7.png)

## Installation instructions: Microsoft Windows 10

### Step 1: Download Visual Studio Code Installer

Visit the [Visual Studio Code website](https://code.visualstudio.com/) on your internet browser, such as Firefox, Edge, or Internet Explorer, and click `Download for Windows`. Then click `Save File` in the dialogue box that asks if you would like to save the file

![Screenshot showing the Visual Studio Code website with the link to download for Windows](/images/guides/vscode1.png) 

### Step 2: Run Visual Code Installer

Double click on the Visual Studio Code installer in your downloads folder

![Screenshot of Visual Studio Code setup icon](/images/guides/vscode2.png)

### Step 3: Walking Through Visual Studio Code Installer I

Click `Next` when the Visual Code setup window opens.

![Screenshot of Visual Studio Code installation options for starting the install](/images/guides/vscode3.png)

### Step 4: Walking Through Visual Studio Code Installer II

Accept the license agreement by selecting the first radio button. Then click `Next`.

![Screenshot of Visual Studio Code license agreement](/images/guides/vscode4.png)

### Step 5: Walking Through Visual Studio Code Installer III

Choose the folder on the computer that Visual Studio Code should be installed in (the default is usually fine). Then click `Next`.

![Screenshot of Visual Studio Code installation process where we select the folder to install in](/images/guides/vscode5.png)

### Step 6: Walking Through Visual Studio Code Installer IV

Choose the folder in the start menu that Visual Studio Code should be installed in. Check the other boxes at your own discretion. Then click `Next`.

![Screenshot of Visual Studio Code installation process where we select start menu folder](/images/guides/vscode6.png)

### Step 7: Walking Through Visual Studio Code Installer V

Please check the box that says `Add to PATH`. Then click `Next`.

![Screenshot of Visual Studio Code installation Add to PATH option](/images/guides/vscode7.png)

### Step 8: Walking Through Visual Studio Code Installer VI

You should see a window listing the configurations you chose in the previous steps. If they are incorrect, click `Back` and redo the previous steps. If they are correct, click `Install`.

![Screenshot of Visual Studio Code installation confirmation](/images/guides/vscode8.png)

### Step 9: Walking Through Visual Studio Code Installer VII

Sit back and relax because the install will take a while. You should see a window with a progress bar similar to this.

![Screenshot of Visual Studio Code installation completion bar](/images/guides/vscode9.png)

### Step 10: Walking Through Visual Studio Code Installer VIII

Check the `Launch Visual Studio Code` checkbox and then click `Next`.

![Screenshot of Visual Studio Code installation final step](/images/guides/vscode10.png)

### Step 11: Complete

Congratulations Visual Studio Code is now installed! You should see something similar to this window when you launch Visual Studio Code.

![Screenshot of Visual Studio Code running successfully](/images/guides/vscode11.png)


Installing VSCode


# Firefox

## What it is

[Firefox](https://www.mozilla.org/en-US/exp/firefox/) is a free to download web browser built by the [Mozilla Foundation](https://foundation.mozilla.org/en/about/), a non profit organization. Firefox allows users to access websites on the internet. 

## Why we use it

For the Digital Humanities Research Institute, we use Firefox because it works on Windows and Mac operating systems, it is frequently updated, and it values user privacy. 

## Installation instructions: macOS

### Step 1: Go to the Firefox download webpage

Visit the [Firefox download page](https://www.mozilla.org/en-US/firefox/new/?utm_medium=referral&utm_source=support.mozilla.org) in your pre-installed browser, such as Safari.

![Image showing the Firefox download page for Mac](images/firefox_mac_01.png)

### Step 2: Download Firefox Installer

Click on the `Download Firefox` button.

![Image showing where to click to download Firefox](images/firefox_mac_02.png)

### Step 3: Move Firefox to the Applications folder

Once the download has finished, the file should open by itself and pop open a Finder window containing the Firefox application. Drag the Firefox icon on top of the Applications folder in order to copy it there. This action will begin the installation, which should only take a few seconds to complete.

![Image showing how to drag Firefox and drop it in Applications folder](images/firefox_mac_03.png)

### Step 4: Eject the Firefox installation file

After dragging the Firefox app to the Applications folder, go back to the desktop screen, move the mouse cursor over the Firefox icon, and click it while holding down the `control` key on your keyboard. Then select the `Eject Firefox` option.

![Image showing how to eject the Firefox installation file](images/firefox_mac_04.png)

### Step 5: Open Firefox 

You can now start Firefox by double-clicking on it in the Applications folder. The first time you open Firefox, you should receive a dialogue box that asks you if you are sure you would like to open Firefox. Here you should click `Open`. 

![Image showing the dialogue box that opens only on the first time starting Firefox](images/firefox_mac_05.png)

### Step 6: Finished!

Firefox will now open. Congratulations, you have completed installing Firefox!

![Image showing a fresh install of Firefox](images/firefox_mac_06.png)

## Installation instructions: Microsoft Windows 10

### Step 1: Go to the Firefox download webpage

Visit the [Firefox download page](https://www.mozilla.org/en-US/firefox/windows/?utm_medium=referral&utm_source=support.mozilla.org) in your pre-installed browser, such Internet Explorer or Edge.

![Image showing the Firefox download page for Windows](images/firefox01.png)

### Step 2: Download Firefox Installer

Click the `Download Now` button. This will prompt a notification bar at the top or bottom of your screen with an option to open, run, or save the Firefox Installer file. 

![Image showing the Firefox Installer download page for Windows](images/firefox02.PNG)

### Step 3: Run Firefox Installer

Click on the `Run` or `Open` option in the notification bar to start the process. 

![Image showing the Open file option for the Firefox Installer in the notification bar](images/firefox03.png)

### Step 4: _User Account Control_ Settings

A _User Account Control_ dialogue may open that asks you to allow the Firefox Installer to make changes to your device. Click `Yes` to start the installation.

![Image showing the User Account Control dialogue](images/firefox04.PNG)

### Step 5: Firefox Installation

Wait for Firefox to finish installing.

![Image showing the Firefox installer running](images/firefox05.PNG)

### Step 6: Completing Firefox Installation

When the installation is complete, Firefox will open. 

Congratulations, you have successfully installed Firefox! 

![Image showing a fresh install of Firefox](images/firefox06.PNG)



<<<<<<< HEAD

=======
>>>>>>> 0c1f92750ca72258cef9b359936ff4e6d9a5ab50
# Short Introduction to Jupyter Notebooks

In some of our workshops we use Jupyter Notebooks. Whether you want to test short code snippets or document your computational output and complement it with text and multimedia resources in a single document, Jupyter Notebooks is a great tool to use. Here are our short introduction to how to use Notebooks.

## What are Notebooks?

Jupyter Notebooks is a form of "computational notebook" (sometimes called "Notebook Interfaces"). They have existed for decades, and were created to let users to combine software code, computational output, explanatory text and multimedia resources in a single document. They became popular among researchers for allowing them to annotate procedure, data and findings, making it easier for them to later reproduce calculations with different data.

Jupyter Notebooks have exploded in popularity in the past years, becoming by far the most used computational notebook.

## How to open a Jupyter notebook

If you have not already installed Anaconda, please do so. Jupyter Notebook comes with Anaconda by default.

Find and open the Anaconda Navigator on your computer (you should be able to find it in the folder with your other applications). From Anaconda Navigator's interface, launch a Jupyter Notebook.

![jupyter](/images/guides/jupyter.png)

Jupyter Notebook will open as a tab in your default browser, which is where you will be working. All of the directories (folders) in your `home` directory will appear. (This may vary depending on what operating system—macOS, Windows, etc.—you are using, as the file structure can be different)

We will now open a new file. It is very important that you make sure to open the file in the right place, so you can find it later. Navigate on the directories clicking on them until you are on the desired directory.

Once you are in the right place, select `New` >> `Python3` in the upper right corner.

![jupyter notebook "open new file" screen](/images/guides/jupyter1.png)

A blank page with an empty box should appear.

![empty box on jupyter notebook new file](/images/guides/jupyter2.png)

## Running a cell

Jupyter Notebook allows you to write and run codes in containers, which we call cells. We won't go deep into how it works since it can get a bit complicated. For the moment, it is enough to know that we can run and see the output of the lines of code that are inside a cell.

To try, type some python code. You can try the classic `print("hello world!")` or anything else you want. To run the cell, press <kbd>shift</kbd> + <kbd>enter</kbd>. That will give you an output, and create a new cell below.

## Choosing, Starting, and Restarting a kernel

Your notebook has a kernel, which is like an engine that executes the code contained in the cells. Again, we won't go too deep on this right now.

What matters is to understand that while you are running codes in a notebook, the kernel will remember all the variables you've created, libraries you've imported, etc. And that will be true even if deleted a cell after you ran it.

This is very powerful, but can be a source of confusion. If you feel you have changed things too much, or that you are getting outputs you should not be getting, or if you experience some kind of crash, you can always restart the kernel, which will "clean" the memory of the kernel, and ask the notebook to run all the cells again. In that way, you will guarantee that the kernel will only have ran what is currently coded on the cells. To do that, on the top menu, click on `kernel` -> `Restart & Run All`. You will see other options there, feel free to explore them.

Jupyter Notebook allows you to run cells in any order you want. Again, that can be very useful, but it can be quite confusing. At least in the beginning, we strongly suggest you to avoid running cells out of order.

## Learning more/Resources

The best way to learn Jupyter Notebook is working with it for a while. Once you get more comfortable, make sure to read tutorials to see advanced possibilities. We suggest some below.

Also, it is a good idea to try to learn the keyboard shortcuts. They can save you a lot of time in the long run. To see the list of shortcuts, in the top menu click on `Help` >> `Keyboard Shortcuts`.

Here are a few that I have found helpful:

-   [28 Jupyter Notebook Tips, Tricks and Shortcuts](https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/)
-   [Corey Schafer's videos](https://www.youtube.com/watch?v=HW29067qVWk)
-   DataQuest's [Jupyter Notebook for Beginners: A Tutorial](https://www.dataquest.io/blog/jupyter-notebook-tutorial)
-   Programming Historian's [longer tutorial](https://programminghistorian.org/en/lessons/jupyter-notebooks)

Short Introduction to Jupyter Notebooks

Mastering the command line will prove useful in a great number of projects. Most Python- and R-based projects will require you to have some knowledge of the command line. At a very basic level, you will be invoking a Python script and will be using values of command line arguments when creating and running your scripts.

Command Line Workshop

Creating Simulations

Data Ethics

Introduction to Git and GitHub

HTML and CSS are fundamental to building websites. Almost all web-based projects use HTML and CSS in some aspect of their web design. I have included three different kinds of projects that use HTML and CSS to to bring to notice a diversity of ways of using the internet and websites in digital humanities projects:

CUNY Graduate Center DRI

Glossary

Shapefile