Part 2 Instructions for Contributors

2.1 Video Contributors

Each chapter will have 3-8 sections, roughly corresponding to the book.

Goal. The purpose of the video is to provide an interactive experience, where learners can review the main ideas of the book.

Learning Objectives

  • Start each section with a set of 3 or 4 learning objectives.
  • For each section, the video will reinforce the learning objectives. It is okay to use the learning objectives from the text. Then, the video will provide exactly the information needed for the learner to complete the interactive exercises.

Background of Viewers. You can assume that the viewer will have read the text. However, just as students in your classes, they will probably have forgotten the substance. So, big points need to be reinforced.

Relationship with Tutorials

  • As part of the purpose of the video is to provide background for the tutorials, there will need to be close co-ordination between the two.
  • Sometimes a video can provide a complicated analysis of a data set and then the tutorial can ask the learner to go through essentially the same analysis albeit with modifications.
  • Many of the overheads will provide a combination of code and output from the code. Explain this to the viewer in a way that he or she can reproduce it in a related situation.

Video Overheads

  • Use whatever system you like (e.g., latex/beamer, Powerpoint) to produce the video overheads in .pdf format.
  • If you are indifferent, try R markdown (that uses latex/Beamer), as in the Chapter 1 Example. As this integrates well with our online delivery software (R markdown/Bookdown), this will probably become the standard later on as we develop protocols to replicate our work for other courses.

Video Production

  • Use whatever recording system that you like. If you do not have experience in this, one easily accessible avenue is to use Zoom’s ability to record. This is how the Frees examples in Chapter 1 were done.
  • Everyone does this differently, but one approach is to write out the scripts of what you want to say prior to the recording. Here are some examples for Chapter 1 of the first course. This means it takes longer to produce the first draft but is more time efficient for those of us who require multiple drafts to get a good quality video. Think of about 1000 words for an 8 minute video.
  • A bonus of writing the scripts in advance is that they are helpful when adding closed-captioning to the videos (really useful for international audiences). Here is the system that we used to add closed captions to the videos:
    • Go to Youtube, open an account (that is free), and upload the video.
    • After a bit of time (needed to process the video), you can go to the “subtitles” part and add captions.
    • Upload the script (as a text file) without timings. Then, Youtube will sync up your file with the video and add timings to it.
    • Wait a bit. Ten minutes seemed to work well (although the system warns you it may require more time). Then, you can download the closed-caption file using one of three formats. We use the “.srt” extension because this is what the hosting site (Kaltura) uses. Despite the extension, these are all just text files and so it is simple to edit if you find errors you wish to fix.
    • Then, we simply uploaded the video file (often .mpeg) and the closed-caption file to the hosting site. Done. You can delete the work from Youtube, if you wish.

2.2 Tutorial Problem Contributors

For each section, the goal is to have one or two tutorial exercises that will reinforce learning objectives of the section.

Assignment Text. Start with a set of background information known as the assignment text. This is relatively brief. For example, Datacamp recommends 540 characters with a target range of 30 to 780 characters.

Instructions. Next comes a set of instructions, typically written in a bullet fashion where each bullet corresponds to a part.

  • The target is for three parts but this may range from 1 to 4
  • For each part, the ideal is 360 characters with a target range of 30 to 480 characters.

Hints may also be provided. Again they should be short (about 270 characters) and there may be from 0 to 4 hints per exercise.

Solution Code. Provide the R code that solves the problem described in the assignment text and instructions.

Sample Code. Copy the solution code and remove selected variables and function names that you think users would learn from filling in. Consider a range of 8-12 lines of code but feel free to deviate to accomplish learning objectives.

Success Messages. Give one to three lines providing encouragement for users and summarizing what they have learned in this exercise. Here is a description of what these elements look like when coded in R.

For most contributors, it is likely that it will be easiest to work with our TutorialTemplate.Rmd that you can get when you download the whole site (in the References folder), or directly from here.

2.2.1 Datacamp Light

Tutorial problem contributors do not need to get into the online tutorial system. Just simply provide the problem set-up (assignment and instructions) and the R-code solutions and sample code, with hints and success messages as added plusses.

The main thing to understand is that the system takes the R code, shoots it to a server someplace that executes the code, and sends results back to the user. Although this is very cool (e.g., R need not be installed on the user’s machine), an implication is that not all the packages that we want are installed on this server. Sadly, Datacamp has not upgraded this service in the last 2-3 years, so we have to be careful in the choice of packages we use. Here is a list of packages readily available. If you use a package that you have not seen before in the tutorial, please check it prior to providing R code. One exception: for this course, we will use a lot of functions from the actuar() package and so intend to make them available individually (by putting the source code on Github). Not too clean but it works.

Moreover, if you would like to learn more, see the following.

Datacamp Light URLs. Datacamp has created a javascript app called Datacamp Light that allows for an interactive learning platform in an html environment. In this general app, you do not need to work in an R environment but, since we are doing so, life is easier. See https://github.com/datacamp/datacamp-light.

