Implementing Demography by Preston et al. (2001) as an R package

Transcription

1 Implementing Demography by Preston et al. (2001) as an R package ROLAND RAU University of Rostock, Summer Term April 2014 c Roland Rau Demography in R 1 / 24

2 Goal of the Seminar: Demographic Methods Implemented as an R Package What is an R package? Packages in R provide extra functionality by implementing new functions, making extra data available,... A package can be downloaded from one of the R mirrors via: install.package("package-name") and can be loaded (i.e. it makes the functions available to the user) via library(package-name). R version ( ) -- "Masked Marvel" Copyright (C) 2013 The R Foundation for Statistical Computing Platform: x86_64-unknown-linux-gnu (64-bit) R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under certain conditions. Type license() or licence() for distribution details. Natural language support but running in an English locale R is a collaborative project with many contributors. Type contributors() for more information and citation() on how to cite R or R packages in publications. Type demo() for some demos, help() for on-line help, or help.start() for an HTML browser interface to help. Type q() to quit R. > library(scatterplot3d) > c Roland Rau Demography in R 2 / 24

3 Goal of the Seminar: Demographic Methods Implemented as an R Package What is an R package? Packages in R provide extra functionality by implementing new functions, making extra data available,... A package can be downloaded from one of the R mirrors via: install.package("package-name") and can be loaded (i.e. it makes the functions available to the user) via library(package-name). Our goal: create a package, full of demographic methods so other people do not have to re-invent the wheel over and over again. Writing functions for a package sounds simple, but could be tricky! c Roland Rau Demography in R 3 / 24

4 Requirements & Preliminary Questions (Minimum) Requirements: Basic knowledge of R (how to run R code; how to write R code, especially how to write a function) Knowledge of standard demographic methods. The seminar requires active participation. Thus, you need to be able to read, write and speak in English. Basic familiarity with the command line ("Eingabeaufforderung"), i.e. opening the command prompt, change between folders/directories with "cd", execute programs... Intrinsic motivation to learn more about programming. Questions: Who knows how a package looks like? Who has experience writing a package? Who has a laptop/notebook? (not necessary but very useful!) Which Operating System (Windows? Unix/Linux? Mac?) c Roland Rau Demography in R 4 / 24

5 How to successfully complete this course? Create a small package with some functions (maybe data), including: help-files (?thenewfunction), examples & error checking. A larger text document is then required as the documentation: What is this method about? Who invented it? What are possible area of application? Are there any potential pitfalls? How do I use it? How can I interpret the results?... i.e. a small Hausarbeit (anyone experience with L A T E X?). I will assemble the parts and then make a larger package (what should be its name?), which could be uploaded either to my university homepage and/or to CRAN (cran.r-project.org). c Roland Rau Demography in R 5 / 24

6 The Six Meetings of the Seminar Date Time Content pm 7pm Introduction pm 7pm Assignments of topics; creating a simple package together pm 7pm Workshop am 5pm Workshop pm 7pm Presentations am 5pm Presentations c Roland Rau Demography in R 6 / 24

