implementing ``demography'' by preston et al. (2001) as an ... · goal of the seminar:...

Implementing“Demography” by Preston et al. (2001)

as an R package

ROLAND RAU

University of Rostock, Summer Term 2014

07 April 2014

c© Roland Rau Demography in R 1 / 24

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, makingextra 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) vialibrary(package-name).

R version 3.0.0 (2013-04-03) -- "Masked Marvel"Copyright (C) 2013 The R Foundation for Statistical ComputingPlatform: 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)>


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, makingextra 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) vialibrary(package-name).

Our goal: create a package, full of demographic methods so other people do nothave to re-invent the wheel over and over again.

Writing functions for a package sounds simple, but could be tricky!


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 toread, 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!) WhichOperating System (Windows? Unix/Linux? Mac?)


How to successfully complete this course?

Create a small package with some functions (maybe data),including: help-files (?thenewfunction), examples & errorchecking. A larger text document is then required as thedocumentation: What is this method about? Who invented it?What are possible area of application? Are there any potentialpitfalls? How do I use it? How can I interpret the results? . . . i.e.a small “Hausarbeit” (anyone experience with LATEX?).

I will assemble the parts and then make a larger package (whatshould be its name?), which could be uploaded either to myuniversity homepage and/or to CRAN (cran.r-project.org).


cran.r-project.org

The Six Meetings of the Seminar

Date Time Content07.04.2014 5pm–7pm Introduction11.04.2014 3pm–7pm Assignments of topics; creating a

simple package together09.05.2014 3pm–7pm Workshop10.05.2014 9am–5pm Workshop23.05.2014 3pm–7pm Presentations24.05.2014 9am–5pm Presentations


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, Pi, 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(http://demographicestimation.iussp.org/)


http://demographicestimation.iussp.org/

Data Sources

Demographic methods typically require some data. The following sources could beused to create examples:

Human Mortality Database (www.mortality.org)

Human Fertility Database (www.humanfertility.org)

Latin American Human Mortality Database (www.lamortalidad.org)

The Information System of the Federal Health Monitoring (www.gbe-bund.de/)


Anatomy of a minimal package

DESCRIPTIONmanNAMESPACER



The file DESCRIPTION

Package: testpackageType: PackageTitle: Checks whether the build system worksVersion: 1.0Date: 2014-01-24Author: Roland RauMaintainer: Roland Rau <[email protected]>Description: It is just a package to check whether

everything worksLicense: GPL-2



The file NAMESPACE

exportPattern("^[[:alpha:]]+")



The directory R consists of one file: quadrier.mich

quadrier.mich <-function(x) x * x


Anatomy of a minimal package I

The directory man consists of two files: quadrier.mich.Rdand testpaket-package.RdFile 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}


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 }


Anatomy of a minimal package I

The directory man consists of two files: quadrier.mich.Rdand testpaket-package.RdFile 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\crType: \tab Package\crVersion: \tab 1.0\crDate: \tab 2014-01-24\crLicense: \tab GPL-2\cr


Anatomy of a minimal package II

}}\author{Who wrote it

Maintainer: Who to complain to <[email protected]>~~ The author and/or maintainer of the package ~~}\references{The Preston et al. (2001) "Demography" book.}\keyword{ package, demography }\examples{quadrier.mich(1234)}



DESCRIPTIONmanNAMESPACER

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 youhave a specific citation.


What do I need to create my own R packages?

Having (a fairly recent version of) R is only a necessary but not a sufficientcondition!

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. Iassume 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 athttp://cran.r-project.org/bin/windows/Rtools/. As far as I canremember, you need the correct Rtools...exe as well as MikTeX (see a bitfurther 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 thingswork for that operating system.

The reference webpage for actually writing R packages is the manual “Writing RExtensions”. The most recent version can be found at:http://cran.r-project.org/doc/manuals/r-release/R-exts.html


http://cran.r-project.org/doc/manuals/r-release/R-admin.html

http://cran.r-project.org/doc/manuals/r-release/R-admin.html

http://cran.r-project.org/bin/windows/Rtools/

http://cran.r-project.org/doc/manuals/r-release/R-exts.html

How can I learn (teach to myself) to write a package?

R is free software, open source software. Pick a package you think isinteresting and read the code yourself. An alphabetic list of packages isavailable here: http://www.cran.r-project.org/web/packages/available_packages_by_name.html

Search the web for: how to write an r package or how towrite an r package using windows. There will be more resultsthan you can read. I can recommend the one by Friedrich Leisch or theone by Rob Hyndman (http://robjhyndman.com/hyndsight/building-r-packages-for-windows/).


http://www.cran.r-project.org/web/packages/available_packages_by_name.html

http://www.cran.r-project.org/web/packages/available_packages_by_name.html

http://robjhyndman.com/hyndsight/building-r-packages-for-windows/


“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 webpagehttp://www.computerhope.com/issues/chusedos.htm. We only needthe cd command and we might need to know how to switch from one drive toanother.

Read the respective section of the R administration and installation manual

Install the required software (Rtools...exe, MikTEX) as mentioned athttp://cran.r-project.org/bin/windows/Rtools/

You need to set the PATH variable correctly (how to do it differs from one versionof Windows to another). Rob Hyndman’s webpage provides some assistance:http://robjhyndman.com/hyndsight/building-r-packages-for-windows/

Download testpackage.zip from my homepage and save it in a dedicateddirectory/folder on your harddisk, for instance,

C:\\Summer2014\\


http://www.computerhope.com/issues/chusedos.htm

http://cran.r-project.org/bin/windows/Rtools/



“Homework” II

DO NOT SAVE IT ON THE DESKTOP; DO NOT SAVE IT IN “MYDOCUMENTS”!!!!!!!

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! :-)


Work Together — Cooperate!(this seminar is not a zero-sum game)

Thank you very much for your attention!


License

This open-access work is published under the terms of the CreativeCommons Attribution NonCommercial License 2.0 Germany, whichpermits use, reproduction & distribution in any medium for non-commercialpurposes, provided the original author(s) and source are given credit.


Kontakt

Universität RostockInstitut für Soziologie und DemographieLehrstuhl für DemographieUlmenstr. 6918057 RostockGermany

Tel.: +49-381-498 4044Fax.: +49-381-498 118 4044Email: [email protected]

Sprechstunde im Sommersemester 2014: Mittwochs, 09:00–10:00(und nach Vereinbarung)


implementing ``demography'' by preston et al. (2001) as an ... · goal of the seminar:...

Documents