Tutorial problem contributors can start with the R tutorial package that one can install, for example, in R markdown. In the package documentation, you can see that one can also code up Python exercises with “tutorial.” With R markdown, we are producing html output. The tutorial package generates some javascript syntax needed from our problems, so we will not need the general Datacamp Light app. However, as we are all interested in learning, it may be that the source code will be of interest.

Users ultimately want to see a correct solution. If the learner does not get the correct solution, then the Section 2.3 submission correction tests provides guidance on correcting the source of the mistakes.

2.2.2 Data

Many tutorial problems will involve interesting data. You might start with the data in the Loss Data Analytics book as many students will be familiar with them from their reading.

(Right click, then “save page as” a text or .csv file)

For other datasets, there are a few in the Regression Modeling with Actuarial and Financial Applications book.

In particular, the R package CASdatasets has many good choices; this package is based on the book Computational Actuarial Science with R.

2.3 Submission Correction Tests Contributors

These are fairly specialized part of the tutorial system; so, our strategy is to have one or two volunteers that will focus on this aspect. They provide guidance to users on how to correct commonly occurring mistakes. They are a super helpful part of so-called “intelligent tutoring systems” but may take us awhile to implement properly.

Like the app Datacamp Light, Datacamp has created an app called testwhat for providing feedback on the R version of Datacamp Light (another app called pythonwhat is for Python code. Other apps are also available for SQL, Shell, and Spreadsheets.).

Our users submit their code to Datacamp servers and so there is nothing for us to install.

The Submission Correction Tests (SCTs) provides us an opportunity to give “individualized” feedback to help students learn from their mistakes. The basics of the syntax are available from the testwhat site. Go through each of the tabs (Syntax, Glossary, Guides, and so on). Our challenge will be to anticipate the main types of mistakes that students might make and provide code to help them along.

Here are some additional sources that may be helpful:

2.4 Using the Short Course

We hope that you (and anyone else) will be interested in taking the foundations of the short course and modifying it to suit your own needs. To make this happen, here are two potentially important pieces:

2.4.1 Download and Edit a Local Copy of the Course

  1. Optional - Get reasonably recent versions of R and Rstudio. Sometimes, there can be conflicts if you are running very old versions these products. (Probably best to do this step at a later stage in case you run into problems that you can’t debug.)
  2. Optional - Update packages. We have discovered conflicts between some of the advanced graphics/RGL and javascript in chapter 3 with old versions of some packages. Surprisingly, the one exception is the package bookdown. We found that an old version (0.21) works best. So, use this code:
  3. Download a copy of the book. Go to Github, https://github.com/OpenActTextDev/LifeCon, hit the green “Code” button, download a .zip file and uncompress it.
  4. Open R-studio, go to “File==>Open Project.” From the folder you just downloaded and uncompressed, select “LifeCon.Rproj.”
  5. In R studio, open the file “PackagesLifeCon.Rmd” (but do not knit it). These are the packages that will be called when you compile the book, so install them now if needed.
  6. In R-studio, go to the upper right tab, hit “Build.” This brings up a “Build Book” tab. Click the down arrow to the right and select “bookdown::gitbook.” This starts the compile process.
  7. Upon successful compile, you should see a preview of the book. If it gets lost, go to the “docs” subfolder and open “index.html” in a browser, hopefully you see the compiled book.
  8. As you edit the book, go to the file "_bookdown.yml". This allows you to select the .Rmd files (and the order) that you wish to appear in the book.

2.4.2 Upload your Course Version to Github

  1. Start by getting a (free) Github account.
  2. We are going to follow the process documented at https://happygitwithr.com/existing-github-first.html, so you might want to look over this excellent resource before beginning.
  3. 16.1 Make a repo on GitHub
    • Go to https://github.com and make sure you are logged in.
    • Click the green “New repository” button. Or, if you are on your own profile page, click on “Repositories,” then click the green “New” button.
    • Pick a repository name that actually reminds you what the project is about! But try to be concise.
    • Public = YES Initialize this repository with a README
    • Click the big green button “Create repository.”
    • Copy the HTTPS clone URL to your clipboard via the green “Clone or Download” button.
  4. In R-studio, open a new project.
    • “File==>New Project==>Version Control==>Git.” In the “repository URL” paste the URL of your new GitHub repository. It will be something like this https://github.com/jennybc/myrepo.git.
  5. Close R studio and copy the existing project onto the one you just created.
  6. Open R studio with the newly created project. I have had a little trouble getting the first commit done on my machine. So, I have to do it by hand:
  7. Now, we can leave the shell
    • Git tab ==> Commit ==>Provide a short descriptive name
    • Then hit the push (up arrow). When it asks for authentication, put in your Github name. Use the personal access token instead of the Github password. Hopefully everything goes up to Github.
  8. Finally to get the world to see your page:
    • Settings ==> GitHub pages ==>Check it out here! ==>
    • Source Change “None” to “main.” Change “/root” to “/docs” . Then save.

May need to wait a couple minutes. Then, you can view your new book at, for example, https://ewfreesres.github.io/TestActMatch/