Added ch2matrix utility

10 files changed, 139 insertions, 12 deletions

diff --git a/.local_checks/@making_IPMbook_package.R b/.local_checks/@making_IPMbook_package.R
index ca531a6..a784fd8 100644
--- a/.local_checks/@making_IPMbook_package.R
+++ b/.local_checks/@making_IPMbook_package.R
@@ -20,7 +20,7 @@ devtools::load_all("D:/Github/IPMbook_package/IPMbook")
 # ==========================
 unlink(list.files(pattern="Rplots.pdf", recursive=TRUE))
 system("R CMD build IPMbook")  # Produces the .tar.gz
-pkg <- "IPMbook_0.1.2.9004.tar.gz"  # <-- fix version number here
+pkg <- "IPMbook_0.1.2.9005.tar.gz"  # <-- fix version number here
 
 # Pick one to check:
 ## on desktop
diff --git a/DESCRIPTION b/DESCRIPTION
index 3382ff2..dd82df4 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,8 +1,8 @@
 Package: IPMbook
 Type: Package
 Title: Functions and Data for the Book 'Integrated Population Models'
-Version: 0.1.2.9004
-Date: 2021-10-01
+Version: 0.1.2.9005
+Date: 2021-10-03
 Depends: R (>= 2.10)
 Imports: stats, abind
 Suggests:
diff --git a/NAMESPACE b/NAMESPACE
index 23e6c79..6b110b4 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -20,4 +20,5 @@ export(
   "simCountBin", "simCountNorm", "simCountPois",
   "marray", "marrayAge", "marrayDead", "createAge",
   "summaryPop",
-  "cleanCH", "zKnown", "zInit", "zInitDR", "rmFirst", "getFirst", "dUnif")
+  "cleanCH", "zKnown", "zInit", "zInitDR", "rmFirst", "getFirst",
+  "dUnif", "ch2matrix")
diff --git a/NEWS b/NEWS
index 9882d28..2b19746 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,7 @@
+CHANGES in version 0.1.2.9005 (2021-10-03)
+
+  * Added `ch2matrix` utility to convert capture histories in text format to matrices.
+
 CHANGES in version 0.1.2.9004 (2021-10-01)
 
   * `marray*` functions now deal correctly with trap losses if only 1 capture.
diff --git a/R/ch2matrix.R b/R/ch2matrix.R
new file mode 100644
index 0000000..d2e3a99
--- /dev/null
+++ b/R/ch2matrix.R
@@ -0,0 +1,47 @@
+
+# Function to convert a capture history recorded as text to a matrix, exported.
+
+# Input: 'ch' could be
+# 1a. a proper CH matrix: numeric, > 1 column -- returned unchanged
+# 1b. the same, as a data frame
+
+# 2a. a character vector with "100110", "001100", etc
+# 2b. the same, as a factor
+# 2c. a numeric vector with 100110, 1100, etc (leading zeros dropped)
+
+# 3a. a 1-column data frame with 2a, b or c.
+# 3b. a 1-column matrix with 2a or 2c.
+
+# Value: a numeric matrix with 1 column per capture occasion and 1 row per capture history
+
+ch2matrix <- function(ch) {
+  if(is.data.frame(ch))
+    ch <- as.matrix(ch)
+  if(is.matrix(ch) && is.numeric(ch) && ncol(ch) > 1)
+    return(ch)
+  if(is.factor(ch))
+    ch <- as.character(ch)
+
+  # Check for matrix with > 1 column -> error
+  if(is.matrix(ch) && ncol(ch) > 1)
+    stop("The format of 'ch' was not recognised.", call. = FALSE)
+
+  ch0 <- as.numeric(ch)
+  if(is.character(ch)) {
+    len <- nchar(ch)
+    if(sum(len - len[1]) !=0)
+      stop("Capture histories must all have the same number of occasions.")
+    ncol <- len[1]
+  } else {
+    ncol <- round(log10(max(ch0))) + 1
+  }
+
+  out <- matrix(NA, length(ch0), ncol)
+  colnames(out) <- paste0("Y", 1:ncol)
+  for(i in 1:ncol) {
+    out[,i] <- ch0 %/% 10^(ncol-i)
+    ch0 <- ch0 %% 10^(ncol-i)
+  }
+
+  return(out)
+}
diff --git a/man/IPMbook-package.Rd b/man/IPMbook-package.Rd
index de2fad3..079167a 100644
--- a/man/IPMbook-package.Rd
+++ b/man/IPMbook-package.Rd
@@ -74,15 +74,16 @@ The functions are listed by chapter below.
 
 \section{UTILITY FUNCTIONS}{
   \describe{
-  \item{\code{\link{getFirst}}}{ Calculates the occasion of first capture from a capture history matrix.}
-  \item{\code{\link{rmFirst}}}{ Removes the records of first capture from a capture history matrix.}
-  \item{\code{\link{zKnown}}}{ Converts a capture history matrix to one with 1 where the animal is know to be alive, NA elsewhere.}
-  \item{\code{\link{zInit}}}{ Converts a capture history matrix to one with 1 after the occasion of first capture, NA elsewhere.}
-  \item{\code{\link{zInitDR}}}{ Converts a dead-recovery capture history matrix to one with 1 after the occasion of first capture until the occasion of dead recovery, then 0; NA elsewhere.}
+  \item{\code{\link{ch2matrix}}}{ Convert capture histories in text format to a matrix.}
   \item{\code{\link{cleanCH}}}{ Removes all-zero rows from a capture history matrix.}
   \item{\code{\link{dbeta2}}}{ Beta distribution with mean and sd.}
   \item{\code{\link{dbeta3}}}{ Beta distribution with mode and concentration.}
   \item{\code{\link{dgamma2}}}{ Gamma distribution with mean and sd.}
+  \item{\code{\link{getFirst}}}{ Calculates the occasion of first capture from a capture history matrix.}
+  \item{\code{\link{rmFirst}}}{ Removes the records of first capture from a capture history matrix.}
+  \item{\code{\link{zInit}}}{ Converts a capture history matrix to one with 1 after the occasion of first capture, NA elsewhere.}
+  \item{\code{\link{zInitDR}}}{ Converts a dead-recovery capture history matrix to one with 1 after the occasion of first capture until the occasion of dead recovery, then 0; NA elsewhere.}
+  \item{\code{\link{zKnown}}}{ Converts a capture history matrix to one with 1 where the animal is know to be alive, NA elsewhere.}
   }
 }
 
