Assessment - Course and Tools Introduction

Reminder

Each module comes with assessments. Those are things you need to do that will be graded. The table on the Schedule page lists the assessments for each module.

If you haven’t done so, please read through the Assessments Overview page so you know how each type of assessment should be done and how grading works.

Each module has an Assessments page, like this one, which describes what the assessments are and what you should do. Often, there is a good bit of information for the exercises.

Quiz

Get the quiz sheet for this module from the general Assessments page. Fill it in, then submit to the online grading system before the deadline.

For this first module, you have 2 submission attempts. This allows you to get used to the submission system.

Discussion

The discussion for this module is all about getting to know each other. For your original post, complete the Exercise below, then post the URL to the website you createed by doing the exercise below into the introductions Discord channel. Do so by Wednesday 5pm.

For your replies, visit some of your classmates websites and leave feedback as a reply to their initial post. Do so by the Friday deadline.

I hope this will allow you to start getting to know each other, even if only virtually.

Exercise

For this exercise, you are asked to start using Github, R, RStudio, and Quarto to create a website which will become your portfolio for this class. You’ll write and post a short personal introduction of yourself.

Workload Note

For those of you who are new to Github/R/Quarto, this first project will make you do a lot of things that you are not familiar with. I know that this will be time-consuming and also might feel a bit intimidating. It’s partly unavoidable and partly on purpose. You need to learn how to quickly get up to speed with all kinds of new tools that come your way. So practicing it is a good idea. You are welcome to draw on any sources for help that you want (online, classmates, instructor, etc.). I’m confident with a bit of trial and error you’ll get it to work.

If you get stuck (quite possible), check the materials listed in the Resources section of the course, or use Google. Also use the discussion boards to ask questions. You may use any method to get help (Google, R4DS Slack channel, AI, colleagues/friends/relatives with R/Quarto/Markdown experience, etc.). Still, try to do as much as possible yourself. We’ll use all the bits you are learning here repeatedly during this course.

Pre-requisites

You should gone through all content in this module and should be set up with all the tools we need, namely R, RStudio, GitHub and GitKraken (or your preferred Git client).

Github setup

I made a template for you to get started. Go to the Online Portfolio Template. Make sure you are logged into GitHub, then click on Use this template. Create a new repository, call it yourname-MADA-portfolio (yourname should include both your first and last name, e.g. andreashandel-MADA-portfolio.) Choose public repository, then create it.

