.Rbuildignore

@@ -2,4 +2,7 @@
 ^doc$
 ^.*\.Rproj$
 ^\.Rproj\.user$
-^NEWS\.md$
+^LICENSE\.md$
+^\.travis\.yml$
+^cran-comments\.md$
+^CRAN-RELEASE$

.gitignore

@@ -7,3 +7,4 @@ doc
 *.Rproj
 inst/doc
 *.DS_Store
+CRAN-RELEASE

.travis.yml

@@ -0,0 +1,4 @@
+# R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
+
+language: R
+cache: packages

DESCRIPTION

@@ -1,13 +1,12 @@
 Package: tidymv
 Type: Package
-Title: Plotting for generalised additive models
-Version: 2.0.0
-Date: 2019-01-10
+Title: Tidy Model Visualisation for Generalised Additive Models
+Version: 2.1.0
+Date: 2019-04-23
 Authors@R: person("Stefano", "Coretta", email = paste0("stefano.coretta", "@", "gmail.com"),
                   role = c("aut", "cre"))
-Description: This package provides functions for visualising generalised
-    additive models and get predicted values using tidy tools from the tidyverse.
-    The name stands for TIDY Model Visualisation.
+Description: Provides functions for visualising generalised
+    additive models and getting predicted values using tidy tools from the 'tidyverse' packages.
 URL: https://github.com/stefanocoretta/tidymv
 BugReports: https://github.com/stefanocoretta/tidymv/issues
 License: MIT + file LICENSE
@@ -26,3 +25,4 @@ Imports: cowplot,
 Suggests: knitr,
     rmarkdown
 VignetteBuilder: knitr
+Language: en_GB

LICENSE

@@ -1,21 +1,2 @@
-The MIT License
-
-Copyright (c) 2017 Stefano Coretta
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+YEAR: 2017
+COPYRIGHT HOLDER: Stefano Coretta

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2017 Stefano Coretta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NEWS.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## [2.1.0] - 2019-04-23
+### Added
+- examples in documentation for all functions
+
+### Changed
+- alpha of 0 line in difference smooth plot (now set to 0.5)
+- prepared for CRAN first release
+
+### Fixed
+- missing import in `plot_difference()`
+
+### Deprecated
+- ⚠️ `time_series` is now deprecated and replaced with `series`. `time_series` will be removed in future releases.
+
 ## [2.0.0] - 2019-01-10
 ### Added
 - `predict_gam()` to return a dataframe with all predictors and fitted values with standard error
@@ -26,7 +40,7 @@
 
 ## [1.5.2] - 2018-10-22
 ### Fixed
-- error with updated `rlang` 
+- error with updated `rlang`
 
 ## [1.5.1] - 2018-08-18
 ### Added
@@ -109,6 +123,7 @@
 - `create_start_event` function
 - `plot_gamsd` function
 
+[2.1.0]: https://github.com/stefanocoretta/tidymv/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/stefanocoretta/tidymv/compare/v1.5.4...v2.0.0
 [1.5.4]: https://github.com/stefanocoretta/tidymv/compare/v1.5.3...v1.5.4
 [1.5.3]: https://github.com/stefanocoretta/tidymv/compare/v1.5.2...v1.5.3

R/functions.R

@@ -5,7 +5,7 @@
 #' @param tibble A tibble arranged according to the series.
 #' @param series_col The name of the column that defines the group of series, as an unquoted expression.
 #'
-#' @return A tibble with an extra column that marks the begninning of the series.
+#' @return A tibble with an extra column that marks the beginning of the series.
 #'
 #' @examples
 #' library(dplyr)