diff --git a/man/ch2matrix.Rd b/man/ch2matrix.Rd
new file mode 100644
index 0000000..f6293ba
--- /dev/null
+++ b/man/ch2matrix.Rd
@@ -0,0 +1,61 @@
+\name{ch2matrix}
+\alias{ch2matrix}
+\encoding{UTF-8}
+
+\title{
+Convert capture histories in text format to a matrix
+}
+\description{
+The function takes capture histories in any of the following formats and converts it to a matrix of integers with one column for each capture occasion and one row for each capture history.
+
+Possible formats for \code{ch} are:
+
+1a. a proper CH matrix: numeric, > 1 column -- returned unchanged.\cr
+1b. the same, as a data frame.
+
+2a. a character vector with "100110", "001100", etc, consisting entirely of digits (no letters, spaces, or symbols).\cr
+2b. the same, as a factor.\cr
+2c. a numeric vector with 100110, 1100, etc (leading zeros dropped).
+
+3a. a 1-column data frame with 2a, b or c.\cr
+3b. a 1-column matrix with 2a or 2c.
+}
+\usage{
+ch2matrix(ch)
+}
+\arguments{
+  \item{ch}{
+capture histories in a suitable format, see Description.
+}
+}
+\value{
+A matrix of integers with one column for each capture occasion and one row for each capture history.
+}
+\author{
+Mike Meredith
+}
+
+\examples{
+# Create some example data
+raw <- c("1000", "1000", "1100", "1100", "1100", "1110",
+  "0110", "0110", "0111", "0101", "0010", "0011", "0001")
+
+ch1 <- ch2matrix(raw)                 # character vector
+cbind(raw, ch1)
+ch <- ch2matrix(factor(raw))          # factor
+all(ch == ch1)
+ch <- ch2matrix(as.numeric(raw))      # numeric
+all(ch == ch1)
+ch <- ch2matrix(matrix(raw, ncol=1))  # 1 column matrix
+all(ch == ch1)
+ch <- ch2matrix(data.frame(raw=raw))  # 1 column data frame
+all(ch == ch1)
+
+# Error messages:
+try(ch2matrix(matrix(rep(raw, 2), ncol=2)))     # 2 column matrix -> error
+try(ch2matrix(data.frame(raw=raw, dummy=raw)))  # 2 column data frame -> error
+
+raw[2] <- "11000"          # wrong length
+try(ch2matrix(raw))        # error
+ch2matrix(as.numeric(raw)) # this works, leading zeros not expected.
+}
\ No newline at end of file
diff --git a/man/marray.Rd b/man/marray.Rd
index 36cbef5..c63e25a 100644
--- a/man/marray.Rd
+++ b/man/marray.Rd
@@ -13,7 +13,7 @@ marray(ch, unobs = 0, freq = 1)
 }
 \arguments{
   \item{ch}{
-an individuals x time matrix with single- or multistate capture histories (0: not captured; 1...X: captured in the 1...X states). This can be a matrix of unique capture histories accompanied by a vector or matrix, \code{freq}, specifying the number of animals with each capture history. Trap losses can be indicated either by negative values for \code{freq}, or by filling the row with NA after the last capture.
+an individuals x time matrix with single- or multistate capture histories (0: not captured; 1...X: captured in the 1...X states). See Details.
 }
   \item{unobs}{
 number of unobserved states (default is 0, needs to be given only in specific cases).
@@ -21,8 +21,12 @@ number of unobserved states (default is 0, needs to be given only in specific ca
   \item{freq}{
 a vector with the number of animals with each capture history, or a matrix with a column for each group. If a single value is supplied, it will be used for all rows in the capture history; the default is to assume each row corresponds to a single animal.
 }
+}
 
+\details{
+The argument \code{ch} can be a matrix of unique capture histories accompanied by a vector or matrix, \code{freq}, specifying the number of animals with each capture history. Trap losses can be indicated either by negative values for \code{freq}, or by filling the row with NA after the last capture. For other formats, see \code{\link{ch2matrix}}.
 }
+
 \value{
 For single-state capture recapture data, an m-array which is a (years-1) x years x groups array, where element [i, j, g] contains the number of individuals in group g released in year i and recaptured in year j+1 (by definition no recaptures can occur in year 1). If no groups are specified, this will be a (years-1) x years matrix. The last column contains the number of individuals released in year i and never recaptured.
 
diff --git a/man/marrayAge.Rd b/man/marrayAge.Rd
index 86a449b..03e19c6 100644
--- a/man/marrayAge.Rd
+++ b/man/marrayAge.Rd
@@ -13,7 +13,7 @@ marrayAge(ch, age, mAge = 1, freq = 1)
 }
 \arguments{
   \item{ch}{
-an individuals x time matrix with capture histories (0: not captured; 1: captured). Alternatively, this can be a matrix of unique capture histories accompanied by a vector or matrix, \code{freq}, specifying the number of animals with each combination of capture history and age. Trap losses can be indicated either by negative values for \code{freq}, or by filling the row with NA after the last capture.
+an individuals x time matrix with capture histories (0: not captured; 1: captured). See Details.
 }
   \item{age}{
 vector with the age class at first capture for each individual.
@@ -24,10 +24,14 @@ maximum number of age classes for which m-arrays are constructed; ignored if \co
   \item{freq}{
 a vector with the number of animals with each capture history, or a matrix with a column for each group. If a single value is supplied, it will be used for all rows in the capture history; the default is to assume each row corresponds to a single animal.
 }
+}
 
+\details{
+The argument \code{ch} can be a matrix of unique capture histories accompanied by a vector or matrix, \code{freq}, specifying the number of animals with each capture history. Trap losses can be indicated either by negative values for \code{freq}, or by filling the row with NA after the last capture. For other formats, see \code{\link{ch2matrix}}.
 }
+
 \value{
-A 4-d array, (years-1) x years x age classes x groups, where element [i, j, k, g] contains the number of individuals in group g of age class k released in year i and recaptured in year j+1 (by definition no recaptures can occur in year 1). if no groups are specified, this will be a 3-d array, (years-1) x years x age classes. The last column contains the number of individuals released in year i and never recaptured.
+A 4-d array, (years-1) x years x age classes x groups, where element [i, j, k, g] contains the number of individuals in group g of age class k released in year i and recaptured in year j+1 (by definition no recaptures can occur in year 1). If no groups are specified, this will be a 3-d array, (years-1) x years x age classes. The last column contains the number of individuals released in year i and never recaptured.
 }
 \author{
 Michael Schaub
diff --git a/man/marrayDead.Rd b/man/marrayDead.Rd
index d8c5324..5e85a8b 100644
--- a/man/marrayDead.Rd
+++ b/man/marrayDead.Rd
@@ -19,6 +19,11 @@ an individuals x time matrix with 1 denoting either the time of marking or the t
 a vector with the number of animals with each capture history, or a matrix with a column for each group. If a single value is supplied, it will be used for all rows in the capture history; the default is to assume each row corresponds to a single animal.
 }
 }
+
+\details{
+The argument \code{MR} can be a matrix of unique capture histories accompanied by a vector or matrix, \code{freq}, specifying the number of animals with each capture history. For other formats, see \code{\link{ch2matrix}}.
+}
+
 \value{
 An m-array, a (years-1) x years x groups array, where element [i, j, g] contains the number of individuals in group g marked in year i and recovered in year j+1. The last column contains the number of individuals marked in year i and never recovered. If no groups are specified, this will be a (years-1) x years matrix.
 }