Merge pull request #218 from grunwaldlab/znk-update-branch

Change branch name; rename option

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 Contributing to *poppr*
 =======================
 
-Thank you for taking interest in contributing to *poppr*. All are welcome to participate in any way they feel is appropriate as long as the [community code of conduct](CONDUCT.md) is respected :ok_hand:.
+Thank you for taking interest in contributing to *poppr*. All are welcome to participate in any way they feel is appropriate as long as the [community code of conduct](CONDUCT.md) is respected :+1:.
 
 There are four ways you can contribute to the development of poppr: reporting a bug, fixing documentation errors, contributing new code, or commenting on issues/pull requests. Note that the majority of these activities do not require you to be proficient in R.
 
@@ -94,7 +94,7 @@ You can make changes directly on github by clicking the little pencil icon in th
 
 1. fork poppr to your github account
 2. clone poppr to your desktop 
-3. create a new branch from master and push/sync to your repository
+3. create a new branch from main and push/sync to your repository
 4. make and commit your changes
 5. update the documentation with roxygen
 
@@ -112,4 +112,4 @@ You can use the following checklist for your contributions:
  - [ ] I have documented my changes in the [NEWS](NEWS) file
  - [ ] I have added myself as a contributor to the [DESCRIPTION](DESCRIPTION) file
  - [ ] All the checks on <https://travis-ci.org/grunwaldlab/poppr> pass
-
+

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: poppr
 Type: Package
 Title: Genetic Analysis of Populations with Mixed Reproduction