Next, clone the repository (which will be something like https://github.com/USERNAME/yourname-MADA-portfolio/) from Github.com to your local computer (using Gitkraken or whatever software/method you decided to use). I recommend that you make a folder somewhere on your computer (e.g., called MADA-course) and place all class-related repositories (of which this is the first one) into this folder. Remember that these GitHub repositories/folders should not be synced with some other software (e.g., Dropbox/OneDrive).

Quick local website check

Once your repository is on your local computer, go into the folder and click on online_portfolio.Rproj, which should open RStudio. In the bottom right, you’ll see a number of files and folders that are part of your repository/project. We’ll edit a few of them as described below. The rest you can ignore for now, we’ll come back to them in later exercises.

In the top right panel in RStudio, you should see a Build tab. Click on it. It should show a Render website button, click it. You will probably get complaints about missing packages. If that’s the case, install them. Once everything works and renders without problems, a local preview of your soon-to-be new website should open in your browser.

If for some reason, you can’t see the Build tab in the top-right corner of RStudio, you can alternatively click on the Terminal tab (next to the Console tab). Type quarto render into the terminal and this should build your website (the RStudio button is basically just calling that command.)

If you can’t get this far and can’t figure out what’s going wrong, ask for help on Discord. Once you got that far, let’s create some content.

Quarto content creation

For this part of the task, the comprehensive Quarto guide and the Quarto section of the 2nd edition of R for Data Science will likely be useful.

Open index.qmd. This is the main landing page for your website. Change the text however you want to. What you are writing here is Markdown, so now would be a good time to check out some of the Markdown resources and play with them. You will also see at the top of your R Studio window two buttons Source and Visual. This allows you to switch between editing Markdown in plain format, and using a visual editor. It’s a good idea to switch back and forth to start to learn how certain graphical elements look like in plain text formatting. You’ll likely be using a mix of visual and source view a lot.

Next, open aboutme.qmd and write some text introducing yourself, as follows:

• Talk a bit about yourself, your background, training, research interests. Let me/us know what kind of statistics, programming, data analysis experience you already have. I’d also be curious to know what you most hope to learn in this course. And then tell us some quirky/interesting/curious thing about you.
• Give your text a nice structure with headings, subheadings, etc.
• Include a picture of yourself. To do so, place the picture in the repository and link it from the Quarto file.
• Finally, include a link to a picture/video/website/etc. The linked material should be somehow related to data analysis. Find something that you think is really cool/interesting/weird/etc. Provide a few explanatory sentences.
• If you want, feel free to get creative and include other things. You can play with Quarto if you wish to, e.g., you can try to include a table or a video or any other elments you want to explore.

If you make changes and want to see how they look, save your changes and rebuild the website. Load/refresh in your browser and it should show any changes.

This portfolio website and everything you put on there is public. So don’t put anything on there that you don’t want to be publicly known.

Website control

For Quarto, a lot of the look/feel and structure of a website is controlled in what’s called a YAML file (it has the ending .yml). The main one is called _quarto.yml. Open it. You’ll see that it contains a bunch of information about the website, including the title, the menu structure, and some styling information.

Make the following changes:

• Update the title of your website.

• Replace the URL-TO-THIS-REPOSITORY-HERE placeholder text with the Github URL of the repository you created (e.g. for me, that would be something like https://github.com/andreashandel/andreashandel-MADA-portfolio).

• It is possible to change the look of your website. Full styling requires knowledge of CSS and HTML. We won’t get into this. But we’ll explore a quick way to change the look. Replace theme with a different one. Many themes are available. Try some, see how things change. You can also change the highlight scheme. For further styling, you can put custom CSS code into the styles.css file. We won’t do this here, but feel free to explore on your own.

YAML (which is the format of _quarto.yml) is VERY finicky when it comes to formatting. You need to have exactly the right number of empty spaces. If you ever change a YAML file and you get a weird error message when trying to rebuild your website, it’s likely because some minor formatting is wrong, e.g. an empty space is missing or too much. Just keep that in mind. (It happens to me all the time.)

Sending updates to Github

Once you are happy with your updates, or if you want to take a break, make sure to push your updates to GitHub. First close RStudio. Then go to the program you use for Github (I will assume that it’s GitKraken. If you use something else the details might vary). In the top right of Gitkraken, there should be a notification about changed files. Click view changes, then Stage all changes. Write a commit message, commit the changes. You should see the main with the computer symbol moved above the one with some random logo. That means your local repository is ahead of the one on github.com. To get them in sync, you click the push button. If things work, the two symbols should now be in the same line.

Sometimes, there might be issues that prevent pushing/pulling, e.g., if someone else changed the same files you did. If you are sure your local version is the correct one, you can perform a force push. A force push will overwrite the remote repo with the local repo forcibly. This means that the remote will be updated with any changes that exist on your local computer. If any changes have been made to the code since you began editing (i.e. someone else has made a commit to the repo while you were working on it) they will be destroyed by the force push since they are not on your local repo. For this assignment, you are the only person working on your introduction so it is unlikely you will encounter any issues with force push, but it is good to be aware of the function of the action. Use with care. It’s generally better to resolve merge conflicts.

Making the website public

We want to set things such that your repository can at the same time become a public website. Github allows you to do that with its Github Pages feature. To turn on the Github Pages feature, go to your repository on github.com (e.g. something like https://github.com/andreashandel/andreashandel-MADA-portfolio). On the top of the website for your repository, you should see a Settings button. Click on it and then find the Pages section. In the Branch section, switch none to main and folder as /docs. Click Save.

This should now have turned on your website. You might have gotten a notice about the location of your new website. If yes, follow the link. If not, you can get there by going to a URL that has the form https://username.github.io/yourname-MADA-portfolio/ (e.g. for me, that is https://andreashandel.github.io/andreashandel-MADA-portfolio/). It might take a few seconds before the page is available, if you get a ‘not found’ error, wait a bit and try again. If everything works, your website is now public!

Github pages

We used the Github pages feature to create the website. You might have noticed that the files for your new website live on the domain github.com, while your nice-looking website lives at the domain github.io. This is how Github Pages work. It take files from your repository and turns them into a website with a distinct URL. Those files can either be in the main repository folder or in a /docs subfolder (our setup). Your website URL and your repository URL are distinct. All github actions, like pushing, pulling, cloning, etc. are done with the repository on the github.com domain. The github.io domain is only there to display websites.

As an example, this course website is displayed at https://andreashandel.github.io/MADAcourse/ and all the files that make up the webpage are at (https://github.com/andreashandel/MADAcourse). Note the text at the bottom of the repository view. That text comes from the Readme.md file. Speaking of which…

Update your repository Readme file

Re-open your project with RStudio. Click to open the README.md file. It only contains a single sentence I placed there. This file will not be part of your website, but it is what people see if they land at your github repository (i.e. the behind-the-scenes location). Add text to it that points users to the URL for your new website. (You’ve done the reverse above, allowing users to quickly go from your website to your Github repository).

Make any other edits you like.

Once done with edits, remember to re-build/re-render your website with Quarto (by clicking ‘Render Website’ in the Build tab) and then committing/pushing your local changes to GitHub (using Gitkraken or another Git client).

Once your website is up and running, don’t forget to post the link into the introductions channel!

General Github workflow

In the future, if you work on repositories like this one (or any others), your workflow should be as follows:

• Open GitKraken or your preferred Git client and make sure the local copy of your repository is up-to-date (this is important if you collaborate with someone or you are working on multiple computers). If the remote is ahead of the local, do a pull.
• Once your local repo is up-to-date, open your project in RStudio by double-clicking the name of the project (ends in .Rproj). Make all the edits you like. Make sure to render your quarto files (or knit your Rmd files). Once you are done with edits, close Rstudio, go to Gitkraken, stage/commit/push your changes back to the remote server.

You will be using this workflow a lot.

Further information

I wrote a tutorial a while back describing the setup with Github pages. It has some additional information, which you can check out on my website. Note that this tutorial still used R Markdown instead of Quarto. Some of the information still applies, other parts are different with Quarto.

Using Github pages makes it fairly easy to create websites. I currently host all my course websites in this way. What we created was a fairly basic page. It is easy with Quarto to create other, more full-featured websites. For instance my personal website uses Quarto. If you are interested in such a more full-featured approach, check out this part of the Quarto documentation. You can also find a few more links to other resources.