R/matingRhinos-package.R

In courtiol/matingRhinos: Analysis of the Mating, Reproductive Success and Their Correlates in White Rhinos

#' Analysis of the Mating, Reproductive Success and Their Correlates in White
#' Rhinos
#'
#' This R package aims at providing the data and documenting the R code behind
#' the analysis of the paper entitled 'Mate choice, reproductive success and
#' inbreeding in white rhinos (_Ceratotherium simum_ Burchell, 1817): new insights
#' for conservation management' by Kretzschmar P., Auld H., Boag P., Ganslosser
#' U., Scott C., Van Coeverden de Groot P.J. & Courtiol A. (accepted in
#' Evolutionary Applications).
#' 
#' This package has not been conceived for general use!
#'
#' The main functions of this package contain a small documentation and examples
#' which could be useful for those who try to understand our code. Type
#' \code{ls('package:matingRhinos')} for a list of all (exported) functions and
#' datasets.
#'
#' You may directly explore the files contained in the package on GitHub at
#' \url{https://github.com/courtiol/matingRhinos}, or after uncompressing the
#' content of the *.tar.gz file (link available on the GitHub as well). To 
#' uncompress such a tarball, you can use the R function \code{\link{untar}}.
#'
#' The package contains all the original data.
#'
#' In the examples below, we provide the workflow leading the results presented
#' in the paper.
#'
#' @name matingRhinos-package
#' @aliases matingRhinos-package matingRhinos
#' @docType package
#'
#' @references
#' Kretzschmar P., Auld H., Boag P., Ganslosser U., Scott C.,
#' Van Coeverden de Groot P.J. & Courtiol A.
#' (accepted in Evolutionary Applications)
#' Mate choice, reproductive success and inbreeding in white rhinos
#' (_Ceratotherium simum_ Burchell, 1817): new insights for conservation management.
#' 
#'
#' @keywords package
#' 
#' @examples
#' 
#' 
#' ###############################################
#' ## Setting general options for this workflow ##
#' ###############################################
#'
#' ### Note: set the following options to TRUE or FALSE depending on what you want.
#' options(matingRhinos_PDF = TRUE) # export figures on hard drive as pdf?
#' options(matingRhinos_colours = TRUE) # use colours in figures?
#' 
#'
#' ############################
#' ## Preparing the datasets ##
#' ############################
#' 
#' ### 1. We split the dataset per cohort:
#' malesC1 <- droplevels(males[males$Cohort == 'C1', ])
#' malesC2 <- droplevels(males[males$Cohort == 'C2', ])
#' femalesC1 <- droplevels(females[females$Cohort == 'C1', ])
#' femalesC2 <- droplevels(females[females$Cohort == 'C2', ])
#' 
#' ### 2. Running the Principal Component Analyses (PCA) on horns characteristics:
#' PCA_C1_males <- compute_PCA(data = malesC1)
#' PCA_C2_males <- compute_PCA(data = malesC2)
#' males$Horn <- NA
#' males$Horn[males$Cohort == 'C1'] <- PCA_C1_males$data$PC1
#' malesC1$Horn <- PCA_C1_males$data$PC1
#' males$Horn[males$Cohort == 'C2'] <- PCA_C2_males$data$PC1
#' malesC2$Horn <- PCA_C2_males$data$PC1

