One of the Research working parties for IFoA, Programming for Actuarial work has launched a manual using Github. The party is headed by Georgios Bakoloukas.
It is believed that the IFoA, has first time came up with a git repository This git repository hosts the markdown files that comprise the introductory guide to programming material.
The Institute and Faculty of Actuaries launched a revised exam curriculum in 2019. One of the reasons for doing so was because:
As a professional body the Institute and Faculty of Actuaries (IFoA) has a responsibility to ensure that the curriculum is relevant, up-to-date and reflects the skills, knowledge and attributes required of actuaries in an ever-changing global business environment.
— IFoA, Curriculum 2019
Advantages from this manual
As stated by IFoA “Programming can help meet the challenges of today’s business enviroment. Big data sets can be handled by code, where some spreadsheeet applications are limited to a maximum number of rows and columns of data. Code packages and libraries are readily available on shared networks, allowing for the rapid prototyping of sophisticated models and analyses reliably. Additionaly, code can perform faster than bulky applications, given they are lower in the computational stack than higher (more abstract) applications that are managing more processes and are further away from the computations happening at the hardware level.”
Aside from aiding actuarial work, programming knowledge can help actuaries extend their presense in fields outside of the traditional actuarial focus. For example, the algorithms behind data science and machine learning can be explored, web sites and apps can be built, and algorithmic trading can be employed using programming.
Sections to the IFoA’s Actuarial Programming Manual
This guide is broadly split into three sections.
First Section
- Basics of coding;
- Set up the programming environment
- Basic components that can be used.
Second section
- How to organize code
- Considering different paradigms and common patterns
- Manage version control.
The final section
- Data visualization
- Modelling.
This git repository hosts the markdown files that comprise the introductory guide to programming material. By rendering the markdown files (using the bookdown library in R), a collection of HTML files are created that represent the markdown files in a gitbook web friendly format. These web pages can then be hosted on GitHub pages for public viewing.
The rendered book by IFoA for programming is viewable here
In March, we covered which programming languages to learn, you can read more about that here.
Directory structure
There are two main folders in this directory: /book and /markdown.
The /markdown folder contains all the R markdown files that are to be rendered into the final book output. It also includes the R script to render these files into this HTML format.
The /book folder contains all the rendered HTML output. Each markdown file has its own HTML file respectively. A supporting /libs folder is created that contains the supporting libraries required for the final gitbook output.
Markdown files
The markdown files are based on the usage specified in the bookdown R library. An online user guide (rendered with bookdown itself) can be found here.
Each chapter has its own R markdown file. The name of the file indicates the order of each chapter, e.g. 01-intro.Rmd will be placed first etc. Files that begin with an underscore are ignored during rendering. The file called index.Rmd is always placed first and is the ‘landing page’ of the final gitbook site. It is also the first parameter required for the render book function used in R.
A guide to the available markdown syntax can be found here.
After a contributor has finished editting the R markdown files, they will need to run the script in the _renderbook.R file in order to render them into the final HTML files for web viewing. The first line of this script needs to be altered to the relevant directory location, depending on where the contributor has cloned their instance of this repo.
The final rendered book can be viewed locally by opening the /book/index.html page in your browser. When editing the markdown files, this local site can be left open. To view the result of any changes made, save the updated Rmd files, run the render book script in R, and then refresh your browser.
Github pages
Github has the ability to host static web pages, such as our rendered bookdown output. More information can be found here.
For each user, github offers the <username>.github.io domain as a free static web host. The content of the <username>.github.io repo is then displayed at this web address.
There are several ways to implement the static web pages. Github can render markdown files into its own template web pages (using Jekyll), and even R code can be run (using Travis) when committing changes to this repo.
However, in its simplest implementation, just rendering the R markdown files locally into the /book directory allows a user to view the book at institute-and-faculty-of-actuaries.github.io/book or institute-and-faculty-of-actuaries.github.io/book/index.html once pushed to the origin remote.
The bookdown and github pages specific workflow is therefore:
- git pull/clone the repo, and create a new branch to commit proposed changes to
- Make changes to the R markdown files and commit to the new branch
- To view the rendered markdown, alter the first line of the _renderbook.R script to the relevant location and run the next two lines
- It is preferable to commit only the markdown changes, as the rendered HTML files can be made following approval of the markdown changes
- Git commit and push the changes made
Let us know what do you think of the big step IFoA has taken to come up with such a book? Are you going to use it anytime soon?
