Merge pull request #16 from philmikejones/rake

add Rmd readme
philmikejones · Sep 10, 2016 · bd5456c · bd5456c
2 parents 0d96447 + bf66753
commit bd5456c
Show file tree

Hide file tree

Showing 4 changed files with 246 additions and 18 deletions.
diff --git 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
@@ -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
@@ -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
@@ -0,0 +1,187 @@
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+[![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 <http://www.gnu.org/licenses/>.
+
+See [LICENSE](https://github.com/philmikejones/rakeR/blob/master/LICENSE)