BAA1030 - Data Analytics and Story Telling

.title[
# BAA1030 - Data Analytics and Story Telling
]
.subtitle[
## Lecture 10: Publish your Quarto with GitHub
]
.author[
### Damien Dupré - Dublin City University
]

---

# Objectives

The last tool for data analytics and visualisations displayed in this lecture is called **GitHub**.

GitHub has a lot of different functions. For now, we will only see how to use it to **publish the html document output from Quarto**.

.center[
![](http://www.quickmeme.com/img/75/7509f68823389e4af3777ca6d3744c632cc32ab3547bc56e319126aa29ab149a.jpg)
]

---

# What is GitHub

Primarily used to collaborate on code development, it became multi-purpose:

- Version Control
- File and Code Storage
- Collaboration
- Developers Social Media
- Online Publication & Website Host
- Automatic Actions

And even more that I am not aware of!

---

# What is GitHub

Primarily used to collaborate on code development, it became multi-purpose:

- Version Control
- **File and Code Storage**
- Collaboration
- Developers Social Media
- **Online Publication & Website Host**
- Automatic Actions

And even more that I am not aware of!

---
class: title-slide, middle

## 🛠️ Your Turn!

1/ Go to https://github.com and click **sign up** (or **log in** if you already have an account)

2/ Fill the information requested, find a **good user name** as it will be used for your default website (e.g., `firstname-name` is usually good)

3/ Later, add a profile picture

---

# Welcome to GitHub

![](https://miro.medium.com/v2/resize:fit:1400/1*cgJlPulU9t3djbf9TQ5sGA.gif)

---
class: inverse, mline, center, middle

# GitHub Repository

---

# How does GitHub Work?

The core principle of GitHub is a remote desktop (or profile) with a folder called **Repository** for each project you are working on or you worked on (also called "Repo" if you want to use the slang).

![](https://raw.githubusercontent.com/damien-dupre/img/main/github_dd_profile.png)

---
class: title-slide, middle

## Demo

---
class: title-slide, middle

## 🛠️ Your Turn!

Follow the steps hereafter to **create your first repository**.

---

# GitHub Repositories

[To create a Repository](https://docs.github.com/en/get-started/quickstart/create-a-repo):

1/ In the upper-right corner of any page, use the `+` drop-down menu, and select New repository.

![](https://docs.github.com/assets/cb-11427/mw-1000/images/help/repository/repo-create.webp)

---

# GitHub Repositories

![](https://git-scm.com/book/en/v2/images/newrepoform.png)

---

# GitHub Repositories

2/ **Type a short, memorable name** for your repository. For example, "hello-world".

![](https://docs.github.com/assets/cb-25139/mw-1000/images/help/repository/create-repository-name.webp)

<span><i class="fas  fa-exclamation-triangle faa-flash animated faa-slow " style=" color:red;"></i></span> Warning: Do NOT use white space between words, snake case convention highly recommended.

3/ **Optionally**, add a description of your repository. For example, "My first repository on GitHub."

---

# GitHub Repositories

4/ **Choose a PUBLIC repository visibility**. For more information, see "About repositories."

5/ Tick **Add a README file**.

6/ Click **Create repository**.

### Congratulations! You've successfully created your first repository, and initialized it with a README file.

.center[
<img src="https://external-preview.redd.it/H3X9ghkU1diDoEaB2j6OLakfRVvtelkI-VVCAMvpHFw.jpg?auto=webp&s=812777b2de31ed351475ecfb9cfe91a74931201b" width="50%" />
]

---
class: inverse, mline, center, middle

# GitHub Commit

---

# Always Commit Changes

In GitHub, a commit is a saved change to a project's source code or other files. When you make changes to a file in a GitHub repository, you create a new version of that file.

**A commit contains a snapshot of the changes** you've made to one or more files, along with a message that describes the changes. This **message should be descriptive and clear**, so that other developers can understand what changes you've made and why.

### Every time you want to take into account a change in your repository, you need to commit these changes

---
class: title-slide, middle

## Demo

---
class: title-slide, middle

## 🛠️ Your Turn!

When you created your new repository, you initialized it with a README file. README files are a great place to describe your project in more detail, or add some documentation such as how to install or use your project. The contents of your README file are automatically shown on the front page of your repository.

**Follow the steps hereafter to commit a change to the README file.**

---

# Commit the First Change

1/ In your repository's list of files, **click README.md**.

---

# Commit the First Change

2/ In the upper right corner of the file view, **click the pen icon to open the file editor**.

3/ In the text box, **type some information about the project**.

4/ Above the new content, click **Preview**.

---

# Commit the First Change

6/ Click **Commit changes...**

7/ In the "Commit message" field, type a short, meaningful **commit message** that describes the change you made to the file. 
]

.pull-right[
![](https://docs.github.com/assets/cb-33561/mw-1000/images/help/repository/create-commit-review.webp)
]

8/ Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. Select **commit directly to the `main` branch** for now.

<span><i class="fas  fa-exclamation-triangle faa-flash animated faa-slow " style=" color:red;"></i></span> Warning: For collaborative projects never commit to the main branch

9/ Click **Propose file change**.

---
class: title-slide, middle

## Demo

---
class: title-slide, middle

## 🛠️ Your Turn!

**Fill your Repository with the `report.html` file** created when you used Quarto to render the `report.ipynb` file to html by following the steps described hereafter:

1/ In your Repository Page in GitHub, Click **Add files** then **Upload files**

2/ **Drop your `report.html` file** in the main box

3/ Write a descriptive commit message (e.g., "Add Quarto report") and **commit your changes**

4/ Go back to your repository page and verify that the file appears in the list

---
class: inverse, mline, center, middle

# GitHub Pages

---

# GitHub Pages

GitHub Pages is a **web hosting service** offered by GitHub that allows you to host static websites directly from a GitHub repository. This means you can use GitHub to store and version control your website's code, and then host it for free using GitHub Pages.

GitHub Pages supports several **different types of websites, including personal or project pages**, documentation, blogs, and more. You can use custom domains or subdomains for your website, and GitHub Pages also supports HTTPS encryption for secure communication.

To create a GitHub Pages website, you need to have a GitHub account and a **repository containing your website's HTML, CSS, and other files**. Once you've created your repository and pushed your website's files to it, you can **enable GitHub Pages in the repository settings**. Your website will then be published at a URL based on your GitHub username and repository name (e.g., username.github.io/repository).

---

# GitHub Pages

![](https://miro.medium.com/v2/resize:fit:1400/format:webp/1*uHia-SKJPkWqbxbGJPfCCA.jpeg)

---
class: title-slide, middle

## Demo

---
class: title-slide, middle

## 🛠️ Your Turn!

Turn on GitHub Pages for your project repository:

1/ Go to **Settings** and find **Pages** on the left pane

2/ In **Branch**, instead of None select **Main** and click **Save**

3/ Click on **Actions** and wait for "pages build and deployment" to finish. When it's done, go to **https://username.github.io/repository/report**

---

# GitHub Pages URL

By default, your html report will be published at:

**https://username.github.io/repository/report**

If:

- Your GitHub username is **damien-dupre**
- Your Repository name is **data-analytics**
- Your Project folder name is **project**
- Your html file name is **report.html**

Then, your report will be published at:

**https://damien-dupre.github.io/data-analytics/project/report**

---

# GitHub Pages URL

<span><i class="fas  fa-exclamation-triangle faa-flash animated faa-slow " style=" color:red;"></i></span> Warning: Do NOT use white spaces between words, snake case convention is highly recommended.

If you use a white space in any of the Repository name, Project folder name, or html file name then this white space will be replaced by the symbol **%20**

For example, a Repository name called **data analytics** will have the following URL:

**https://damien-dupre.github.io/data%20analytics/project/report**

---

# GitHub Pages URL

There are two special cases to consider with URLs:

1/ If your html file name is **index.html**, then your file URL will be:

**https://damien-dupre.github.io/data-analytics/project**

2/ If your Repository name is **username.github.io** (e.g., damien-dupre.github.io), then your file URL will be:

**https://damien-dupre.github.io/project/report**

---

# GitHub Pages URL

Both shortcuts can be used to display a document at:

**https://username.github.io**

If:

- Your GitHub username is **damien-dupre**
- Your Repository name is **damien-dupre.github.io**
- Your html file name is **index.html**

Then your report will be published at the URL:

**https://damien-dupre.github.io**

---
class: inverse, mline, center, middle

# Assignment 2 Brief

---

# Assignment Instructions

### Context

You are Data Analyst for the UNICEF organisation, and you have been asked to design a report to raise awareness of the public on a specific world issue.

### Task

Using the files that you already have received by email (i.e., one or both **unicef_indicator_1.csv** and **unicef_indicator_2.csv** files as well as **unicef_metadata.csv** file), **create an html report that contains a story** (i.e., narrative) **and some visualisations** to support this story.

This html report must be **rendered by Quarto** and **published with GitHub Pages**.

### Story

You can copy-paste the exact same text included in your Tableau Dashboard assignment. You can also modify it or write a new one if you prefer. This story has to __use text emphasis styles__ (e.g., title levels, italic/bold font, list and bullet points, ...).

---

# Assignment Instructions

They will have to be created with plotnine. You need to __include 4 visualisations__:

- A World Map chart,
- A bar chart,
- A scatterplot with a regression line,
- A time-series chart.
]

The report must contain a YAML text cell with, **at least**, the following code:

```yaml
---
format:
  html:
    embed-resources: true
    code-fold: true
---
```
]

More specifications of the YAML, the addition of a HTML theme, full customisation of the visualisations and the use of hashpipe options in the code cells will be positively assessed.

---

# Assignment Instructions

## Submission

Submit the **URL of your html report** published with GitHub Pages AND the link to your `report.ipynb` file from your Google Drive on the **BAA1030 Loop page** by **April 7th, 1pm**.

## Assessment Criteria

- Overall Code (25%)
- Data Transformations (25%)
- Visualisation Design (25%)
- HTML Output (25%)

See criteria quality grid for a description of expected submissions.

---

# Vibe Coding and GitHub

---

# Vibe Coding Your Assignment

Vibe coding is the practice of **describing what you want in natural language** and letting an AI assistant (such as ChatGPT, Claude, or GitHub Copilot) generate the code for you.

For the assignment, vibe coding can help you with:

- Writing the **plotnine visualisations** (world map, bar chart, scatterplot, time-series)
- Setting up the **Quarto YAML** with the correct options
- Writing **Polars data transformations** (filtering, grouping, joining)
- Formatting the **markdown text** for your story

<span><i class="fas  fa-exclamation-triangle faa-flash animated faa-slow " style=" color:red;"></i></span> Vibe coding does **not** mean blindly trusting AI output. Always **read and understand** the code before running it!

---

# Vibe Coding in Practice

**Step 1:** Write a prompt describing a specific visualisation you need

> "Using plotnine and Polars, from a dataframe called unicef_indicator_1 joined with unicef_metadata, create a world map showing the indicator value for the most recent year available. Use a yellow-to-red colour gradient and add a descriptive title."

**Step 2:** The AI generates Polars + plotnine code

**Step 3:** Read the code, verify that column names match your actual data, and run it

**Important for the assignment:**

- Always tell the AI the **exact column names** from your CSV files
- Specify **"using Polars and plotnine"** (not pandas or matplotlib)
- Ask for **Quarto hashpipe options** if you want to customise the output
- Test each code cell individually before rendering with Quarto

---

# Tips for Vibe Coding the Assignment

> "Using Polars, read unicef_indicator_1.csv and unicef_metadata.csv, join them on country, and create a bar chart of the top 10 countries by indicator value using plotnine."

> "Write a Quarto YAML with the flatly theme, code folding, embedded resources, title 'UNICEF Report', and my name as author."

> "Using plotnine, create a time-series line chart of the indicator value over the years, coloured by continent."
]

- Not checking that column names match your actual data files
- Forgetting to specify Polars (AI defaults to pandas)
- Not running all cells before calling `quarto render`
- Using white spaces in file names (breaks GitHub Pages URLs)

**Always verify:**

- Does the code run without errors in Google Colab?
- Does the Quarto YAML have correct indentation?
- Is `embed-resources: true` included in the YAML?
]

---
class: title-slide, middle

## 🛠️ Your Turn!

Use an AI assistant (ChatGPT, Claude, or Copilot) to help you get started on the assignment. **Review all generated code before running it!**

1/ Ask the AI: *"Using Polars, write Python code to read a CSV file called unicef_indicator_1.csv and display its first 5 rows."*

2/ Ask the AI: *"Using plotnine and Polars, create a bar chart showing the average value of the obs_value column by continent."* (adjust column names to match your actual data)

3/ Paste the generated code into your `report.ipynb`, run the cells, and verify the output. Did you need to adjust any column names?

---

# Thanks for your attention and don't hesitate to ask if you have any question!

[<svg aria-hidden="true" role="img" viewBox="0 0 496 512" style="height:1em;width:0.97em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg> @damien-dupre](http://github.com/damien-dupre)  
[<svg aria-hidden="true" role="img" viewBox="0 0 640 512" style="height:1em;width:1.25em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M579.8 267.7c56.5-56.5 56.5-148 0-204.5c-50-50-128.8-56.5-186.3-15.4l-1.6 1.1c-14.4 10.3-17.7 30.3-7.4 44.6s30.3 17.7 44.6 7.4l1.6-1.1c32.1-22.9 76-19.3 103.8 8.6c31.5 31.5 31.5 82.5 0 114L422.3 334.8c-31.5 31.5-82.5 31.5-114 0c-27.9-27.9-31.5-71.8-8.6-103.8l1.1-1.6c10.3-14.4 6.9-34.4-7.4-44.6s-34.4-6.9-44.6 7.4l-1.1 1.6C206.5 251.2 213 330 263 380c56.5 56.5 148 56.5 204.5 0L579.8 267.7zM60.2 244.3c-56.5 56.5-56.5 148 0 204.5c50 50 128.8 56.5 186.3 15.4l1.6-1.1c14.4-10.3 17.7-30.3 7.4-44.6s-30.3-17.7-44.6-7.4l-1.6 1.1c-32.1 22.9-76 19.3-103.8-8.6C74 372 74 321 105.5 289.5L217.7 177.2c31.5-31.5 82.5-31.5 114 0c27.9 27.9 31.5 71.8 8.6 103.9l-1.1 1.6c-10.3 14.4-6.9 34.4 7.4 44.6s34.4 6.9 44.6-7.4l1.1-1.6C433.5 260.8 427 182 377 132c-56.5-56.5-148-56.5-204.5 0L60.2 244.3z"/></svg> https://damien-dupre.github.io](https://damien-dupre.github.io)  
[<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M16.1 260.2c-22.6 12.9-20.5 47.3 3.6 57.3L160 376V479.3c0 18.1 14.6 32.7 32.7 32.7c9.7 0 18.9-4.3 25.1-11.8l62-74.3 123.9 51.6c18.9 7.9 40.8-4.5 43.9-24.7l64-416c1.9-12.1-3.4-24.3-13.5-31.2s-23.3-7.5-34-1.4l-448 256zm52.1 25.5L409.7 90.6 190.1 336l1.2 1L68.2 285.7zM403.3 425.4L236.7 355.9 450.8 116.6 403.3 425.4z"/></svg> damien.dupre@dcu.ie](mailto:damien.dupre@dcu.ie)