7 Possible Topics Decomposition of the crude death rate Period life table (one year, flexible age-group width) Decomposition of life expectancy differences Cause-elimination life tables Age-cause decomposition of life expectancies Tempo-adjusted TFR Matrix-Populations: λ 1, w, v, P i, GRR, NRR, T Brass relational mortality model Estimating r (continuous case) Fitting parametric mortality models (Gompertz, Gompertz-Makeham, de Moivre, Kannisto,... ) and/or Brass logit-model Cohort-component projection Indirect estimation techniques ( c Roland Rau Demography in R 7 / 24

8 Data Sources Demographic methods typically require some data. The following sources could be used to create examples: Human Mortality Database ( Human Fertility Database ( Latin American Human Mortality Database ( The Information System of the Federal Health Monitoring ( c Roland Rau Demography in R 8 / 24

9 Anatomy of a minimal package DESCRIPTION man NAMESPACE R c Roland Rau Demography in R 9 / 24

10 Anatomy of a minimal package The file DESCRIPTION Package: testpackage Type: Package Title: Checks whether the build system works Version: 1.0 Date: Author: Roland Rau Maintainer: Roland Rau <roland.rau@uni-rostock.de> Description: It is just a package to check whether everything works License: GPL-2 c Roland Rau Demography in R 10 / 24

11 Anatomy of a minimal package The file NAMESPACE exportpattern("^[[:alpha:]]+") c Roland Rau Demography in R 11 / 24

12 Anatomy of a minimal package The directory R consists of one file: quadrier.mich quadrier.mich <- function(x) x * x c Roland Rau Demography in R 12 / 24

13 Anatomy of a minimal package I The directory man consists of two files: quadrier.mich.rd and testpaket-package.rd File quadrier.mich.rd \name{quadrier.mich \alias{quadrier.mich %- Also NEED an \alias for EACH other topic documented here. \title{ this function simply squares its input \description{ Takes the (numerical) input and squares it. \usage{ quadrier.mich(x) %- maybe also usage for other objects documented here. \arguments{ \item{x{ A numerical object (scalar, matrix, or array) \details{ Here you can write further details. \value{ The function returns simply the square of the input c Roland Rau Demography in R 13 / 24

14 Anatomy of a minimal package II \references{ Preston et al. (2001) Demography. Blackwell \author{ Roland Rau \note{ no further notes \seealso{ sum, mean \examples{ quadrier.mich(4) % Add one or more standard keywords, see file KEYWORDS in the % R documentation directory. \keyword{ demography \keyword{ mortality c Roland Rau Demography in R 14 / 24

15 Anatomy of a minimal package I The directory man consists of two files: quadrier.mich.rd and testpaket-package.rd File testpaket-package.rd \name{testpaket-package \alias{testpaket-package \alias{testpaket \doctype{package \title{ Tests the build system \description{ More information to be listed here sometime in the future \details{ \tabular{ll{ Package: \tab testpaket\cr Type: \tab Package\cr Version: \tab 1.0\cr Date: \tab \cr License: \tab GPL-2\cr c Roland Rau Demography in R 15 / 24

16 Anatomy of a minimal package II \author{ Who wrote it Maintainer: Who to complain to <yourfault@somewhere.net> ~~ The author and/or maintainer of the package ~~ \references{ The Preston et al. (2001) "Demography" book. \keyword{ package, demography \examples{ quadrier.mich(1234) c Roland Rau Demography in R 16 / 24

17 Anatomy of a minimal package DESCRIPTION man NAMESPACE R This is the absolute minimum. Additional directories could be, for instance, data for (surprise, surprise) data or src for code, which needs to be compiled (C, Fortran,... ), or inst if you have a specific citation. c Roland Rau Demography in R 17 / 24

18 What do I need to create my own R packages? Having (a fairly recent version of) R is only a necessary but not a sufficient condition! The R Installation and Administration Manual (http: //cran.r-project.org/doc/manuals/r-release/r-admin.html) gives an overview how you can build R (and therefore also packages) yourself. I assume that most of you have MS Windows. There is an extra section: Appendix D The Windows toolset, which gives more detailed instructions. A more comprehensive overview is provided at As far as I can remember, you need the correct Rtools...exe as well as MikTeX (see a bit further down on this page), the basic installation option should be sufficient. There is also a section for Apple OS users; however, I am unfamiliar how things work for that operating system. The reference webpage for actually writing R packages is the manual Writing R Extensions. The most recent version can be found at: c Roland Rau Demography in R 18 / 24

19 How can I learn (teach to myself) to write a package? R is free software, open source software. Pick a package you think is interesting and read the code yourself. An alphabetic list of packages is available here: packages/available_packages_by_name.html Search the web for: how to write an r package or how to write an r package using windows. There will be more results than you can read. I can recommend the one by Friedrich Leisch or the one by Rob Hyndman ( building-r-packages-for-windows/). c Roland Rau Demography in R 19 / 24

20 Homework I Create an environment in which you can work (assuming you are on Windows) If you not (yet) know how to navigate on the command line: last chance to do so. For instance, check this webpage We only need the cd command and we might need to know how to switch from one drive to another. Read the respective section of the R administration and installation manual Install the required software (Rtools...exe, MikT E X) as mentioned at You need to set the PATH variable correctly (how to do it differs from one version of Windows to another). Rob Hyndman s webpage provides some assistance: building-r-packages-for-windows/ Download testpackage.zip from my homepage and save it in a dedicated directory/folder on your harddisk, for instance, C:\\Summer2014\\ c Roland Rau Demography in R 20 / 24

21 Homework II DO NOT SAVE IT ON THE DESKTOP; DO NOT SAVE IT IN MY DOCUMENTS!!!!!!! unzip the package Your directory structure should look somehow like this (using the same example): C:\\Summer2014\\testpackage\\testpackage\\DESCRIPTION \\NAMESPACE \\man \\R If this is your directory structure, please go (via cd) to the directory/folder: C:\\Summer2014\\testpackage and enter: R CMD check testpackage If this works without any errors, warnings, you are ready to go! :-) c Roland Rau Demography in R 21 / 24

22 Work Together Cooperate! (this seminar is not a zero-sum game) Thank you very much for your attention! c Roland Rau Demography in R 22 / 24

23 License This open-access work is published under the terms of the Creative Commons Attribution NonCommercial License 2.0 Germany, which permits use, reproduction & distribution in any medium for non-commercial purposes, provided the original author(s) and source are given credit. c Roland Rau Demography in R 23 / 24

24 Kontakt Universität Rostock Institut für Soziologie und Demographie Lehrstuhl für Demographie Ulmenstr Rostock Germany Tel.: Fax.: Sprechstunde im Sommersemester 2014: Mittwochs, 09:00 10:00 (und nach Vereinbarung) c Roland Rau Demography in R 24 / 24