#' ### 3. We visuallise the first 6 rows of each dataset:
#' head(males)
#' head(malesC1)
#' head(malesC2)
#' head(females)
#' head(femalesC1)
#' head(femalesC2)
#'
#'
#' ########################
#' ## Parentage analysis ##
#' ########################
#'
#' ### Note: the bioinformatic work leading to parentage has not been done using R.
#' 
#' ### 1. Fatherhood successfully assigned
#' sum(males$Rep_succ) # number assigned for all males
#' round(100*sum(males$Rep_succ)/104, 1) # proportion assigned for all males
#' sum(malesC1$Rep_succ) # number assigned for C1 males
#' round(100*sum(malesC1$Rep_succ)/53, 1) # proportion assigned for C1 males
#' sum(malesC2$Rep_succ) # number assigned for C2 males
#' round(100*sum(malesC2$Rep_succ)/51, 1) # proportion assigned for C2 males
#' fisher.test(matrix(c(sum(malesC1$Rep_succ), 53 - sum(malesC1$Rep_succ),
#'                      sum(malesC2$Rep_succ), 51 - sum(malesC2$Rep_succ)),
#'                      byrow = TRUE,
#'                      nrow = 2))
#' 
#'
#' #####################################
#' ## Mating and reproductive success ##
#' #####################################
#' 
#' ### 1. Computing the skewness tests for males: 
#' test_NonacsB(benef = males$Mat_succ, time = males$Time)
#' test_NonacsB(benef = males$Rep_succ, time = males$Time)
#'
#' ### 2. Creating figure 1:
#' figure_NonacsB(data_males = males, data_females = females_C1C2merged)
#'
#' ### 3. Relationship between mating and reproductive success for males: 
#' compute_correlation(var1 = malesC1$Mat_succ, var2 = malesC1$Rep_succ)
#' compute_Bateman(mating_success = malesC1$Mat_succ, reproductive_success = malesC1$Rep_succ)
#' 
#' compute_correlation(var1 = malesC2$Mat_succ, var2 = malesC2$Rep_succ)
#' compute_Bateman(mating_success = malesC2$Mat_succ, reproductive_success = malesC2$Rep_succ)
#' 
#' ### 4. Creating figure 2:
#' figure_Bateman(data_agg = rhinos_agg)
#'
#' ### 5. Computing the skewness tests for females: 
#' test_NonacsB(benef = females_C1C2merged$Mat_succ, time = females_C1C2merged$Time)
#' test_NonacsB(benef = females_C1C2merged$Rep_succ, time = females_C1C2merged$Time)
#'
#' ### 6. Relationship between mating and reproductive success for females:
#' compute_correlation(var1 = femalesC1$Mat_succ, var2 = femalesC1$Rep_succ)
#' nrow(femalesC1)
#' compute_Bateman(mating_success = femalesC1$Mat_succ, reproductive_success = femalesC1$Rep_succ)
#' 
#' compute_correlation(var1 = femalesC2$Mat_succ, var2 = femalesC2$Rep_succ)
#' nrow(femalesC2)
#' compute_Bateman(mating_success = femalesC2$Mat_succ, reproductive_success = femalesC2$Rep_succ)
#'
#' ### 7. Successful males:
#' malesC1[malesC1$Rep_succ == max(malesC1$Rep_succ), c('No', 'Rep_succ', 'Mat_succ')]
#' range(malesC1$Mat_succ[malesC1$Rep_succ != max(malesC1$Rep_succ)])
#' range(malesC1$Rep_succ[malesC1$Rep_succ != max(malesC1$Rep_succ)])
#' 
#' malesC2[malesC2$Rep_succ == max(malesC2$Rep_succ), c('No', 'Rep_succ', 'Mat_succ')]
#' 
#'
#' ##########################
#' ## Horn characteristics ##
#' ##########################
#' 
#' ### 1. Variance explained:
#' round(100*PCA_C1_males$var_expl[1], 1)
#' round(100*PCA_C2_males$var_expl[1], 1)
#' 
#' ### 2. Creating figure 3:
#' figure_PCA(data = males)
#'
#'
#' ######################
#' ## All correlations ##
#' ######################
#' 
#' ### 1. Computing all the correlation tests
#' compute_correlation_table(cohort = 'C1', fitness = 'Mat_succ', data = males)
#' compute_correlation_table(cohort = 'C1', fitness = 'Rep_succ', data = males)
#' compute_correlation_table(cohort = 'C2', fitness = 'Mat_succ', data = males)
#' compute_correlation_table(cohort = 'C2', fitness = 'Rep_succ', data = males)
#' 
#' ### 2. Creating figures 4 & 5:
#' figure_correlations(data = males)
#' ## note: rerun if bug 'polygon edge not found'; this is a ggplot hiccup.
#' 
#' 
#' #############################################
#' ##  Testosterone metabolites concentration ##
#' #############################################
#' 
#' ### 1. Mean +/- SD:
#' round(mean(malesC1$Testo_mean, na.rm = TRUE), digits = 3L)
#' round(sd(malesC1$Testo_mean, na.rm = TRUE), digits = 3L)
#' round(mean(malesC2$Testo_mean, na.rm = TRUE), digits = 3L)
#' round(sd(malesC2$Testo_mean, na.rm = TRUE), digits = 3L)
#' 
#' ### 2. Creating figure S1:
#' figure_testosterone(data = males)
#' 
#' 
#' ######################
#' ## Male territories ##
#' ######################
#' 
#' ### 1. Computing the range of the territory sizes:
#' rbind(malesC1[which.min(malesC1$Ter_map), c('No', 'Cohort', 'Ter_map')],
#'       malesC1[which.max(malesC1$Ter_map), c('No', 'Cohort', 'Ter_map')])
#' 
#' rbind(malesC2[which.min(malesC2$Ter_map), c('No', 'Cohort', 'Ter_map')],
#'       malesC2[which.max(malesC2$Ter_map), c('No', 'Cohort', 'Ter_map')])
#' 
#' 
#' #################
#' ## Relatedness ##
#' #################
#' 
#' ### 1. Relatedness of the male the most related to females:
#' males[which.max(males$Related_mean), c('No', 'Cohort', 'Related_mean', 'Related_SD')]
#' 
#' ### 2. Comparing mean relatedness of female mates and all candidate females:
#' wilcox.test(males$Related_mean_mated_fem, males$Related_mean, paired = TRUE)
#' wilcox.test(malesC1$Related_mean_mated_fem, malesC1$Related_mean, paired = TRUE)
#' wilcox.test(malesC2$Related_mean_mated_fem, malesC2$Related_mean, paired = TRUE)
#'
#' 
#' ### 3. Creating figure S2:
#' figure_relatedness_simulation(relat_sim)
#' 
#' ### 4. Creating figure S3:
#' figure_relatedness(data = males)
#'
#'
NULL