github | Thought splinters

Using GitHub as a Mentoring Tool

Sun, 01 Aug 2021 00:00:00 +0000

Beginner, Intermediate, and Expert Level

For several years I am interested to learn R, the free software environment for statistical computing and graphics. After

reading several books,
finished some (paid) introductory (MOOC) courses successfully with Coursera
and especially some smaller (paid) projects

I would say that I am now (stuck?) on an intermediate skill level. I believe that this is the most challenging step in progressing to an expert for a self-determined learner. There are always so many different avenues to follow up. This is especially true with R and its

ever increasing amount of new R packages (To date: 20010 (MRAN) resp. 17954 (CRAN), 3452 (Bioconductor).
hundreds of books (see: the searchable list on r-project.org, a curated list on GitHub by Roman Tselgelskyi, but also my Wakelet on free R Books
an unknown number of (free) online tutorials (see the general list and university listed free R tutorials by Pairach Piboonrungroj and my Wakelet on learn R programming)

Comparing my skill level with the three learner paths suggested by RStudio Education, I could affirm my personal assessment. From the six tasks proposals on the intermediate path

grab some R cheat sheets
learn to get help (see, for instance, my activities on StackOverflow)
improve your visualizations
develop interactive applications with htmlwidgets and Shiny
simplify your model explorations with tidymodels
explore other specialized packages

I have some skills with the first three, and I also experimented already with Shiny. I even had worked on some steps at the expert levels by writing an R package: (bib2academic got 16 stars, but I did not manage to submit it to CRAN. It is now obsolete as a similar function was integrated into the Academic Hugo website (now Wowchemy website builder).

Project for Motivation Necessary

But to continue this path, I would need some strong motivation. I tried, for instance, to read the (not yet finished) book Mastering Shiny. As with all books and papers by Hadley Wickham, it is well written and exciting. But to learn continuously, I would need a practical project where I get not only real-world challenges but also a strong personal motivation to complete the product. In finishing the project/product, I would have to learn to overcome several real-world challenges where I would need to look for help and consult/experiment with several new functions or packages.

But this strategy has two advantages:

It is very laborious as the specific questions are not (yet) clear enough. Fora like StackOverflow are not suitable as the problem space is not delimited, a concrete coding question with a REPREX (REPRoducible EXamples) is not available.
It is error-prone and not efficient. Am I posing the right question? Do I look at the right places? It is not guaranteed that one finds the optimal solution. This is particularly awkward if the answer in the R community is very well known.

Looking for a Human Mentor

I believe with a mentor, one could overcome these insecurities fast. The mentor — an experienced user — could ask questions to narrow the search space and point out helpful hints about what and where to look. Wikipedia, for instance, has established a similar program for their user community called Adopt-a-user.

The Adopt-a-user program is designed to help new and inexperienced users by pairing them with more experienced Wikipedians. These editors (referred to as adopters or mentors) will “adopt” newer users, guiding them along the way as they learn about Wikipedia and its various aspects. (Wikipedia)

In Wikipedia, the intention is to help novice contributors get orientation and some guided practice with the very complex rule set for writing or changing Wikipedia entries. My thought is to find a mentor to advance at the intermediate level. I think there is plenty of material for the R beginners freely available. But more important: You will learn R from scratch as an individual and do not need to worry at the beginning stage about an already developed complex rule which you have to observe and follow.

As far as I know, there is no mentor program for R users. The next best alternative is a more open and friendly community. An excellent example, in my opinion, would be the RStudio Community. But even there, you should have a concrete question to ask.

GitHub as a Mentoring Tool

An instructive example

I recently found out that GitHub could be used as an educational tool. I will you give an example which was very exciting for me:

Often I was confronted with the problem of how to calculate and format nicely a contingency table in R. The free web material on the web on this question is abound (e.g., Datacamp, Data Science Central, R-Bloggers, TechVidvan, Statology, …). But many examples still teach the Base R commands. They do not mention new procedures with the tidydata approach and related packages like tidyr. And they do not worry about outputting the table in a publishing-ready format.

There are many contingency tables published in the recently finished books Introduction to Modern Statistics.

Table 1: Descriptive statistics for the stent study.
	30 days	365 days
Group	Stroke	No event	Stroke	No event
Control	13	214	28	199
Treatment	33	191	45	179
Total	46	405	73	378

I could look up the source code from lines 85-101 via GitHub and learn how to produce the above table. (In the following code chunk, I have focussed on the table appearance and left out different previous data transformations to prepare the two data sets stent30 and stent365. Furthermore, the code differs somewhat from the original due to some CSS styles of this website.).

```{r stent-study}
suppressMessages(library(janitor))
suppressMessages(library(kableExtra))
suppressMessages(library(openintro))
suppressMessages(library(tidyverse))

stent %>%
  mutate(group = str_to_title(group)) %>%
  pivot_longer(cols = c(`30 days`, `365 days`), 
               names_to = "stage", 
               values_to = "outcome") %>%
  count(group, stage, outcome) %>%
  pivot_wider(names_from = c(stage, outcome), values_from = n) %>%
  adorn_totals(where = "row") %>%
  kbl(linesep = "", booktabs = TRUE, caption = "Descriptive statistics for the stent study.",
      col.names = c("Group", "Stroke", "No event", "Stroke", "No event"),
      table.attr = "style='width: 75%;'") %>%
  add_header_above(c(" " = 1, "30 days" = 2, "365 days" = 2), extra_css = "border-bottom: 2px solid") %>%
  row_spec(1, extra_css = "border-top: 2px solid") %>%
  row_spec(3, extra_css = "border-top: 2px solid") %>%
  kable_styling(bootstrap_options = c("striped", "condensed"), 
                latex_options = c("striped", "hold_position"),
                full_width = T, position = 'center')
```

Lesson learned

Looking into the source code at GitHub, I learned several issues:

I experimented already with the janitor package, and I am happy to get the confirmation that it is a widely used package to “provide quick counts of variable combinations (i.e., frequency tables and crosstabs)” and to “format [nicely] the tabulation results.” (From the Janitor package description.)
I also did know about the kableExtra package and had the kable_styling function already used several times.
The other kableExtra functions (add_header_above(), row_spec(), kbl()) I had not used before. Especially add_header_above() has an important role for special headings in contingency tables.
The parameter extra_css was entirely new for me. I have never heard about it and didn’t even know that it exists.

For me, this learning experience was very instructive! I admit that this example could have been asked via a friendly forum: For instance: “How could I produce a contingency table formatted professionally for print by using the tidyverse approach?” Additionally, one would have to provide some code to show where one stands and what approach one is using.

Looking Experts over their Shoulders

But this was just one example where I knew about the problem and had already tried several approaches to find a solution. But what about code patterns I didn’t even know and could therefore not ask the right question?

Finding a GitHub project with code snippets one needs urgently is just the beginning. There is a big chance that the same repository (aka ‘repo’) hides more code snippets to learn from. And maybe the person behind this one GitHub repos maintains other repositories that are also very interesting?

In my case, it turned out that Mine Çetakaya-Rundel, one of the authors and the person responsible for the repository management, has educational approaches that are similar to mine. But she is way off more skilled in R and statistics. I am especially interested in her usage of the learnr package for interactive tutorials and have watched a series of three videos on Teaching Statistics and Data Science Online.

In a certain sense, she functions as a mentor for me — even if she doesn’t know about it 🥸. Meanwhile, we had some exchanges on GitHub issues as I am interested in learning how to use the learnr package for introductions into statistics via R-Tutorials. Regularly if I find a problem as a user reading and following the tutorial exercises, I try to fix the code in my fork and send the solutions as pull requests (PR) to Mine. Besides learning to use GitHub in a collaborative setting, I have already profited in many ways. I learned about packages I have never heard of (see, for example, the list of packages used for the book) and saw code snippets that transformed data in a much more elegant way as I used to do.

Summary

To inspect code on GitHub is a suitable strategy for intermediate (programming) learners. I illustrated it with an R example, but I think you could generalize it as a learning strategy. I recommend the following steps:

Note names and/or repositories you learned from successful internet recherche. By searching answers or asking questions via StackOverflow, you will encounter the same names, blog addresses, Twitter messages, repos again and again.
Look around if these person/websites generally work on problems you are interested in. Look into the profile and follow the activities of these persons on their blog, Twitter, YouTube, GitHub … accounts.
Decide on a person and select a specific project. I recommend focusing not only on a particular person but also on picking one project to concentrate on. Ideally, it is a current project the person is still interested in and produces code you want to learn and use for your own work later on.
Think about a possibility to get involved in the project. The idea is to give the person and the community something back for its/their mentoring function and commit yourself to relevant real-world problems. The possibilities depend on your skills and interests. It may be advertising the project, writing a favorable review, fixing typos, commenting via the issue part of the repo, recommending code changes via PRs, or financially supporting the author(s) and/or the ongoing project.

Finally, I would like to add also a warning: “Following” a person should not develop to stalking. It is essential not to be intrusive or pushy. You will see already after a short time if the person values your contribution(s), e.g., by answering friendly or thoughtfully, accepting your PRs, etc. If you get the impression that your engagement is disruptive, then stop it immediately. Either look at the code silently without interaction or try to find another “mentor” or project to get involved.

Blogdown tutorial (Part 4)

Sat, 09 Sep 2017 00:00:00 +0000

Bring your website online: From blogdown via GitHub to Netlify

Update 2021-05-19: Because of breaking changes in Hugo and new features in blogdown this post is partly outdated. Starting with blogdown version 1.0 you do not build the website always from scratch.

Complement this sequence of the tutorial with reading Up & running with blogdown in 2021 by Allison Hill, co-author of the blogdown book.

We start this last part of the tutorial where we have finished last time.

Ignore public folder

One benefit of using Netlify is that that there is no need to upload your large public folder to get your website. Netlify will compile the source files and build by its own the Hugo site. You should take advantage of this feature by telling RStudio that the public-folder does not need version control, committed and uploaded. Select the public folder under the Git tab on the right upper pane and select from the configuration menu ignore….

Ignore public folder

Confirm .gitignore

This will bring up a window where you can specify which files are to be ignored. Confirm the inclusion of the public folder with clicking ‘Save’.

Confirm the exclusion of the public folder.

This saved file (.gitignore) will be added as modified to the version control.

.gitignore file added

Clean up

Before we are going to rebuild the complete site, I recommend to take some precaution. To rebuild from a clean slate I restart R (Under the RStudio menu ‘Session’ or CMD-Shift-F10 on MacOS.) and clean up all unnecessary files (‘Clean All’ in the ‘Build’ tab under the ‘More’ menu in the upper right pane.)

Rebuild website from a clean status.

Build website

Now you can safely (re-)build the website by clicking into ‘Build Website’. You get a message of all the activities done, the time necessary for the build and were the output was created. [Personal comment: Frankly I do not know if the last two steps are really necessary when Netlify is running its own scripts.]

Rendering website content.

Commit changes

The next step is to select all changed files under the Git tab and to choose “Commit”, write a commit message and to confirm these changes.

Select (stage) content for next commit.

Bring all changes under version control and check if everything went smoothly.

Push changes

Now you can transfer all your committed changes to GitHub. After clicking on the push button a window opens and you can see if the changed files are transferred successfully.

Push the committed files to GitHub.

Inspect repo

If you don’t trust this process, you can direct your browser to your GitHub repository and check if really the last commit “First post” has safely arrived.

Inspect your repo on GitHub to confirm the procedure.

Get Netlify account

The last task we are going to solve is the connection the GitHub repository to the Netlifly service. Go to https://www.netlify.com/ and create a free new account (“Get started for free”).

Inspect your repo on GitHub to confirm the procedure.

Let Netlify access your repo

After the registration procedure you get a page where you can choose ‘New Site from Git’.

New Site from Git

There are essential three step to create the new website: (A) Choose GitHub as your Git repository. This will bring up a window where you have to confirm that you will allow Netlify access to your GitHub account.

Autorize Netlify

(B) Then you have to specify to which repository Netlify should connect.

Choose your website repository.

Deploy settings

In the third and last step (C in my former notation) on Netlify to create your website you have to specify the details (parameters) to let Netlify know which type of website it has to build. In the example in the screenshot I said that Netlify should watch my master branch, build a Hugo website from the public repository with the newest version of Hugo at the time of writing this tutorial (version 0.26).

Specify the deploy settings.

Deploy website

After clicking “Deploy website” you can lean back and watch Netlify busy working on building the website. This may take for this initial step some time but later on Netlify will finish work almost immediately as it only builds the new/changed files incrementally. When the rolling down of the messages stops you should see as last line: “Site is live”!

Wait — and watch Netlify working until it is finished.

Preview deploy

Scroll back to the beginning of the log messages. You will see that Netlify has giving you a random URL but you can change this later on to your liking. Click “Preview deploy” to go to the URL of your new website.

Inspect your random URL.

Website is online!

Congratulations! Your website is now online.

Your website is online.

Final comments

This was a very quick tour where I have covered just the things I believed to be essential. If you are (like me) new to static website generators then the different steps together seem overwhelmingly complex. But with patience and some trial and errors you should succeed — as I have. There are many other (better) tutorials and How-Tos around. You should definitely read carefully the book blogdown: Creating websites with R Markdown and the reports of different experiences from the new rbind community.

Blogdown tutorial (Part 2)

Tue, 05 Sep 2017 00:00:00 +0000

Creating a Github repository

Update 2021-05-19: Even if some screenshots might have changed slightly, this part of the tutorial is still up to date. But there are now many other resources with the same content available.

Especially I would like to recommend Up & running with blogdown in 2021 by Allison Hill, co-author of the blogdown book. There is a small part at the end to the integration into GitHub.

R User now can use the helpful package usethis with information how to get Git(Hub) Credentials and with Happy Git and GitHub for the useR there is also a gentle introduction to Git & GitHub.

In part 1 we have installed the hugo-academic theme on top of R, RStudio and blogdown. We will continue the installation process with creating a remote GitHub repository.

Create a GitHub repo

In case you do not have a GitHub account, sign up for it. When you have finished the registration process click the button “Start a project”. If you already have an account click at “New repository”.

Creating a new GitHub repository.

Name your GitHub repo

Both actions (“Start a project” and “New repository”) opens up a window where you can name your new repository. Leave all the other options empty resp. as they are and click the green button “Create repository”.

Name your new GitHub repository.

Quick Setup

The last click brings you to a “Quick setup” page with several options. As there already exist a repository with our hugo-academic files, we copy the two lines in the third option: “push an existing repository from the command line”.

Quick setup: push an exiting repository from the command line.

Shell commands: git init

But before we can paste these two lines into the terminal in order to link our local with the remote GitHub repository we need to download Git and install it. The best description I know of the installation procedure and its integration with RStudio is by Hadley Wickham in chapter 13 of his book about R Packages. There is a online version available. Read the two sections Initial set up and Create a local Git repository. For the mentioned shell commands you can use the Terminal tab of RStudio in the left lower pane.

Use for the shell command the new terminal tab of RStudio.

Git tab in RStudio

5After the shell command git init the local repository is under version control. After you have restarted RStudio you will now see new tabs in the RStudio panes. Click in the Git tab in the upper right pane. This reveals a bunch of folder and some files. The yellow boxes with the question marks under the status column indicate that these file are not yet under version control.

Folders and files which are not under version control.

Add files under version control

To bring these folders and files under version control you have to select all of them and click in one of the check boxes under the column “Staged”. You will see now a lot more files as all the files under the still untracked folders are explicitly shown. The A indicates that these files are new (are just added) to the repository.

New (Added) files to be set under version control.

Initial commit

A click in the Commit tab opens up a new window where you must write a message. This is necessary so that all collaborators (including the future-you!) remembers what was the change about. This first (e.g.initial) commit will bring all the files under version control.

The initial commit brings many files under version control.

Success message

After sending your message by clicking the Commit button you will see a list of all the committed files which are now in the local repository under version control. You can close this window and we can finally add our two lines copied from the GitHub page.

Files are successfully committed.

Connect local with remote repo

Insert the two copied lines from the GitHub repository into the Terminal tab (red arrow). The first line will establish the connection between the local and the remote repository. The second line will push all the committed local files to the GitHub repository.Depending of you internet connection and how many data has to be transferred this can take a couple of seconds (blue arrow).

Connecting local Git with remote GitHub repository and pushing the initial commit.

After this second step we are going to to get a live preview of your website.