diff --git a/.Rbuildignore b/.Rbuildignore index d25daa1..0f40a15 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -7,3 +7,4 @@ cran-comments.md data-raw/ ^README\.Rmd$ ^README-.*\.png$ +^CONDUCT\.md$ diff --git a/CONDUCT.md b/CONDUCT.md new file mode 100644 index 0000000..52a673e --- /dev/null +++ b/CONDUCT.md @@ -0,0 +1,25 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, we pledge to respect all people who +contribute through reporting issues, posting feature requests, updating documentation, +submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for +everyone, regardless of level of experience, gender, gender identity and expression, +sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. + +Examples of unacceptable behavior by participants include the use of sexual language or +imagery, derogatory comments or personal attacks, trolling, public or private harassment, +insults, or other unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, +commits, code, wiki edits, issues, and other contributions that are not aligned to this +Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed +from the project team. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by +opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the Contributor Covenant +(http:contributor-covenant.org), version 1.0.0, available at +http://contributor-covenant.org/version/1/0/0/ diff --git a/README.Rmd b/README.Rmd index bcf8ce6..16ccf81 100644 --- a/README.Rmd +++ b/README.Rmd @@ -14,17 +14,6 @@ knitr::opts_chunk$set( [![Build Status](https://travis-ci.org/philmikejones/rakeR.svg?branch=master)](https://travis-ci.org/philmikejones/rakeR) -Developer note -============== - -Do not push to **`origin/master`**! - -**`origin/master`** is a protected branch and expects CI tests to have been -successfully completed before it will merge code. - -Develop in a new branch (suggest `origin/develop`), check your changes with -`devtools::check()`, and submit a pull request to be checked by Travis CI. - rakeR ===== @@ -38,12 +27,17 @@ Install Install the development version with `devtools`: -```{r install-rakeR} +```{r install-rakeR, eval=FALSE, include=TRUE} # Obtain devtools if you don't already have it installed # install.packages("devtools") # Install rakeR development version from GitHub devtools::install_github("philmikejones/rakeR") +``` + +Load the package with: + +```{r attach-rakeR} library("rakeR") ``` @@ -80,10 +74,14 @@ inds <- data.frame( vars <- c("age", "sex") ``` -Basic raking is done with `weight()`. Integerisation is performed with -`integerise()`, for now using the truncate, replicate, sample method. -Finally, `simulate()` takes care of creating the final microsimulated data set. -They can be combined with pipes: +* (Re-)weighting is done with `weight()` which returns a data frame of +fractional weights. +* Integerisation is performed with `integerise()` which returns a data frame of +integerised weights. +* `simulate()` takes care of creating the final microsimulated data and returns +a data frame of simulated cases in zones. + +These functions can be combined with pipes: ```{r chain-example} # obtain magrittr if not already installed @@ -103,15 +101,32 @@ sim_df ``` +Contributions +============= + +Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms. + +Feedback on the API, bug reports/issues, and pull requests are very welcome. + +If making a pull request **do not** push to `origin/master`! +`origin/master` is a protected branch and expects CI tests to have been +successfully completed before it will merge code. + +Develop in a new branch, check your changes with `devtools::check()`, and +submit a pull request which will be checked by Travis CI. + + Acknowledgements ---------------- Many of the functions in this package are based on code written by [Robin Lovelace](https://github.com/Robinlovelace) and [Morgane Dumont](https://github.com/modumont) for their book -[*Spatial Microsimulation with R* (2016), Chapman and Hall/CRC Press](https://www.crcpress.com/Spatial-Microsimulation-with-R/Lovelace-Dumont/p/book/9781498711548). +[*Spatial Microsimulation with R* (2016), Chapman and Hall/CRC Press](https://www.crcpress.com/Spatial-Microsimulation-with-R/Lovelace-Dumont/p/book/9781498711548). Their book is also an excellent resource for learning +about spatial microsimulation and understanding what's going on under the hood +of this package. -The ipfp algorithm itself is +The rewighting (ipfp) algorithm itself is [written by Andrew Blocker](https://github.com/awblocker/ipfp) and is written in `C` for maximum speed and efficiency. diff --git a/README.md b/README.md index e69de29..c8bb0cc 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,187 @@ + + +[![Build Status](https://travis-ci.org/philmikejones/rakeR.svg?branch=master)](https://travis-ci.org/philmikejones/rakeR) + +rakeR +===== + +Create a spatial microsimulated data set in R using iterative proportional fitting ('raking'). + +Install +------- + +Install the development version with `devtools`: + +``` r +# Obtain devtools if you don't already have it installed +# install.packages("devtools") + +# Install rakeR development version from GitHub +devtools::install_github("philmikejones/rakeR") +``` + +Load the package with: + +``` r +library("rakeR") +#> +#> Attaching package: 'rakeR' +#> The following object is masked from 'package:stats': +#> +#> simulate +``` + +Raking +------ + +To perform the raking you should supply two data frames, one with the constraint information with counts per category for each zone (e.g. census counts) and one with individual--level data (i.e. one row per individual). In addition supply a character vector with constraint variable names. + +``` r +cons <- data.frame( + + "zone" = letters[1:3], + "a0_49" = c(8, 2, 7), + "a_gt50" = c(4, 8, 4), + "f" = c(6, 6, 8), + "m" = c(6, 4, 3) + +) + +inds <- data.frame( + + "id" = LETTERS[1:5], + "age" = c("a_gt50", "a_gt50", "a0_49", "a_gt50", "a0_49"), + "sex" = c("m", "m", "m", "f", "f"), + "income" = c(2868, 2474, 2231, 3152, 2473), + stringsAsFactors = FALSE + +) + +vars <- c("age", "sex") +``` + +- (Re-)weighting is done with `weight()` which returns a data frame of fractional weights. +- Integerisation is performed with `integerise()` which returns a data frame of integerised weights. +- `simulate()` takes care of creating the final microsimulated data and returns a data frame of simulated cases in zones. + +These functions can be combined with pipes: + +``` r +# obtain magrittr if not already installed +# install.packages("magrittr") +library("magrittr") + +sim_df <- weight(cons, inds, vars) %>% integerise() %>% simulate(inds = inds) +sim_df +#> id age sex income zone +#> 1 A a_gt50 m 2868 a +#> 2 B a_gt50 m 2474 a +#> 3 C a0_49 m 2231 a +#> 3.1 C a0_49 m 2231 a +#> 3.2 C a0_49 m 2231 a +#> 3.3 C a0_49 m 2231 a +#> 4 D a_gt50 f 3152 a +#> 4.1 D a_gt50 f 3152 a +#> 5 E a0_49 f 2473 a +#> 5.1 E a0_49 f 2473 a +#> 5.2 E a0_49 f 2473 a +#> 5.3 E a0_49 f 2473 a +#> 1.1 A a_gt50 m 2868 b +#> 1.2 A a_gt50 m 2868 b +#> 2.1 B a_gt50 m 2474 b +#> 3.4 C a0_49 m 2231 b +#> 4.2 D a_gt50 f 3152 b +#> 4.3 D a_gt50 f 3152 b +#> 4.4 D a_gt50 f 3152 b +#> 4.5 D a_gt50 f 3152 b +#> 4.6 D a_gt50 f 3152 b +#> 5.4 E a0_49 f 2473 b +#> 5.5 E a0_49 f 2473 b +#> 2.2 B a_gt50 m 2474 c +#> 3.5 C a0_49 m 2231 c +#> 4.7 D a_gt50 f 3152 c +#> 4.8 D a_gt50 f 3152 c +#> 5.6 E a0_49 f 2473 c +#> 5.7 E a0_49 f 2473 c +#> 5.8 E a0_49 f 2473 c +#> 5.9 E a0_49 f 2473 c +#> 5.10 E a0_49 f 2473 c +#> 5.11 E a0_49 f 2473 c +``` + +Alternatively use the `rake()` function, which is a wrapper for `weight() %>% integerise() %>% simulate()`: + +``` r +sim_df <- rake(cons, inds, vars) +sim_df +#> id age sex income zone +#> 1 A a_gt50 m 2868 a +#> 2 B a_gt50 m 2474 a +#> 3 C a0_49 m 2231 a +#> 3.1 C a0_49 m 2231 a +#> 3.2 C a0_49 m 2231 a +#> 3.3 C a0_49 m 2231 a +#> 4 D a_gt50 f 3152 a +#> 4.1 D a_gt50 f 3152 a +#> 5 E a0_49 f 2473 a +#> 5.1 E a0_49 f 2473 a +#> 5.2 E a0_49 f 2473 a +#> 5.3 E a0_49 f 2473 a +#> 1.1 A a_gt50 m 2868 b +#> 1.2 A a_gt50 m 2868 b +#> 2.1 B a_gt50 m 2474 b +#> 3.4 C a0_49 m 2231 b +#> 4.2 D a_gt50 f 3152 b +#> 4.3 D a_gt50 f 3152 b +#> 4.4 D a_gt50 f 3152 b +#> 4.5 D a_gt50 f 3152 b +#> 4.6 D a_gt50 f 3152 b +#> 5.4 E a0_49 f 2473 b +#> 5.5 E a0_49 f 2473 b +#> 2.2 B a_gt50 m 2474 c +#> 3.5 C a0_49 m 2231 c +#> 4.7 D a_gt50 f 3152 c +#> 4.8 D a_gt50 f 3152 c +#> 5.6 E a0_49 f 2473 c +#> 5.7 E a0_49 f 2473 c +#> 5.8 E a0_49 f 2473 c +#> 5.9 E a0_49 f 2473 c +#> 5.10 E a0_49 f 2473 c +#> 5.11 E a0_49 f 2473 c +``` + +Contributions +============= + +Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms. + +Feedback on the API, bug reports/issues, and pull requests are very welcome. + +If making a pull request **do not** push to `origin/master`! `origin/master` is a protected branch and expects CI tests to have been successfully completed before it will merge code. + +Develop in a new branch, check your changes with `devtools::check()`, and submit a pull request which will be checked by Travis CI. + +Acknowledgements +---------------- + +Many of the functions in this package are based on code written by [Robin Lovelace](https://github.com/Robinlovelace) and [Morgane Dumont](https://github.com/modumont) for their book [*Spatial Microsimulation with R* (2016), Chapman and Hall/CRC Press](https://www.crcpress.com/Spatial-Microsimulation-with-R/Lovelace-Dumont/p/book/9781498711548). Their book is also an excellent resource for learning about spatial microsimulation and understanding what's going on under the hood of this package. + +The rewighting (ipfp) algorithm itself is [written by Andrew Blocker](https://github.com/awblocker/ipfp) and is written in `C` for maximum speed and efficiency. + +Contact +------- + +philmikejones at gmail dot com + +Licenses +-------- + +Copyright 2016 Phil Mike Jones. + +rakeR is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. + +rakeR is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with rakeR. If not, see . + +See [LICENSE](https://github.com/philmikejones/rakeR/blob/master/LICENSE)