Adding infrastructure for CRAN et al.

jacob-long · jacob-long · commit 5f5199d07d56 · 2018-01-11T15:20:40.000-05:00
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -10,3 +10,5 @@
 ^panel\-simulations\.R$
 ^diagnostics\.R$
 ^data\-raw$
+^cran-comments\.md$
+^CONDUCT\.md$
diff --git a/CONDUCT.md b/CONDUCT.md
@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+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, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at long.1377@osu.edu. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct/
+
+[homepage]: https://www.contributor-covenant.org
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: panelr
 Title: Regression Models and Utilities for Repeated Measures and Panel Data
-Version: 0.1.0
-Authors@R: person("Jacob A.", "Long", email = "long.1377@osu.edu", role = c("aut", "cre"))
+Version: 0.1.1
+Authors@R: person("Jacob A.", "Long", email = "long.1377@osu.edu", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-1582-6214"))
 Description: This package implements several methods for creating regression
   models that take advantage of the unique aspects of 
   panel data. It automates the "within-between" (also known as
diff --git a/NEWS.md b/NEWS.md
@@ -0,0 +1,14 @@
+# panelr 0.1.1
+
+* Added a `NEWS.md` file to track changes to the package.
+* Added infrastructure for CRAN submission.
+* Improved documentation and added references.
+* Added README.
+
+# panelr 0.1.0
+
+* Got things working such that it can be shared outside the maintainer's own
+computers.
+* Added WageData example, documentation, etc.
+* Unit testing and automated tests through Travis and Appveyor.
+
diff --git a/README.Rmd b/README.Rmd
@@ -0,0 +1,142 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, echo = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.path = "README-"
+)
+```
+
+[![Travis-CI Build Status](https://travis-ci.org/jacob-long/panelr.svg?branch=master)](https://travis-ci.org/jacob-long/panelr)[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/jacob-long/panelr?branch=master&svg=true)](https://ci.appveyor.com/project/jacob-long/panelr)[![Coverage Status](https://img.shields.io/codecov/c/github/jacob-long/panelr/master.svg)](https://codecov.io/github/jacob-long/panelr?branch=master)
+
+
+# panelr
+
+This is an R package designed to aid in the analysis of panel data, 
+designs in which the same group of respondents/entities are contacted/measured
+multiple times. `panelr` provides some useful infrastructure, like a 
+`panel_data` object class, as well as automating some emerging methods for
+analyses of these data.
+
+It automates the "within-between" (also known as
+"between-within" and "hybrid") specification that combines the
+desirable aspects of both fixed effects and random effects econometric models
+and fits them using the lme4 package in the backend. Bayesian estimation of 
+these models is supported by interfacing with the brms package.
+
+## Installation
+
+At the moment, `panelr` is only available through Github. A submission to 
+CRAN is coming soon.
+
+```{r eval = FALSE}
+install.packages("devtools")
+devtools::install_github("jacob-long/panelr")
+```
+
+Note the several dependencies: `dplyr`, `tidyr`, `lme4`, `pbkrtest`, `jtools`,
+`magrittr`, `stringr`, and `rlang`. You will need `brms` (and its dependencies,
+like `rstan`) to do Bayesian estimation.
+
+## Usage
+
+### `panel_data` frames
+
+While not strictly required, the best way to start is to declare your data
+as panel data. I'll load the example data `WageData` to demonstrate.
+
+```{r}
+library(panelr)
+data("WageData")
+colnames(WageData)
+```
+
+The two key variables here are `t` and `id`. `t` is the wave of the survey the
+row of the data refers to while `id` is the survey respondent. This is a 
+perfectly balanced data set, so there are 7 observations for each of the 595
+respondents. We will use those two pieces of information to create a 
+`panel_data` object.
+
+```{r}
+wages <- panel_data(WageData, id = id, wave = t)
+```
+
+We have to tell `panel_data()` which column refers to the unique identifiers
+for respondents/entities (the latter when you have something like countries
+or companies instead of people) and which column refers to the period/wave of
+data collection. If the waves are not numeric and indexed starting at 1, 
+the function will attempt to coerce them to that kind of numbering scheme.
+
+Note that the resulting `panel_data` object will always use the column names
+`id` and `wave`, so it will overwrite those columns if they already exist in the
+source data. `panel_data` frames are modified tibbles 
+([`tibble` package](http://tibble.tidyverse.org/)) that are grouped by entity.
+
+### `wbm` --- the within-between model
+
+Anyone can fit a within-between model without the use of this package as it is
+just a particular specification of a multilevel model. With that said, it's 
+something that will require some programming and could be rather prone to 
+error. In the best case, it is cumbersome and inefficient to create the 
+necessary variables. 
+
+`wbm` is the primary function that you'll use from this package and it fits
+within-between models for you, utilizing
+[`lme4`](https://cran.r-project.org/web/packages/lme4/index.html) as a 
+backend. 
+
+A three-part model syntax is used that goes like this:
+
+`dv ~ varying_variables | invariant_variables | cross_level_interactions`
+
+It works like a typical formula otherwise. The bars just tell `panelr` how to 
+treat the variables. Note also that you can specify random slopes using
+`lme4`-style syntax in the third part of the formula as well. 
+
+Lagged variables are supported as well through the `lag` function. Unlike base
+R, `panelr` lags the variables correctly --- wave 1 observations will have NA
+values for the lagged variable rather than taking the final wave value of the
+previous entity. 
+
+Here we will specify a model using the `wages` data. We will predict 
+logged wages (`lwage`) using two time-varying variables --- lagged
+union membership (`union`) and contemporaneous weeks worked (`wks`) --- along 
+with a time-invariant predictor, a binary indicator for black race (`blk`).
+For demonstrative purposes, we'll fit a random slope for `wks` and an 
+interaction between `blk` and `lag(union)`.
+
+```{r message = FALSE}
+model <- wbm(lwage ~ lag(union) + wks | blk | blk * lag(union) + (wks | id),
+             data = wages)
+summary(model)
+```
+
+Note that `imean` is an internal function that calculates the individual-level
+mean, which represents the between-subjects effects of the time-varying 
+predictors. The within effects are the time-varying predictors at the occasion 
+level with the individal-level mean subtracted. If you want the model specified
+such that the occasion level predictors do not have the mean subtracted, use
+the `model = "contextual"` argument. The "contextual" label refers to the way 
+these terms are normally interpreted when it is specified that way.
+
+
+## Contributing
+
+I'm happy to receive bug reports, suggestions, questions, and (most of all)
+contributions to fix problems and add features. I prefer you use the Github 
+issues system over trying to reach out to me in other ways. Pull requests for
+contributions are encouraged.
+
+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.
+
+## License
+
+The source code of this package is licensed under the 
+[MIT License](http://opensource.org/licenses/mit-license.php).
diff --git a/cran-comments.md b/cran-comments.md
@@ -0,0 +1,18 @@
+## Test environments
+* local OS X install, R 3.4.3
+* local Ubuntu 17.04 install, R 3.4.3
+* ubuntu 12.04 (devel and release; on travis-ci), R 3.4.3
+* Windows 2012 Server (devel and release; on Appveyor)
+
+## R CMD check results
+
+0 errors | 0 warnings | 1 note
+
+* This is a new release.
+
+## Reverse dependencies
+
+This is a new release, so there are no reverse dependencies. I will be 
+submitting separately the package `clfe`, which will depend on this package.
+Since I develop both, I have control over their compatibility and they are 
+indeed compatible. 