-Version: 2.8.6
+Version: 2.8.7
 Authors@R: c(person(c("Zhian", "N."), "Kamvar", role = c("cre", "aut"),
     email = "zkamvar@gmail.com", comment = c(ORCID = "0000-0003-1458-7108")),
     person(c("Javier", "F."), "Tabima", role = "aut",

NEWS.md

@@ -1,3 +1,20 @@
+poppr 2.8.7
+==========
+
+DEPRECATION
+-----------
+
+* The argument `blacklist` has been deprecated in favor of `exclude` for the
+  following functions: `bruvo.msn()`, `poppr.msn()`, `clonecorrect()`, `poppr()`, 
+  `mlg.table()`, `mlg.crosspop()`, and `popsub()`. It will be removed in the
+  poppr version 2.9
+
+GITHUB
+------
+
+* The default branch for the repository is now "main", so development versions
+  will install `remotes::install_github("grunwaldlab/poppr@main")`
+
 poppr 2.8.6
 ===========
 

R/Index_calculations.r

@@ -69,9 +69,11 @@
 #'   population names (accessed via \code{\link[adegenet]{popNames}}). 
 #'   Defaults to "ALL".
 #'   
-#' @param blacklist a list of character strings or integers to indicate specific
-#'   populations to be removed from analysis. Defaults to NULL.
-#'   
+#' @param exclude a \code{vector} of population names or indexes that the user
+#' wishes to discard. Default to \code{NULL}.
+#'
+#' @param blacklist DEPRECATED, use exclude.
+#'
 #' @param sample an integer indicating the number of permutations desired to 
 #'   obtain p-values. Sampling will shuffle genotypes at each locus to simulate 
 #'   a panmictic population using the observed genotypes. Calculating the 
@@ -301,7 +303,7 @@
 #' }
 #==============================================================================#
 #' @import adegenet ggplot2 vegan
-poppr <- function(dat, total = TRUE, sublist = "ALL", blacklist = NULL, 
+poppr <- function(dat, total = TRUE, sublist = "ALL", exclude = NULL, blacklist = NULL, 
                   sample = 0, method = 1, missing = "ignore", cutoff = 0.05, 
                   quiet = FALSE, clonecorrect = FALSE, strata = 1, keep = 1, 
                   plot = TRUE, hist = TRUE, index = "rbarD", minsamp = 10, 
@@ -322,6 +324,19 @@ poppr <- function(dat, total = TRUE, sublist = "ALL", blacklist = NULL,
   namelist <- NULL
   hist <- plot
   callpop  <- match.call()
+  if (!is.null(blacklist)) {
+    warning(
+      option_deprecated(
+        callpop, 
+        "blacklist", 
+        "exclude", 
+        "2.8.7.", 
+        "Please use `exclude` in the future"
+       ), 
+      immediate. = TRUE
+    )
+    exclude <- blacklist
+  }
   if (!is.na(grep("system.file", callpop)[1])){
     popsplt <- unlist(strsplit(dat, "/"))
     namelist$File <- popsplt[length(popsplt)]
@@ -336,7 +351,7 @@ poppr <- function(dat, total = TRUE, sublist = "ALL", blacklist = NULL,
     poplist       <- NULL
     poplist$Total <- dat
   } else {
-    dat <- popsub(x$GENIND, sublist = sublist, blacklist = blacklist)
+    dat <- popsub(x$GENIND, sublist = sublist, exclude = exclude)
     if (any(levels(pop(dat)) == "")) {
       levels(pop(dat))[levels(pop(dat)) == ""] <- "?"
       warning("missing population factor replaced with '?'")

R/bruvo.r

@@ -536,7 +536,7 @@ bruvo.boot <- function(pop, replen = 1, add = TRUE, loss = TRUE, sample = 100,
 bruvo.msn <- function (gid, replen = 1, add = TRUE, loss = TRUE, 
                        mlg.compute = "original", 
                        palette = topo.colors,
-                       sublist = "All", blacklist = NULL, vertex.label = "MLG", 
+                       sublist = "All", exclude = NULL, blacklist = NULL, vertex.label = "MLG", 
                        gscale = TRUE, glim = c(0,0.8), gadj = 3, gweight = 1, 
                        wscale = TRUE, showplot = TRUE, 
                        include.ties = FALSE, threshold = NULL, 
@@ -551,6 +551,19 @@ bruvo.msn <- function (gid, replen = 1, add = TRUE, loss = TRUE,
   if (!inherits(gid@mlg, "MLG")){
     gid@mlg <- new("MLG", gid@mlg)
   }
+  if (!is.null(blacklist)) {
+    warning(
+      option_deprecated(
+        match.call(), 
+        "blacklist", 
+        "exclude", 
+        "2.8.7.", 
+        "Please use `exclude` in the future"
+       ), 
+      immediate. = TRUE
+    )
+    exclude <- blacklist
+  }
 
 
 
@@ -572,8 +585,8 @@ bruvo.msn <- function (gid, replen = 1, add = TRUE, loss = TRUE,
 
   gadj <- ifelse(gweight == 1, gadj, -gadj)
 
-  if (toupper(sublist[1]) != "ALL" | !is.null(blacklist)){
-    gid <- popsub(gid, sublist, blacklist)
+  if (toupper(sublist[1]) != "ALL" | !is.null(exclude)){
+    gid <- popsub(gid, sublist, exclude)
   }
 
   # Updating the MLG with filtered data

R/data_subset.r

@@ -211,9 +211,11 @@ clonecorrect <- function(pop, strata = 1, combine = FALSE, keep = 1){
 #' @param sublist a \code{vector} of population names or indexes that the user
 #' wishes to keep. Default to \code{"ALL"}.
 #'
-#' @param blacklist a \code{vector} of population names or indexes that the user
+#' @param exclude a \code{vector} of population names or indexes that the user
 #' wishes to discard. Default to \code{NULL}.
 #'
+#' @param blacklist DEPRECATED, use exclude.
+#'
 #' @param mat a \code{matrix} object produced by \code{\link{mlg.table}} to be
 #' subsetted. If this is present, the subsetted matrix will be returned instead
 #' of the genind object 
@@ -231,26 +233,39 @@ clonecorrect <- function(pop, strata = 1, combine = FALSE, keep = 1){
 #' popNames(microbov)
 #' 
 #' # Analyze only the populations with exactly 50 individuals
-#' mic.50 <- popsub(microbov, sublist=c(1:6, 11:15), blacklist=c(3,4,13,14))
+#' mic.50 <- popsub(microbov, sublist=c(1:6, 11:15), exclude=c(3,4,13,14))
 #'
 #' \dontrun{
 #' # Analyze the first 10 populations, except for "Bazadais"
-#' mic.10 <- popsub(microbov, sublist=1:10, blacklist="Bazadais")
+#' mic.10 <- popsub(microbov, sublist=1:10, exclude="Bazadais")
 #' 
 #' # Take out the two smallest populations
-#' micbig <- popsub(microbov, blacklist=c("NDama", "Montbeliard"))
+#' micbig <- popsub(microbov, exclude=c("NDama", "Montbeliard"))
 #' 
 #' # Analyze the two largest populations
 #' miclrg <- popsub(microbov, sublist=c("BlondeAquitaine", "Charolais"))
 #' }
 #' @export
 #==============================================================================#
 
-popsub <- function(gid, sublist="ALL", blacklist=NULL, mat=NULL, drop=TRUE){
+popsub <- function(gid, sublist="ALL", exclude=NULL, blacklist=NULL, mat=NULL, drop=TRUE){
 
   if (!is.genind(gid) & !is(gid, "genlight")){
     stop("popsub requires a genind or genlight object\n")
   }
+  if (!is.null(blacklist)) {
+    warning(
+      option_deprecated(
+        match.call(), 
+        "blacklist", 
+        "exclude", 
+        "2.8.7.", 
+        "Please use `exclude` in the future"
+       ), 
+      immediate. = TRUE
+    )
+    exclude <- blacklist
+  }
   if (is.null(pop(gid))){
     if (!is.na(sublist[1]) && sublist[1] != "ALL")
       warning("No population structure. Subsetting not taking place.")
@@ -259,7 +274,7 @@ popsub <- function(gid, sublist="ALL", blacklist=NULL, mat=NULL, drop=TRUE){
   orig_list <- sublist 
   popnames  <- popNames(gid)
   if (toupper(sublist[1]) == "ALL"){
-    if (is.null(blacklist)){
+    if (is.null(exclude)){
       return(gid)
     } else {
       # filling the sublist with all of the population names.
@@ -277,25 +292,25 @@ popsub <- function(gid, sublist="ALL", blacklist=NULL, mat=NULL, drop=TRUE){
     }
   }
 
-  # Treating anything present in blacklist.
-  if (!is.null(blacklist)){
+  # Treating anything present in exclude.
+  if (!is.null(exclude)){
 
-    # If both the sublist and blacklist are numeric or character.
-    if (is.numeric(sublist) & is.numeric(blacklist) | class(sublist) == class(blacklist)){
-      sublist <- sublist[!sublist %in% blacklist]
-    } else if (is.numeric(sublist) & class(blacklist) == "character"){
-      # if the sublist is numeric and blacklist is a character. eg s=1:10, b="USA"
-      sublist <- sublist[sublist %in% which(!popnames %in% blacklist)]
+    # If both the sublist and exclude are numeric or character.
+    if (is.numeric(sublist) & is.numeric(exclude) | class(sublist) == class(exclude)){
+      sublist <- sublist[!sublist %in% exclude]
+    } else if (is.numeric(sublist) & class(exclude) == "character"){
+      # if the sublist is numeric and exclude is a character. eg s=1:10, b="USA"
+      sublist <- sublist[sublist %in% which(!popnames %in% exclude)]
     } else {
       # no sublist specified. Ideal situation
       if(all(popnames %in% sublist)){
-        sublist <- sublist[-blacklist]
+        sublist <- sublist[-exclude]
       } else {
         # weird situation where the user will specify a certain sublist, yet
-        # index the blacklist numerically. Interpreted as an index of
+        # index the exclude numerically. Interpreted as an index of
         # populations in the whole data set as opposed to the sublist.
-        warning("Blacklist is numeric. Interpreting blacklist as the index of the population in the total data set.")
-        sublist <- sublist[!sublist %in% popnames[blacklist]]
+        warning("exclude is numeric. Interpreting exclude as the index of the population in the total data set.")
+        sublist <- sublist[!sublist %in% popnames[exclude]]
       }
     }
   }
@@ -315,7 +330,7 @@ popsub <- function(gid, sublist="ALL", blacklist=NULL, mat=NULL, drop=TRUE){
         stop(unmatched_pops_warning(popNames(gid), orig_list))
       } else {
         nothing_warn <- paste("Nothing present in the sublist.\n",
-                            "Perhaps the sublist and blacklist arguments have",
+                            "Perhaps the sublist and exclude arguments have",
                             "duplicate entries?\n",
                             "Subset not taking place.")
         warning(nothing_warn)

R/internal.r

@@ -181,37 +181,37 @@ round.poppr <- Vectorize(function(x){
 # Internal functions utilizing this function:
 # ## none
 #==============================================================================#
-sub_index <- function(pop, sublist="ALL", blacklist=NULL){
+sub_index <- function(pop, sublist="ALL", exclude=NULL){
   numList <- seq(nInd(pop))
   if (is.null(pop(pop))){
     return(numList)
   }
   if(toupper(sublist[1]) == "ALL"){
-    if (is.null(blacklist)){
+    if (is.null(exclude)){
       return(numList)
     } else {
       # filling the sublist with all of the population names.
       sublist <- popNames(pop) 
     }
   }
-  # Treating anything present in blacklist.
-  if (!is.null(blacklist)){
-    # If both the sublist and blacklist are numeric or character.
-    if (is.numeric(sublist) & is.numeric(blacklist) | class(sublist) == class(blacklist)){
-      sublist <- sublist[!sublist %in% blacklist]
-    } else if (is.numeric(sublist) & class(blacklist) == "character"){
-    # if the sublist is numeric and blacklist is a character. eg s=1:10, b="USA"
-      sublist <- sublist[sublist %in% which(!popNames(pop) %in% blacklist)]
+  # Treating anything present in exclude.
+  if (!is.null(exclude)){
+    # If both the sublist and exclude are numeric or character.
+    if (is.numeric(sublist) & is.numeric(exclude) | class(sublist) == class(exclude)){
+      sublist <- sublist[!sublist %in% exclude]
+    } else if (is.numeric(sublist) & class(exclude) == "character"){
+    # if the sublist is numeric and exclude is a character. eg s=1:10, b="USA"
+      sublist <- sublist[sublist %in% which(!popNames(pop) %in% exclude)]
     } else {
       # no sublist specified. Ideal situation
       if(all(popNames(pop) %in% sublist)){
-        sublist <- sublist[-blacklist]
+        sublist <- sublist[-exclude]
       } else {
       # weird situation where the user will specify a certain sublist, yet index
-      # the blacklist numerically. Interpreted as an index of populations in the
+      # the exclude numerically. Interpreted as an index of populations in the
       # whole data set as opposed to the sublist.
-        warning("Blacklist is numeric. Interpreting blacklist as the index of the population in the total data set.")
-        sublist <- sublist[!sublist %in% popNames(pop)[blacklist]]
+        warning("Blacklist is numeric. Interpreting exclude as the index of the population in the total data set.")
+        sublist <- sublist[!sublist %in% popNames(pop)[exclude]]
       }
     }
   }
@@ -224,7 +224,7 @@ sub_index <- function(pop, sublist="ALL", blacklist=NULL){
   }
   sublist <- pop(pop) %in% sublist
   if (sum(sublist) == 0){
-    warning("All items present in Sublist are also present in the Blacklist.\nSubsetting not taking place.")
+    warning("All items present in sublist are also present in exclude.\nSubsetting not taking place.")
     return(seq(nInd(pop)))
   } 
   #cat("Sublist:\n", sublist,"\n")

R/messages.r

@@ -273,3 +273,12 @@ uninformative_loci_message <- function(pop, glocivals, alocivals, locivals,
   msg <- paste("\n", fmsg, "\n", gmsg, "\n", amsg)
   return(msg)
 }
+
+option_deprecated <- function(the_call, option, replacement, version, extra) {
+  names(the_call)[names(the_call) == option] <- replacement
+  CALL <- as.character(deparse(the_call))
+  msg <- paste("the option", option, "is deprecated as of poppr version")
+  msg <- paste(msg, version, extra)
+  msg <- paste(msg, "\n\nPlease use this as a replacement:\n ", CALL, "\n")
+  msg
+}