@@ -107,18 +107,35 @@ predict_gam <- function(model, exclude_terms = NULL, length_out = 50, values = N
 #' It returns a tibble with the predictions from a a \link[mgcv]{gam} or \link[mgcv]{bam} object.
 #'
 #' @param model A \code{gam} or \code{bam} model object.
-#' @param time_series An unquoted expression indicating the model term that defines the time series.
+#' @param series An unquoted expression indicating the model term that defines the series on which smoothing is applied. This is the term that is displayed on the x-axis when plotting.
+#' @param time_series Deprecated, use \code{series} instead.
 #' @param series_length An integer indicating how many values along the time series to use for predicting the outcome term.
 #' @param conditions A list of quosures with \link[rlang]{quos} specifying the levels to plot from the model terms.
 #' @param exclude_random Whether to exclude random smooths (the default is \code{TRUE}).
 #' @param exclude_terms Terms to be excluded from the prediction. Term names should be given as they appear in the model summary (for example, \code{"s(x0,x1)"}).
 #' @param split Columns to separate as a named list.
 #' @param sep Separator between columns (default is \code{"\\."}, which is the default with \code{}). If character, it is interpreted as a regular expression.
 #'
+#' @examples
+#' library(mgcv)
+#' set.seed(10)
+#' data <- gamSim(4)
+#' model <- gam(y ~ fac + s(x2) + s(x2, by = fac) + s(x0), data = data)
+#'
+#' pred <- get_gam_predictions(model, x2)
+#'
 #' @export
-get_gam_predictions <- function(model, time_series, series_length = 25, conditions = NULL, exclude_random = TRUE, exclude_terms = NULL, split = NULL, sep = "\\.") {
-    time_series_q <- dplyr::enquo(time_series)
-    time_series_name <- rlang::quo_name(time_series_q)
+get_gam_predictions <- function(model, series, series_length = 25, conditions = NULL, exclude_random = TRUE, exclude_terms = NULL, split = NULL, sep = "\\.", time_series) {
+    if(!missing(time_series)) {
+      warning("This argument has been deprecated and will be removed in the future. Please use `series` instead.")
+
+      series_q = dplyr::enquo(time_series)
+    } else {
+      time_series = NULL
+      series_q <- dplyr::enquo(series)
+    }
+
+    series_name <- rlang::quo_name(series_q)
     outcome_q <- model$formula[[2]]
 
     fitted <- model$model
@@ -142,11 +159,11 @@ get_gam_predictions <- function(model, time_series, series_length = 25, conditio
         }
     }
 
-    time_series_min <- dplyr::select(fitted, !!time_series_q) %>% min()
-    time_series_max <- dplyr::select(fitted, !!time_series_q) %>% max()
+    series_min <- dplyr::select(fitted, !!series_q) %>% min()
+    series_max <- dplyr::select(fitted, !!series_q) %>% max()
 
     fitted <- fitted %>%
-        dplyr::select(-!!time_series_q, -!!outcome_q)
+        dplyr::select(-!!series_q, -!!outcome_q)
 
     if ("(AR.start)" %in% colnames(fitted)) {
         fitted$`(AR.start)` <- NULL
@@ -161,12 +178,12 @@ get_gam_predictions <- function(model, time_series, series_length = 25, conditio
 
     fitted_series <- fitted_series %>%
         dplyr::mutate(
-            !!rlang::quo_name(time_series_q) := rep(
-                list(seq(time_series_min, time_series_max, length.out = series_length)),
+            !!rlang::quo_name(series_q) := rep(
+                list(seq(series_min, series_max, length.out = series_length)),
                 nrow(fitted_series)
             )
         ) %>%
-        tidyr::unnest(!!time_series_q)
+        tidyr::unnest(!!series_q)
 
     if (ncol(fitted_series) > 0) {
         fitted_series <- fitted_series %>%
@@ -188,7 +205,7 @@ get_gam_predictions <- function(model, time_series, series_length = 25, conditio
     excluded_terms <- as.null()
     for (smooth in 1:length(model[["smooth"]])) {
         smooth_term <- model[["smooth"]][[smooth]][["term"]][[1]]
-        if (smooth_term != time_series_name) {
+        if (smooth_term != series_name) {
             excluded_terms <- c(excluded_terms, smooth_term)
             smooth_label <- model[["smooth"]][[smooth]][["label"]]
             exclude_smooths <- c(exclude_smooths, smooth_label)
@@ -281,10 +298,17 @@ get_gam_predictions <- function(model, time_series, series_length = 25, conditio
 #' @inheritParams get_gam_predictions
 #' @param comparison An unquoted expression indicating the model term for which the comparison will be plotted.
 #' @param facet_terms An unquoted formula with the terms used for faceting.
-#' @param conditions A list of quosures with \link[rlang]{quos} specifying the levels to plot from the model terms not among \code{time_series}, \code{comparison}, or \code{facet_terms}.
+#' @param conditions A list of quosures with \link[rlang]{quos} specifying the levels to plot from the model terms not among \code{series}, \code{comparison}, or \code{facet_terms}.
 #'
 #' @examples
-#' # see vignette
+#' library(mgcv)
+#' set.seed(10)
+#' data <- gamSim(4)
+#' model <- gam(y ~ fac + s(x2) + s(x2, by = fac) + s(x0), data = data)
+#'
+#' plot_difference(model, x2, list(fac = c("1", "2")))
+#'
+#' # For details, see vignette
 #' \dontrun{
 #' vignette("plot-smooths", package = "tidymv")
 #' }
@@ -294,8 +318,16 @@ get_gam_predictions <- function(model, time_series, series_length = 25, conditio
 #' @importFrom rlang "quo_name"
 #' @importFrom stats "predict"
 #' @export
-plot_smooths <- function(model, time_series, comparison = NULL, facet_terms = NULL, conditions = NULL, exclude_random = TRUE, exclude_terms = NULL, series_length = 25, split = NULL, sep = "\\.") {
-    time_series_q <- dplyr::enquo(time_series)
+plot_smooths <- function(model, series, comparison = NULL, facet_terms = NULL, conditions = NULL, exclude_random = TRUE, exclude_terms = NULL, series_length = 25, split = NULL, sep = "\\.", time_series) {
+    if(!missing(time_series)) {
+      warning("This argument has been deprecated and will be removed in the future. Please use `series` instead.")
+
+      series_q = dplyr::enquo(time_series)
+    } else {
+      time_series = NULL
+      series_q <- dplyr::enquo(series)
+    }
+
     comparison_q <- dplyr::enquo(comparison)
     facet_terms_q <- dplyr::enquo(facet_terms)
     if (rlang::quo_is_null(comparison_q)) {
@@ -306,12 +338,12 @@ plot_smooths <- function(model, time_series, comparison = NULL, facet_terms = NU
     }
     outcome_q <- model$formula[[2]]
 
-    predicted_tbl <- get_gam_predictions(model, !!time_series_q, conditions, exclude_random = exclude_random, exclude_terms = exclude_terms, series_length = series_length, split = split, sep = sep)
+    predicted_tbl <- get_gam_predictions(model, !!series_q, conditions, exclude_random = exclude_random, exclude_terms = exclude_terms, series_length = series_length, split = split, sep = sep)
 
     smooths_plot <- predicted_tbl %>%
         ggplot2::ggplot(
             ggplot2::aes_string(
-                rlang::quo_name(time_series_q), rlang::quo_name(outcome_q)
+                rlang::quo_name(series_q), rlang::quo_name(outcome_q)
             )
         ) +
         {if (!is.null(comparison_q)) {
@@ -359,27 +391,41 @@ plot_smooths <- function(model, time_series, comparison = NULL, facet_terms = NU
 #' Significant differences are marked with red areas.
 #'
 #' @examples
-#' # see vignette
+#' library(mgcv)
+#' set.seed(10)
+#' data <- gamSim(4)
+#' model <- gam(y ~ fac + s(x2) + s(x2, by = fac) + s(x0), data = data)
+#'
+#' plot_smooths(model, x2, fac)
+#'
+#' # For details, see vignette
 #' \dontrun{
 #' vignette("plot-smooths", package = "tidymv")
 #' }
 #'
 #' @inheritParams get_gam_predictions
-#' @param time_series An unquoted expression indicating the model term that defines the time series.
 #' @param difference A named list with the levels to compute the difference of.
-#' @param conditions A named list specifying the levels to plot from the model terms not among \code{time_series} or \code{difference}. Notice the difference with \link[tidymv]{plot_smooths}, which uses \link[rlang]{quos}.
+#' @param conditions A named list specifying the levels to plot from the model terms not among \code{series} or \code{difference}. Notice the difference with \link[tidymv]{plot_smooths}, which uses \link[rlang]{quos}.
 #'
 #' @export
-plot_difference <- function(model, time_series, difference, conditions = NULL, series_length = 100) {
-    time_series_q <- dplyr::enquo(time_series)
-    time_series_chr <- rlang::quo_name(time_series_q)
+plot_difference <- function(model, series, difference, conditions = NULL, series_length = 100, time_series) {
+    if(!missing(time_series)) {
+      warning("This argument has been deprecated and will be removed in the future. Please use `series` instead.")
+
+      series_q = dplyr::enquo(time_series)
+    } else {
+      time_series = NULL
+      series_q <- dplyr::enquo(series)
+    }
+
+    series_chr <- rlang::quo_name(series_q)
 
     fitted <- model$model
 
-    time_series_min <- dplyr::select(fitted, !!time_series_q) %>% min()
-    time_series_max <- dplyr::select(fitted, !!time_series_q) %>% max()
+    series_min <- dplyr::select(fitted, !!series_q) %>% min()
+    series_max <- dplyr::select(fitted, !!series_q) %>% max()
 
-    conditions <- c(conditions, rlang::ll(!!time_series_chr := seq(time_series_min, time_series_max, length.out = series_length)))
+    conditions <- c(conditions, rlang::ll(!!series_chr := seq(series_min, series_max, length.out = series_length)))
 
     diff <- itsadug::get_difference(model, difference, cond = conditions, print.summary = FALSE) %>%
         dplyr::mutate(
@@ -388,7 +434,7 @@ plot_difference <- function(model, time_series, difference, conditions = NULL, s
         )
 
     sig_diff <- itsadug::find_difference(
-        diff$difference, diff$CI, diff[[time_series_chr]]
+        diff$difference, diff$CI, diff[[series_chr]]
     )
 
     annotate <- ggplot2::annotate(
@@ -403,7 +449,7 @@ plot_difference <- function(model, time_series, difference, conditions = NULL, s
     diff_plot <- diff %>%
         ggplot2::ggplot(
             ggplot2::aes_string(
-                rlang::quo_name(time_series_q), "difference"
+                rlang::quo_name(series_q), "difference"
             )
         ) +
         {if (is_sig) {annotate}} +
@@ -416,14 +462,14 @@ plot_difference <- function(model, time_series, difference, conditions = NULL, s
         ) +
         ggplot2::geom_path(
         ) +
-        geom_hline(yintercept = 0)
+        ggplot2::geom_hline(yintercept = 0, alpha = 0.5)
 
     return(diff_plot)
 }
 
 #' Smooths and confidence intervals.
 #'
-#' It provides a `geom` for plotting GAM smooths with confidence intervals from the output of \link[tidymv]{predict_gam}. It inherits the following `aes` from a call to `ggplot`:
+#' It provides a `geom` for plotting GAM smooths with confidence intervals from the output of \link[tidymv]{predict_gam}. It inherits the following aesthetics from a call to \code{ggplot}:
 #'   \itemize{
 #'     \item The term defining the x-axis.
 #'     \item The fitted values (the \code{fit} column in the tibble returned by \link[tidymv]{predict_gam}).

README.md

@@ -1,9 +1,13 @@
-# `tidymv`: Plotting for generalised additive models
+# `tidymv`: Tidy Model Visualisation for Generalised Additive Models
+
+<!-- badges: start -->
+[![Travis build status](https://travis-ci.org/stefanocoretta/tidymv.svg?branch=master)](https://travis-ci.org/stefanocoretta/tidymv)
+<!-- badges: end -->
 
 This is the repository of the `R` package `tidymv`. This package provides functions for the visualisation of GAM(M)s and the generation of model-based predicted values using tidy tools from the `tidyverse`. `tidymv` uses some functions from the `itsadug` package.
 
 ## Installation
 
-To install the package, use `devtools::install_github("stefanocoretta/tidymv@v2.0.0", build_opts = c("--no-resave-data", "--no-manual"))`. To learn how to use the package, check out the vignettes (for example, `vignette("predict-gam", package = "tidymv")`).
+To install the package from GitHub, use `devtools::install_github("stefanocoretta/tidymv@v2.1.0", build_opts = c("--no-resave-data", "--no-manual"))`. To learn how to use the package, check out the vignettes (for example, `vignette("predict-gam", package = "tidymv")`).
 
 If you wish to install the development version, use `devtools::install_github("stefanocoretta/tidymv", build_opts = c("--no-resave-data", "--no-manual"))`.

cran-comments.md

@@ -0,0 +1,20 @@
+## Resubmission
+In this version I have:
+
+* Added 'Provides' and 'package' to the Description field in DESCRIPTION.
+* Added executable examples in all functions.
+
+## Test environments
+* local OS X install, R 3.5.3
+* ubuntu 14.04 (on travis-ci), R 3.5.2
+* win-builder (devel and release)
+
+## R CMD check results
+
+0 errors | 0 warnings | 1 note
+
+* This is a new release.
+
+## Downstream dependencies
+
+There are currently no downstream dependencies for this package.