Using Rcompadre with the tidyverse

Piping with Rcompadre

Let’s say we want to remove all rows where matA contains missing values (NA). We can use cdb_flag() to add a column checking for NA (column “check_NA_A”), and then use filter() to remove those rows. Here are two approaches without piping:

# approach 1 (nested functions)
compadre_use <- filter(cdb_flag(Compadre), check_NA_A == FALSE)

# approach 2 (intermediate step)
compadre_flag <- cdb_flag(Compadre)
compadre_use <- filter(compadre_flag, check_NA_A == FALSE)

and here’s the equivalent piped sequence:

compadre_use <- Compadre %>% 
  cdb_flag() %>%               # first argument is Compadre, from previous line
  subset(check_NA_A == FALSE)  # first argument is output of cdb_flag()

The advantage of piping here is that we don’t have to use nested functions (filter(cdb_flag())), and we don’t have to create object names for every intermediate step in our analysis. An additional alternative is to use subset() instead of filter().

Using mutate with Rcompadre functions that return vectors

A variety of Rcompadre functions take a CompadreDB object as their first argument and return a vector. To use these functions within mutate() in a piped sequence, we generally need to explicitly refer to the object on the left side of the pipe with a dot (".").

Here’s an example with the Rcompadre functions mpm_has_active() and cdb_id_studies(), each of which take a CompadreDB object and return a vector.

compadre_use <- Compadre %>% 
  mutate(has_active = mpm_has_active(.)) %>% 
  filter(has_active == TRUE) %>% 
  mutate(StudyID = cdb_id_studies(.))

In the example above, the pipe passes a CompadreDB object to the first arguments of mutate() and subset(), respectively. The dot for the first argument is implicit. Then, within mutate(), we use the dot again (explicitly this time) to pass the CompadreDB object to mpm_has_active() or cdb_id_studies().

We can also use the dot notation approach to extract components from the CompadreMat objects in the column mat, such as matA, matU, matF, matC, matrixClass, MatrixClassOrganized, or MatrixClassAuthor. Each of these components can be accessed using an accessor function of the same name. Here’s how to extract a list of matU and a list of MatrixClassOrganized from each row of the database, and add these lists to a CompadreDB object as new columns:

compadre_unnest <- Compadre %>% 
  mutate(mat_U = matU(.),
         m_class_organized = MatrixClassOrganized(.))

Vectorizing within mutate with the apply functions

Just like creating a new column with $ (e.g. compadre$new_col <- ...), each expression within mutate() must return a vector of the same length as the number of rows in the data frame, or return a single value which will be recycled for all rows. For some operations this requires vectorization.

Let’s say we want to calculate the population growth rate for every matrix in the database. We can use the eigs() function in the popdemo package, but it can only take a single matrix at a time.

To apply eigs() to a list of matrices we can use sapply(). But first we need to remove matrices with missing values, because these will cause eigs() to fail.

compadre_lambda <- Compadre %>% 
  cdb_flag() %>% 
  filter(check_NA_A == FALSE) %>%      # remove matrices with missing values
  mutate(mat_A = matA(.)) %>%          # extract list-column of matA
  mutate(lam = sapply(mat_A, popdemo::eigs, what = "lambda"))  # get lambda for every matA
#> Warning in FUN(X[[i]], ...): More than one eigenvalues have equal absolute
#> magnitude

In the example above, sapply() returns a scalar value for every row of the database. If we instead want to derive a more complex object for every row such as a vector or matrix, we can use the function lapply() which always returns a list. In the example below we use lapply() to calculate vectors of stage-specific survival (column sums of matU) for every row of the database.

compadre_stage_surv <- Compadre %>% 
  mutate(stage_survival = lapply(matU(.), colSums))

# print vector of stage-specific survival for 20th row
compadre_stage_surv$stage_survival[[20]]
#>    U1    U2    U3    U4    U5    U6 
#> 0.145 0.888 0.788 0.928 0.907 0.999

Vectorizing over multiple arguments

Let’s say we want to know the survival probability for the first ‘active’ stage class (i.e. a stage that’s not dormant or propagule) for every row of the database. One approach is to write our own function that takes matU and the integer index of the first active stage class, and returns the corresponding survival probability, e.g.

SurvFirstActive <- function(matU, first_active) colSums(matU)[first_active]

Notice that this function has two arguments, both of which will vary across rows of the database. We therefore need to vectorize this function over both arguments, which we can do with mapply() (i.e. “multivariate apply”). Here’s an example:

compadre_surv_first_active <- Compadre %>% 
  mutate(surv_1 = mapply(FUN = SurvFirstActive,              # function
                         matU = matU(.),                     # argument 1
                         first_active = mpm_first_active(.)) # argument 2
         )