qfasar (version 1.2.1)

diet_pool: Pool diet estimates to combined prey types

Description

diet_pool pools estimated diets and variance matrices to a smaller number of combined prey types. If est_diet is used to estimate predator diet composition using a partitioned prey library (make_prey_part), diet_pool pools the partitioned results back to the original, unpartitioned prey types.

Usage

diet_pool(rep_grp, est_ind, var_ind = NA, est_mean = NA, var_mean = NA)

Arguments

rep_grp

The post-multiplication matrix returned by a call to make_prey_part as the object pool_post, or a user-defined matrix for custom pooling. Each column defines a prey type to which estimates should be pooled.

est_ind

A numeric matrix of the estimated diet compositions of individual predators using a partitioned prey library, intended to be the object est_ind returned by a call to est_diet.

var_ind

A numeric array containing the estimated variance matrix for the estimated diet of each predator, intended to be the object var_ind returned by a call to est_diet. Optional.

est_mean

A numeric matrix containing the estimated mean diet of each predator type, intended to be the object est_mean returned by a call to est_diet. Optional.

var_mean

A numeric array containing the estimated variance matrix for the estimated mean diet of each predator type, intended to be the object var_mean returned by a call to est_diet. Optional.

Value

A list containing the following elements, all of which are organized on the basis of the original, unpartitioned prey types:

est_ind

A numeric matrix of the estimated diet compositions of individual predators.

var_ind

A numeric array containing the estimated variance matrix for the estimated mean diet of each predator.

est_mean

A numeric matrix containing the estimated mean diet of each predator type.

var_mean

A numeric array containing the estimated variance matrix for the estimated mean diet of each predator type.

err_code

An integer error code (0 if no error is detected).

err_message

A string containing a brief summary of the results.

Details

The function dimac explores the prey library for additional structure with identified prey types. If significant structure is found within a library, estimating diet composition on the basis of a partitioned prey library may lead to estimates with less bias and possibly less variation through reduced prey confounding (Bromaghin et al. 2016). The function make_prey_part takes the clustering results returned by dimac and user specification of the number of clusters in which to partition each prey type and returns a partitioned prey library that is ready for use in diet estimation.

However, when estimating diet composition using a partitioned prey library one may still wish to pool partitioned estimates back to the original, unpartitioned prey types for reporting purposes. That is the purpose of the function diet_pool.

NOTE: diet_pool can also be used to pool estimates into a smaller number of combined prey types for reporting purposes. For example, imagine a prey library with a large number of prey types. If subsets of the prey types have similar ecological function, their signatures may share some similarities (prey confounding, Bromaghin et al. 2016). In such a case, one may wish to estimate diet on the basis of the full prey library, but subsequently pool the resulting estimates to a smaller number of combined prey types for reporting purposes (reporting groups, Bromaghin 2008) to reduce the effect of prey confounding. diet_pool can also be used for this purpose, though the user would need to manually construct the reporting group matrix rep_grp.

References

Bromaghin, J.F. 2008. BELS: Backward elimination locus selection for studies of mixture composition or individual assignment. Molecular Ecology Resources 8:568-571.

Bromaghin, J.F., S.M. Budge, and G.W. Thiemann. 2016. Should fatty acid signature proportions sum to 1 for diet estimation? Ecological Research 31:597-606.

Examples

# NOT RUN {
diet_pool(rep_grp = matrix(c(1, 0, 0, 0, 0, 0, 0,
                             0, 1, 0, 0, 0, 0, 0,
                             0, 1, 0, 0, 0, 0, 0,
                             0, 0, 1, 0, 0, 0, 0,
                             0, 0, 0, 1, 0, 0, 0,
                             0, 0, 0, 1, 0, 0, 0,
                             0, 0, 0, 0, 1, 0, 0,
                             0, 0, 0, 0, 0, 1, 0,
                             0, 0, 0, 0, 0, 1, 0,
                             0, 0, 0, 0, 0, 0, 1),
                           nrow = 10, byrow = TRUE),
         est_ind = matrix(c(0.116, 0.315,
                            0.028, 0.073,
                            0.000, 0.000,
                            0.131, 0.120,
                            0.000, 0.000,
                            0.000, 0.000,
                            0.723, 0.452,
                            0.000, 0.000,
                            0.000, 0.000,
                            0.002, 0.040),
                          nrow = 10, byrow = TRUE))


# }