mages' blog

Last week we released version 0.1.5-4 of the ChainLadder package on CRAN. The R package provides methods which are typically used in insurance claims reserving. If you are new to R or insurance check out my recent talk on Using R in Insurance.

The chain-ladder method which is a popular method in the insurance industry to forecast future claims payments gave the package its name. However, the ChainLadder package has many other reserving methods and models implemented as well, such as the bootstrap model demonstrated below. It is a great starting point to learn more about stochastic reserving.

Since we published version 0.1.5-2 in March 2012 additional functionality has been added to the package, see the change log, but in particular the vignette has come a long way.

Many thanks to my co-authors Dan Murphy and Wayne Zhang.

I am very grateful to all who provided feedback over the last two weeks and tested the previous versions 0.3.1 and 0.3.2, which were not released on CRAN.

So, what changed since version 0.3.2?

Not much, but plot.gvis didn't open a browser window when options(gvis.plot.tag) were not set to NULL, but the user explicitly called plot.gvis with tag NULL. Thanks to Sebastian Kranz for reporting this bug. Additionally the vignette has been updated and includes an extended section on knitr.

As usual, you can download the most recent version from our project site. It will take a few days before version 0.3.3 will be available on CRAN for all operating systems.

Many thanks to all who participated in the survey about writing R package vignettes.

Following my post last Thursday the responses came in quickly in the evening and all day on Friday. Since Saturday the response rate has been decreasing constantly and I think it is time for a summary based on the 56 responses received.

Summary - How to write a good vignette

• Length: Trust yourself, but aim for about 20 pages.
  
• Language: Don't use language which assumes that the reader is an R and/or subject expert.
  
• Structure: Include at least the following sections:
  
  • Examples
    
  • Introduction
    
  • Case studies
    
  • References
    
  It would be nice to include also sections on:
  • Support
    
  • Motivation
    
  • Road map
    
• Examples: Use lots of examples and don't repeat just the examples from the help pages.
  
• Get inspiration from: Rcpp, reshape, plyr, vegan, and see below for more.
  
• Secrets of good vignettes:
  
  • Provide an introduction with a clear purpose of the package.
    
  • Work with case studies, walk the reader through a task from start to finish.
    
  • Demonstrate the non-default arguments of the package functions, highlight why and when you want to change them.
    
  • Write briefly and concisely, but provide reference/footnotes to relevant literature and further help.
    
  • Provide dummy data to play with.
    
  • Discuss limitations.
    
• What else: Potentially split the vignette into several documents, see Rcpp for an example.
  

I am currently co-writing the vignette for the ChainLadder package and wonder what I should be focusing on. I have co-written the vignette of the googleVis package in the past and based it purely and what I thought would work. So, this is an experiment to find out, if user feedback will help me to write a better vignette. Let's see how it develops. I will make the data available once I have at least 10 submission.


Thanks!