diff --git a/NAMESPACE b/NAMESPACE index 76d6be6..c9ed1d2 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -32,5 +32,4 @@ importFrom(stats,sd) importFrom(stats,stepfun) importFrom(stats,var) importFrom(utils,capture.output) -importFrom(vegan,betadisper) importFrom(vegan,vegdist) diff --git a/R/utilities.R b/R/utilities.R index cb7fe11..2028d65 100644 --- a/R/utilities.R +++ b/R/utilities.R @@ -1,10 +1,10 @@ -#' Convert from a long form abundance dataframe to a time by species dataframe. -#' -#' @param df A dataframe containing time.var, species.var and abundance.var columns -#' @param time.var The name of the time column from df -#' @param species.var The name of the species column from df -#' @param abundance.var The name of the abundance column from df -#' @return A dataframe of species abundances x time +# Convert from a long form abundance dataframe to a time by species dataframe. +# +# @param df A dataframe containing time.var, species.var and abundance.var columns +# @param time.var The name of the time column from df +# @param species.var The name of the species column from df +# @param abundance.var The name of the abundance column from df +# @return A dataframe of species abundances x time transpose_community <- function(df, time.var, species.var, abundance.var) { @@ -25,22 +25,22 @@ transpose_community <- function(df, time.var, return(comdat) } -#' check names of data frames -#' -#' @param given Vector of variable names as supplied by user -#' @param data Data frame containing variables +# check names of data frames +# +# @param given Vector of variable names as supplied by user +# @param data Data frame containing variables check_names <- function(given, data) { for (i in given) { assertthat::assert_that(assertthat::has_name(data, i)) } } -#' Utility function to warn users that either multiple records exist within -#' replicates, or that data may be spanning multiple replicates but no -#' replicate.var has been specified -#' @param df A dataframe containing time.var, species.var and abundance.var columns -#' @param time.var The name of the time column from df -#' @param species.var The name of the species column from df +# Utility function to warn users that either multiple records exist within +# replicates, or that data may be spanning multiple replicates but no +# replicate.var has been specified +# @param df A dataframe containing time.var, species.var and abundance.var columns +# @param time.var The name of the time column from df +# @param species.var The name of the species column from df check_single_onerep <- function(df, time.var, species.var) { counts <- table(df[[time.var]], df[[species.var]]) if (any(counts > 1)) @@ -49,15 +49,15 @@ check_single_onerep <- function(df, time.var, species.var) { sep = ' ')) } -#' Utility function to ensure only a single record exists for a given species -#' within one replicate if replicate.var given, and for one time point if -#' time.var given. -#' @param df A dataframe containing a species.var column, and optionally a -#' time.var and replicate.var columns -#' @param species.var The name of the species column from df -#' @param time.var The name of the time column from df -#' @param replicate.var The name of the replicate column from df -#' +# Utility function to ensure only a single record exists for a given species +# within one replicate if replicate.var given, and for one time point if +# time.var given. +# @param df A dataframe containing a species.var column, and optionally a +# time.var and replicate.var columns +# @param species.var The name of the species column from df +# @param time.var The name of the time column from df +# @param replicate.var The name of the replicate column from df +# #' @importFrom utils capture.output check_single <- function(df, species.var, @@ -94,21 +94,20 @@ check_single <- function(df, } } -#' Utility to check for numeric abundance and time variables -#' -#' @param df A dataframe containing time.var, species.var, and replicate.var columns -#' @param time.var The name of the time column from df -#' @param abundance.var The name of the replicate column from df - +# Utility to check for numeric abundance and time variables +# +# @param df A dataframe containing time.var, species.var, and replicate.var columns +# @param time.var The name of the time column from df +# @param abundance.var The name of the replicate column from df check_numeric <- function(df, time.var, abundance.var) { if(!is.numeric(df[[time.var]])) { stop("Time variable is not numeric") } if(!is.numeric(df[[abundance.var]])) { stop("Abundance variable is not numeric") } } -#' Utility function to stop calculations if only one species occurs in at least one replicate -#' @param df A dataframe containing time.var, species.var and abundance.var columns -#' @param species.var The name of the species column from df -#' @param replicate.var The name of the replicate column from df +# Utility function to stop calculations if only one species occurs in at least one replicate +# @param df A dataframe containing time.var, species.var and abundance.var columns +# @param species.var The name of the species column from df +# @param replicate.var The name of the replicate column from df check_multispp <- function(df, species.var, replicate.var){ df <- droplevels(df) @@ -120,8 +119,8 @@ check_multispp <- function(df, species.var, replicate.var){ } } -#' Utility function to stop calculations if the species never change in a replicate -#' @param comdat A community dataframe +# Utility function to stop calculations if the species never change in a replicate +# @param comdat A community dataframe #' @importFrom stats var check_sppvar <- function(comdat){ sppvar <- sum(apply(comdat, 2, var)) @@ -129,24 +128,24 @@ check_sppvar <- function(comdat){ stop("One or more replicates consist of species that never vary; please remove these replicates before calculation")} -#' Utility function to calculate richness -#' @param x Vector of abundance of each species +# Utility function to calculate richness +# @param x Vector of abundance of each species S <- function(x){ x <- x[x > 0 & !is.na(x)] stopifnot(x == as.numeric(x)) length(x) } -#' Add zero abundances for missing species, on the assumption that any species -#' in the \code{species.var} column should be included for every group defined -#' by all the remaining columns save \code{abundance.var}. -#' -#' @param df A dataframe with species, abundances, and at least one other column -#' to group by -#' @param species.var The name of the species column from df -#' @param abundance.var The name of the abundance column from df -#' @return A dataframe with the same columns as df, but with zeros added for -#' species that are present in df, but not in a particular group. +# Add zero abundances for missing species, on the assumption that any species +# in the \code{species.var} column should be included for every group defined +# by all the remaining columns save \code{abundance.var}. +# +# @param df A dataframe with species, abundances, and at least one other column +# to group by +# @param species.var The name of the species column from df +# @param abundance.var The name of the abundance column from df +# @return A dataframe with the same columns as df, but with zeros added for +# species that are present in df, but not in a particular group. fill_zeros <- function(df, species.var, abundance.var) { mergevars <- !(names(df) %in% c(species.var, abundance.var)) @@ -157,16 +156,16 @@ fill_zeros <- function(df, species.var, abundance.var) { return(df) } -#' Add missing abundances for species absent from a replicate, on the assumption -#' that any species in the \code{species.var} column should be included for -#' every group defined by all the remaining columns except \code{abundance.var}. -#' -#' @param df A dataframe with species, abundances, and at least one other column -#' to group by -#' @param species.var The name of the species column from df -#' @param abundance.var The name of the abundance column from df -#' @return A dataframe with the same columns as df, but with \code{NA} added for -#' species that are present in df, but not in each group. +# Add missing abundances for species absent from a replicate, on the assumption +# that any species in the \code{species.var} column should be included for +# every group defined by all the remaining columns except \code{abundance.var}. +# +# @param df A dataframe with species, abundances, and at least one other column +# to group by +# @param species.var The name of the species column from df +# @param abundance.var The name of the abundance column from df +# @return A dataframe with the same columns as df, but with \code{NA} added for +# species that are present in df, but not in each group. fill_species <- function(df, species.var, abundance.var) { mergevars <- !(names(df) %in% c(species.var, abundance.var)) @@ -176,22 +175,22 @@ fill_species <- function(df, species.var, abundance.var) { return(df) } -#' @title Add abundance ranks -#' @description Rank species by abundance, by specified grouping. Species with -#' zero abundance receive rank S+1, where S is the total number of species in -#' the group. -#' @param df A data frame containing a single record per species with its abundance -#' @param abundance.var The name of the abundance column -#' -#' @return The add_ranks function returns a data frame with the following -#' additional column: -#' \itemize{ -#' \item{rank: }{A numeric column with the species rank; a rank of 1 -#' indicates the species was most abundant in that time period. All species -#' that are not present in that time period have the rank value S+1 where S -#' is the number of species in the sample. -#' } -#' } +# @title Add abundance ranks +# @description Rank species by abundance, by specified grouping. Species with +# zero abundance receive rank S+1, where S is the total number of species in +# the group. +# @param df A data frame containing a single record per species with its abundance +# @param abundance.var The name of the abundance column +# +# @return The add_ranks function returns a data frame with the following +# additional column: +# \itemize{ +# \item{rank: }{A numeric column with the species rank; a rank of 1 +# indicates the species was most abundant in that time period. All species +# that are not present in that time period have the rank value S+1 where S +# is the number of species in the sample. +# } +# } add_ranks <- function(df, abundance.var) { # get species richness, note that zero abunance does not contribute to S @@ -204,23 +203,23 @@ add_ranks <- function(df, abundance.var) { return(df) } -#' @title Add relative abundance ranks and cumulative abundance -#' @description Rank species by abundance within the specified grouping. The -#' rank of the lead abundant species is 1 and the most abundant species has -#' rank 1/S, where S is the number of species in the group. -#' @param df A data frame containing a single record per species with its abundance -#' @param abundance.var The name of the abundance column -#' @param species.var The name of the species column -#' -#' @return The add_rank_abundance function returns a data frame with the following -#' additional column: -#' \itemize{ -#' \item{rank: }{} -#' \item{relrank: }{A numeric column with the species rank divided -#' by the maximum rank in the group; a rank of 1 indicates the species was the -#' least abundant.} -#' \item{cumabund: }{} -#' } +# @title Add relative abundance ranks and cumulative abundance +# @description Rank species by abundance within the specified grouping. The +# rank of the lead abundant species is 1 and the most abundant species has +# rank 1/S, where S is the number of species in the group. +# @param df A data frame containing a single record per species with its abundance +# @param abundance.var The name of the abundance column +# @param species.var The name of the species column +# +# @return The add_rank_abundance function returns a data frame with the following +# additional column: +# \itemize{ +# \item{rank: }{} +# \item{relrank: }{A numeric column with the species rank divided +# by the maximum rank in the group; a rank of 1 indicates the species was the +# least abundant.} +# \item{cumabund: }{} +# } #' @importFrom stats stepfun add_rank_abundance <- function(df, species.var, abundance.var) { @@ -236,17 +235,17 @@ add_rank_abundance <- function(df, species.var, abundance.var) { return(out) } -#' @title A Split-Apply-Combine implementation -#' @description Faster split-apply-combine for data frames, when the results of FUN -#' are homogeneous with respect to the number, order, data type and (if -#' applicable) levels of columns in the returned data frame. -#' -#' @param df A data frame -#' @param by The name of column(s) in the data frame that define groups to split -#' @param FUN The function applied to each grouped data frame after splitting -#' @param ... Additional parameters to FUN -#' -#' @source \url{https://stackoverflow.com/a/9730292/687112} +# @title A Split-Apply-Combine implementation +# @description Faster split-apply-combine for data frames, when the results of FUN +# are homogeneous with respect to the number, order, data type and (if +# applicable) levels of columns in the returned data frame. +# +# @param df A data frame +# @param by The name of column(s) in the data frame that define groups to split +# @param FUN The function applied to each grouped data frame after splitting +# @param ... Additional parameters to FUN +# +# @source \url{https://stackoverflow.com/a/9730292/687112} split_apply_combine <- function(df, by, FUN, ...) { if (is.null(by)) { # just apply @@ -269,10 +268,10 @@ split_apply_combine <- function(df, by, FUN, ...) { as.data.frame(out) } -#' @title Rank-Abundance Curve Dissimilarity -#' @description A function to calculate the curve difference between two communities, given the empirical relative rank by abundance curve as a \code{stepfun}. -#' @param sf The curve for the first community. -#' @param sf2 The curve for the second community. +# @title Rank-Abundance Curve Dissimilarity +# @description A function to calculate the curve difference between two communities, given the empirical relative rank by abundance curve as a \code{stepfun}. +# @param sf The curve for the first community. +# @param sf2 The curve for the second community. curve_dissim <- function(sf, sf2) { relrank <- get('x', envir = environment(sf)) @@ -284,10 +283,10 @@ curve_dissim <- function(sf, sf2) { return(sum(w*h)) } -#' @title Evar -#' @description A utility function to calculate Evar from Smith and Wilson 1996 -#' @param S the number of species in the sample -#' @param x the vector of abundances of each species +# @title Evar +# @description A utility function to calculate Evar from Smith and Wilson 1996 +# @param S the number of species in the sample +# @param x the vector of abundances of each species Evar <- function(x, S = length(x)) { x1 <- x[x!=0] lnx <- log(x1) @@ -295,20 +294,19 @@ Evar <- function(x, S = length(x)) { return(1 - 2 / pi * atan(theta)) } -#' @title Checking for errors in arguments -#' @description Check for errors in the application of arguments and input data -#' for all \code{*_change} and \code{*_difference} functions. -#' @param df The name of the dataframe -#' @param time.var The name of the optional time column -#' @param species.var The name of the species column -#' @param abundance.var The name of the abundance column -#' @param replicate.var The name of the replicate column -#' @param treatment.var The name of the optional treatment column -#' @param block.var The name of the optional block column -#' @param pool The name the optional pooling approach -#' @param reference.treatment The name of the optional reference treatment -#' @param reference.time The name of the optional reference time - +# @title Checking for errors in arguments +# @description Check for errors in the application of arguments and input data +# for all \code{*_change} and \code{*_difference} functions. +# @param df The name of the dataframe +# @param time.var The name of the optional time column +# @param species.var The name of the species column +# @param abundance.var The name of the abundance column +# @param replicate.var The name of the replicate column +# @param treatment.var The name of the optional treatment column +# @param block.var The name of the optional block column +# @param pool The name the optional pooling approach +# @param reference.treatment The name of the optional reference treatment +# @param reference.time The name of the optional reference time check_args <- function(df, time.var = NULL, species.var, diff --git a/man/Evar.Rd b/man/Evar.Rd deleted file mode 100644 index e1aeb0b..0000000 --- a/man/Evar.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{Evar} -\alias{Evar} -\title{Evar} -\usage{ -Evar(x, S = length(x)) -} -\arguments{ -\item{x}{the vector of abundances of each species} - -\item{S}{the number of species in the sample} -} -\description{ -A utility function to calculate Evar from Smith and Wilson 1996 -} diff --git a/man/RAC_change.Rd b/man/RAC_change.Rd index 8aa7258..cb481d2 100644 --- a/man/RAC_change.Rd +++ b/man/RAC_change.Rd @@ -4,8 +4,8 @@ \alias{RAC_change} \title{Rank Abundance Curve Changes} \usage{ -RAC_change(df, time.var, species.var, abundance.var, replicate.var = NULL, - reference.time = NULL) +RAC_change(df, time.var, species.var, abundance.var, + replicate.var = NULL, reference.time = NULL) } \arguments{ \item{df}{A data frame containing time, species, and abundance columns and an optional columns of replicates.} diff --git a/man/RAC_difference.Rd b/man/RAC_difference.Rd index 84a3ebe..6943488 100644 --- a/man/RAC_difference.Rd +++ b/man/RAC_difference.Rd @@ -4,9 +4,9 @@ \alias{RAC_difference} \title{Rank Abundance Curve Differences} \usage{ -RAC_difference(df, time.var = NULL, species.var, abundance.var, replicate.var, - treatment.var = NULL, pool = FALSE, block.var = NULL, - reference.treatment = NULL) +RAC_difference(df, time.var = NULL, species.var, abundance.var, + replicate.var, treatment.var = NULL, pool = FALSE, + block.var = NULL, reference.treatment = NULL) } \arguments{ \item{df}{A data frame containing a species, abundance, and replicate columns and optional time, treatment, and block columns} diff --git a/man/S.Rd b/man/S.Rd deleted file mode 100644 index e290c24..0000000 --- a/man/S.Rd +++ /dev/null @@ -1,14 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{S} -\alias{S} -\title{Utility function to calculate richness} -\usage{ -S(x) -} -\arguments{ -\item{x}{Vector of abundance of each species} -} -\description{ -Utility function to calculate richness -} diff --git a/man/abundance_difference.Rd b/man/abundance_difference.Rd index 8e2d7ac..8034523 100644 --- a/man/abundance_difference.Rd +++ b/man/abundance_difference.Rd @@ -5,8 +5,8 @@ \title{Abundance Differences} \usage{ abundance_difference(df, time.var = NULL, species.var, abundance.var, - replicate.var, treatment.var = NULL, pool = FALSE, block.var = NULL, - reference.treatment = NULL) + replicate.var, treatment.var = NULL, pool = FALSE, + block.var = NULL, reference.treatment = NULL) } \arguments{ \item{df}{A data frame containing species, abundance, replicate columns and optional time, treatment and block columns.} @@ -77,7 +77,7 @@ abundance_difference(df = df, replicate.var = "plot", time.var = "year", reference.treatment = "N1P0") - + # Pooling by treatment with time df <- subset(pplots, year < 2004) abundance_difference(df = df, diff --git a/man/add_rank_abundance.Rd b/man/add_rank_abundance.Rd deleted file mode 100644 index ca02a60..0000000 --- a/man/add_rank_abundance.Rd +++ /dev/null @@ -1,31 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{add_rank_abundance} -\alias{add_rank_abundance} -\title{Add relative abundance ranks and cumulative abundance} -\usage{ -add_rank_abundance(df, species.var, abundance.var) -} -\arguments{ -\item{df}{A data frame containing a single record per species with its abundance} - -\item{species.var}{The name of the species column} - -\item{abundance.var}{The name of the abundance column} -} -\value{ -The add_rank_abundance function returns a data frame with the following - additional column: - \itemize{ - \item{rank: }{} - \item{relrank: }{A numeric column with the species rank divided - by the maximum rank in the group; a rank of 1 indicates the species was the - least abundant.} - \item{cumabund: }{} - } -} -\description{ -Rank species by abundance within the specified grouping. The - rank of the lead abundant species is 1 and the most abundant species has - rank 1/S, where S is the number of species in the group. -} diff --git a/man/add_ranks.Rd b/man/add_ranks.Rd deleted file mode 100644 index 158d021..0000000 --- a/man/add_ranks.Rd +++ /dev/null @@ -1,29 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{add_ranks} -\alias{add_ranks} -\title{Add abundance ranks} -\usage{ -add_ranks(df, abundance.var) -} -\arguments{ -\item{df}{A data frame containing a single record per species with its abundance} - -\item{abundance.var}{The name of the abundance column} -} -\value{ -The add_ranks function returns a data frame with the following - additional column: - \itemize{ - \item{rank: }{A numeric column with the species rank; a rank of 1 - indicates the species was most abundant in that time period. All species - that are not present in that time period have the rank value S+1 where S - is the number of species in the sample. - } - } -} -\description{ -Rank species by abundance, by specified grouping. Species with - zero abundance receive rank S+1, where S is the total number of species in - the group. -} diff --git a/man/check_args.Rd b/man/check_args.Rd deleted file mode 100644 index 08d2b28..0000000 --- a/man/check_args.Rd +++ /dev/null @@ -1,35 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_args} -\alias{check_args} -\title{Checking for errors in arguments} -\usage{ -check_args(df, time.var = NULL, species.var, abundance.var, - replicate.var = NULL, treatment.var = NULL, pool = FALSE, - block.var = NULL, reference.time = NULL, reference.treatment = NULL) -} -\arguments{ -\item{df}{The name of the dataframe} - -\item{time.var}{The name of the optional time column} - -\item{species.var}{The name of the species column} - -\item{abundance.var}{The name of the abundance column} - -\item{replicate.var}{The name of the replicate column} - -\item{treatment.var}{The name of the optional treatment column} - -\item{pool}{The name the optional pooling approach} - -\item{block.var}{The name of the optional block column} - -\item{reference.time}{The name of the optional reference time} - -\item{reference.treatment}{The name of the optional reference treatment} -} -\description{ -Check for errors in the application of arguments and input data - for all \code{*_change} and \code{*_difference} functions. -} diff --git a/man/check_multispp.Rd b/man/check_multispp.Rd deleted file mode 100644 index d96bc84..0000000 --- a/man/check_multispp.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_multispp} -\alias{check_multispp} -\title{Utility function to stop calculations if only one species occurs in at least one replicate} -\usage{ -check_multispp(df, species.var, replicate.var) -} -\arguments{ -\item{df}{A dataframe containing time.var, species.var and abundance.var columns} - -\item{species.var}{The name of the species column from df} - -\item{replicate.var}{The name of the replicate column from df} -} -\description{ -Utility function to stop calculations if only one species occurs in at least one replicate -} diff --git a/man/check_names.Rd b/man/check_names.Rd deleted file mode 100644 index 92c3d5d..0000000 --- a/man/check_names.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_names} -\alias{check_names} -\title{check names of data frames} -\usage{ -check_names(given, data) -} -\arguments{ -\item{given}{Vector of variable names as supplied by user} - -\item{data}{Data frame containing variables} -} -\description{ -check names of data frames -} diff --git a/man/check_numeric.Rd b/man/check_numeric.Rd deleted file mode 100644 index a30630f..0000000 --- a/man/check_numeric.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_numeric} -\alias{check_numeric} -\title{Utility to check for numeric abundance and time variables} -\usage{ -check_numeric(df, time.var, abundance.var) -} -\arguments{ -\item{df}{A dataframe containing time.var, species.var, and replicate.var columns} - -\item{time.var}{The name of the time column from df} - -\item{abundance.var}{The name of the replicate column from df} -} -\description{ -Utility to check for numeric abundance and time variables -} diff --git a/man/check_single.Rd b/man/check_single.Rd deleted file mode 100644 index db8f690..0000000 --- a/man/check_single.Rd +++ /dev/null @@ -1,25 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_single} -\alias{check_single} -\title{Utility function to ensure only a single record exists for a given species -within one replicate if replicate.var given, and for one time point if -time.var given.} -\usage{ -check_single(df, species.var, time.var = NULL, replicate.var = NULL) -} -\arguments{ -\item{df}{A dataframe containing a species.var column, and optionally a -time.var and replicate.var columns} - -\item{species.var}{The name of the species column from df} - -\item{time.var}{The name of the time column from df} - -\item{replicate.var}{The name of the replicate column from df} -} -\description{ -Utility function to ensure only a single record exists for a given species -within one replicate if replicate.var given, and for one time point if -time.var given. -} diff --git a/man/check_single_onerep.Rd b/man/check_single_onerep.Rd deleted file mode 100644 index 8cb700a..0000000 --- a/man/check_single_onerep.Rd +++ /dev/null @@ -1,22 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_single_onerep} -\alias{check_single_onerep} -\title{Utility function to warn users that either multiple records exist within -replicates, or that data may be spanning multiple replicates but no -replicate.var has been specified} -\usage{ -check_single_onerep(df, time.var, species.var) -} -\arguments{ -\item{df}{A dataframe containing time.var, species.var and abundance.var columns} - -\item{time.var}{The name of the time column from df} - -\item{species.var}{The name of the species column from df} -} -\description{ -Utility function to warn users that either multiple records exist within -replicates, or that data may be spanning multiple replicates but no -replicate.var has been specified -} diff --git a/man/check_sppvar.Rd b/man/check_sppvar.Rd deleted file mode 100644 index 6549332..0000000 --- a/man/check_sppvar.Rd +++ /dev/null @@ -1,14 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{check_sppvar} -\alias{check_sppvar} -\title{Utility function to stop calculations if the species never change in a replicate} -\usage{ -check_sppvar(comdat) -} -\arguments{ -\item{comdat}{A community dataframe} -} -\description{ -Utility function to stop calculations if the species never change in a replicate -} diff --git a/man/curve_change.Rd b/man/curve_change.Rd index aa4f3ce..64bb591 100644 --- a/man/curve_change.Rd +++ b/man/curve_change.Rd @@ -4,8 +4,8 @@ \alias{curve_change} \title{Curve Change} \usage{ -curve_change(df, time.var, species.var, abundance.var, replicate.var = NULL, - reference.time = NULL) +curve_change(df, time.var, species.var, abundance.var, + replicate.var = NULL, reference.time = NULL) } \arguments{ \item{df}{A data frame containing time, species, and abundance columns and an optional column of replicates} diff --git a/man/curve_difference.Rd b/man/curve_difference.Rd index 1b1a47f..7795380 100644 --- a/man/curve_difference.Rd +++ b/man/curve_difference.Rd @@ -5,8 +5,8 @@ \title{Curve Difference} \usage{ curve_difference(df, time.var = NULL, species.var, abundance.var, - replicate.var, treatment.var = NULL, pool = FALSE, block.var = NULL, - reference.treatment = NULL) + replicate.var, treatment.var = NULL, pool = FALSE, + block.var = NULL, reference.treatment = NULL) } \arguments{ \item{df}{A data frame containing a species, abundance, and replicate columns and optional time, treatment, and block columns} @@ -52,7 +52,7 @@ curve_difference(df = df, treatment.var = "treatment", block.var = "block", replicate.var = "plot") - + # With blocks and time df <- subset(pplots, year < 2004 & block < 3) curve_difference(df = df, diff --git a/man/curve_dissim.Rd b/man/curve_dissim.Rd deleted file mode 100644 index bfc4440..0000000 --- a/man/curve_dissim.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{curve_dissim} -\alias{curve_dissim} -\title{Rank-Abundance Curve Dissimilarity} -\usage{ -curve_dissim(sf, sf2) -} -\arguments{ -\item{sf}{The curve for the first community.} - -\item{sf2}{The curve for the second community.} -} -\description{ -A function to calculate the curve difference between two communities, given the empirical relative rank by abundance curve as a \code{stepfun}. -} diff --git a/man/cyclic_shift.Rd b/man/cyclic_shift.Rd index 97c2020..38f4749 100644 --- a/man/cyclic_shift.Rd +++ b/man/cyclic_shift.Rd @@ -5,8 +5,8 @@ \alias{temporal_torus_translation} \title{Cyclic Shift Permutations} \usage{ -cyclic_shift(df, time.var, species.var, abundance.var, replicate.var = NA, - FUN, bootnumber) +cyclic_shift(df, time.var, species.var, abundance.var, + replicate.var = NA, FUN, bootnumber) } \arguments{ \item{df}{A data frame containing time, species and abundance columns and an optional column of replicates} diff --git a/man/cyclic_shift_onerep.Rd b/man/cyclic_shift_onerep.Rd index f83f6b1..951ec41 100644 --- a/man/cyclic_shift_onerep.Rd +++ b/man/cyclic_shift_onerep.Rd @@ -4,7 +4,8 @@ \alias{cyclic_shift_onerep} \title{A function to calculate a non-S3 cyclic shift on one replicate} \usage{ -cyclic_shift_onerep(df, time.var, species.var, abundance.var, FUN, bootnumber) +cyclic_shift_onerep(df, time.var, species.var, abundance.var, FUN, + bootnumber) } \arguments{ \item{df}{A data frame containing time, species and abundance columns and an optional column of replicates} diff --git a/man/fill_species.Rd b/man/fill_species.Rd deleted file mode 100644 index 63edf3d..0000000 --- a/man/fill_species.Rd +++ /dev/null @@ -1,27 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{fill_species} -\alias{fill_species} -\title{Add missing abundances for species absent from a replicate, on the assumption -that any species in the \code{species.var} column should be included for -every group defined by all the remaining columns except \code{abundance.var}.} -\usage{ -fill_species(df, species.var, abundance.var) -} -\arguments{ -\item{df}{A dataframe with species, abundances, and at least one other column -to group by} - -\item{species.var}{The name of the species column from df} - -\item{abundance.var}{The name of the abundance column from df} -} -\value{ -A dataframe with the same columns as df, but with \code{NA} added for - species that are present in df, but not in each group. -} -\description{ -Add missing abundances for species absent from a replicate, on the assumption -that any species in the \code{species.var} column should be included for -every group defined by all the remaining columns except \code{abundance.var}. -} diff --git a/man/fill_zeros.Rd b/man/fill_zeros.Rd deleted file mode 100644 index bb23396..0000000 --- a/man/fill_zeros.Rd +++ /dev/null @@ -1,27 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{fill_zeros} -\alias{fill_zeros} -\title{Add zero abundances for missing species, on the assumption that any species -in the \code{species.var} column should be included for every group defined -by all the remaining columns save \code{abundance.var}.} -\usage{ -fill_zeros(df, species.var, abundance.var) -} -\arguments{ -\item{df}{A dataframe with species, abundances, and at least one other column -to group by} - -\item{species.var}{The name of the species column from df} - -\item{abundance.var}{The name of the abundance column from df} -} -\value{ -A dataframe with the same columns as df, but with zeros added for - species that are present in df, but not in a particular group. -} -\description{ -Add zero abundances for missing species, on the assumption that any species -in the \code{species.var} column should be included for every group defined -by all the remaining columns save \code{abundance.var}. -} diff --git a/man/multivariate_change.Rd b/man/multivariate_change.Rd index 76b2802..dadc2ca 100644 --- a/man/multivariate_change.Rd +++ b/man/multivariate_change.Rd @@ -1,14 +1,16 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/multivariate_change.R +% Please edit documentation in R/multivariate_change_and_difference.R \name{multivariate_change} \alias{multivariate_change} -\title{Using dissimilarity-based metrics to calculate changes in composition and dispersion} +\title{Using dissimilarity-based metrics to calculate changes in composition + and dispersion} \usage{ -multivariate_change(df, time.var, species.var, abundance.var, replicate.var, - treatment.var = NULL, reference.time = NULL) +multivariate_change(df, time.var, species.var, abundance.var, + replicate.var, treatment.var = NULL, reference.time = NULL) } \arguments{ -\item{df}{A data frame containing time, species, abundance and replicate columns and an optional column of treatment} +\item{df}{A data frame containing time, species, abundance and replicate +columns and an optional column of treatment} \item{time.var}{The name of the time column} @@ -16,43 +18,64 @@ multivariate_change(df, time.var, species.var, abundance.var, replicate.var, \item{abundance.var}{The name of the abundance column} -\item{replicate.var}{The name of the replicate column. Replicate must be unique within the dataset and cannot be nested within treatments or blocks.} +\item{replicate.var}{The name of the replicate column. Replicate must be +unique within the dataset and cannot be nested within treatments or blocks.} \item{treatment.var}{the name of the optional treatment column} -\item{reference.time}{The name of the optional time point that all other time points should be compared to (e.g. the first year of data). If not specified, each comparison is between consecutive time points (e.g. first to second year, second to third year, etc.)} +\item{reference.time}{The name of the optional time point that all other time +points should be compared to (e.g. the first year of data). If not +specified, each comparison is between consecutive time points (e.g. first +to second year, second to third year, etc.)} } \value{ The multivariate_change function returns a data frame with the following attributes: \itemize{ - \item{time.var: }{A column with the specified time.var and a second column, with '2' appended to the name. Time is subtracted from time2 for dispersion change.} - \item{composition_change: }{A numeric column that is the euclidean distance between the centroids of two time points.} - \item{dispersion_change: }{A numeric column that is the difference in the average dispersion of the replicates around the centroid for the two time periods. A negative value indicates replicates are converging over time (there is less dispersion at time period 2 than time period 1) and a positive value indicates replicates are diverging over time (there is more dispersion at time period 2 than time period 1.} - \item{treatment.var: }{A column that has same name and type as the treatment.var column, if treatment.var is specified.} + \item{time.var: }{A column with the specified time.var and a second column, + with '2' appended to the name. Time is subtracted from time2 for dispersion + change.} + \item{composition_change: }{A numeric column that is the euclidean distance + between the centroids of two time points.} + \item{dispersion_change: }{A numeric column that is the difference in the + average dispersion of the replicates around the centroid for the two time + periods. A negative value indicates replicates are converging over time + (there is less dispersion at time period 2 than time period 1) and a + positive value indicates replicates are diverging over time (there is more + dispersion at time period 2 than time period 1.} + \item{treatment.var: }{A column that has same name and type as the + treatment.var column, if treatment.var is specified.} } } \description{ -Calculates the changes in composition and dispersion based off a Bray-Curtis dissimilarity matrix. Composition change is the euclidean distance between the centroids of compared time periods and ranges from 0-1, where 0 are identical communities, and 1 and completely different communities. Since composition change is based on plotted distance between centroids, it is context dependent and depends on how many centroids are being plotted, thus result of composition change depends on how many time periods are being measured. Dispersion change is the difference of average dispersion of each replicate to its centroid between time periods. +Calculates the changes in composition and dispersion based off a + Bray-Curtis dissimilarity matrix. Composition change is the euclidean + distance between the centroids of compared time periods and ranges from + 0-1, where 0 are identical communities, and 1 and completely different + communities. Since composition change is based on plotted distance between + centroids, it is context dependent and depends on how many centroids are + being plotted, thus result of composition change depends on how many time + periods are being measured. Dispersion change is the difference of average + dispersion of each replicate to its centroid between time periods. } \examples{ data(pplots) # With treatment multivariate_change(pplots, - time.var="year", - replicate.var = "plot", - treatment.var = "treatment", - species.var = "species", + time.var="year", + replicate.var = "plot", + treatment.var = "treatment", + species.var = "species", abundance.var = "relative_cover") # In each year there are 6 replicates and there are 4 years of data for 3 # time comparisons, thus 24 total observations in each treatment. # With treatment and reference year multivariate_change(pplots, - time.var="year", - replicate.var = "plot", - treatment.var = "treatment", - species.var = "species", + time.var="year", + replicate.var = "plot", + treatment.var = "treatment", + species.var = "species", abundance.var = "relative_cover", reference.time = 2002) # In each year there are 6 replicates and there are 4 years of data for 3 @@ -60,15 +83,15 @@ multivariate_change(pplots, # Without treatment df <- subset(pplots, treatment == "N1P0") -multivariate_change(df, - time.var="year", - replicate.var = "plot", - species.var = "species", +multivariate_change(df, + time.var="year", + replicate.var = "plot", + species.var = "species", abundance.var = "relative_cover") # In each year there are 6 replicates and there are 4 years of data for 3 # time comparisons, thus 24 total observations. } \references{ -Avolio et al. 2015; Avolio et al. Submitted MEE, Mari Anderson et al. 2006. +Avolio et al. 2015; Avolio et al. Submitted MEE, Marti Anderson et al. 2006. } diff --git a/man/multivariate_difference.Rd b/man/multivariate_difference.Rd index c7cf809..7bfca71 100644 --- a/man/multivariate_difference.Rd +++ b/man/multivariate_difference.Rd @@ -1,16 +1,17 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/multivariate_difference.R +% Please edit documentation in R/multivariate_change_and_difference.R \name{multivariate_difference} \alias{multivariate_difference} \title{Using dissimilarity-based metrics to calculate differences in - composition and dispersion between pairs of treatments at a single time - point} + composition and dispersion between pairs of treatments at a single time + point} \usage{ multivariate_difference(df, time.var = NULL, species.var, abundance.var, replicate.var, treatment.var, reference.treatment = NULL) } \arguments{ -\item{df}{A data frame containing an optional time column, species, abundance and replicate, and treatment columns} +\item{df}{A data frame containing an optional time column, species, abundance +and replicate, and treatment columns} \item{time.var}{The name of the optional time column} @@ -18,57 +19,75 @@ multivariate_difference(df, time.var = NULL, species.var, abundance.var, \item{abundance.var}{The name of the abundance column} -\item{replicate.var}{The name of the replicate column. Replicate must be unique within the dataset and cannot be nested within treatments or blocks.} +\item{replicate.var}{The name of the replicate column. Replicate must be +unique within the dataset and cannot be nested within treatments or blocks.} \item{treatment.var}{the name of the treatment column} -\item{reference.treatment}{The name of the optional treatment that all other treatments will be compared to (e.g. only controls will be compared to all other treatments). If not specified all pairwise treatment comparisons will be made.} +\item{reference.treatment}{The name of the optional treatment that all other +treatments will be compared to (e.g. only controls will be compared to all +other treatments). If not specified all pairwise treatment comparisons will +be made.} } \value{ The multivariate_difference function returns a data frame with the following attributes: \itemize{ - \item{treatment.var: }{A column that has same name and type as the treatment.var column, if treatment.var is specified.} - \item{treatment.var2: }{A column that has the same type as the treatment.var column, and is named treatment.var with a 2 appended to it.} - \item{composition_diff: }{A numeric column that is the euclidean distance between the centroids of two treatments at a single point in time.} - \item{abs_dispersion_diff: }{A numeric column that is the absolute value of the difference in the average dispersion of the replicates around the centroid for the two treatments.} - \item{trt_greater_disp: }{A column that has same type as the treatment.var column, and specifies which of the two treatments has greater dispersion.} - \item{time.var: }{A characteristic column that has the same name and type as the time.var column, if specified.} + \item{treatment.var: }{A column that has same name and type as the + treatment.var column, if treatment.var is specified.} + \item{treatment.var2: }{A column that has the same type as the treatment.var + column, and is named treatment.var with a 2 appended to it.} + \item{composition_diff: }{A numeric column that is the euclidean distance + between the centroids of two treatments at a single point in time.} + \item{abs_dispersion_diff: }{A numeric column that is the absolute value of + the difference in the average dispersion of the replicates around the + centroid for the two treatments.} + \item{trt_greater_disp: }{A column that has same type as the treatment.var + column, and specifies which of the two treatments has greater dispersion.} + \item{time.var: }{A characteristic column that has the same name and type as + the time.var column, if specified.} } } \description{ -Calculates the difference in composition and dispersion between treatments based off a Bray-Curtis dissimilarity matrix at a single point in time. Composition difference is the euclidean distance between the centroids of different treatments. Since centroid distance is based on plotted distance between centroids, it is context dependent and depends on how many centroids are being plotted. The centroid distance between treatments depends on how many treatments are being compared. Dispersion difference is the difference of average dispersion of each replicate to its centroid between two treatments. +Calculates the difference in composition and dispersion between + treatments based off a Bray-Curtis dissimilarity matrix at a single point + in time. Composition difference is the euclidean distance between the + centroids of different treatments. Since centroid distance is based on + plotted distance between centroids, it is context dependent and depends on + how many centroids are being plotted. The centroid distance between + treatments depends on how many treatments are being compared. Dispersion + difference is the difference of average dispersion of each replicate to its + centroid between two treatments. } \examples{ - data(pplots) # Without time df <- subset(pplots, year == 2002) -multivariate_difference(df, - replicate.var = "plot", - treatment.var = "treatment", - species.var = "species", +multivariate_difference(df, + replicate.var = "plot", + treatment.var = "treatment", + species.var = "species", abundance.var = "relative_cover") # There are 6 replicates for each of three treatments, thus 18 total # observations. # Without time and with reference treatment df <- subset(pplots, year == 2002) -multivariate_difference(df, - replicate.var = "plot", - treatment.var = "treatment", - species.var = "species", +multivariate_difference(df, + replicate.var = "plot", + treatment.var = "treatment", + species.var = "species", abundance.var = "relative_cover", reference.treatment = "N1P0") # There are 6 replicates for each of three treatments, thus 18 total # observations. # With time -multivariate_difference(pplots, - time.var = "year", - replicate.var = "plot", - species.var = "species", - abundance.var = "relative_cover", +multivariate_difference(pplots, + time.var = "year", + replicate.var = "plot", + species.var = "species", + abundance.var = "relative_cover", treatment.var = "treatment") # In each year there are 6 replicates for each of three treatments, for a # total of 18 observations. diff --git a/man/split_apply_combine.Rd b/man/split_apply_combine.Rd deleted file mode 100644 index fcd84d0..0000000 --- a/man/split_apply_combine.Rd +++ /dev/null @@ -1,25 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{split_apply_combine} -\alias{split_apply_combine} -\title{A Split-Apply-Combine implementation} -\source{ -\url{https://stackoverflow.com/a/9730292/687112} -} -\usage{ -split_apply_combine(df, by, FUN, ...) -} -\arguments{ -\item{df}{A data frame} - -\item{by}{The name of column(s) in the data frame that define groups to split} - -\item{FUN}{The function applied to each grouped data frame after splitting} - -\item{...}{Additional parameters to FUN} -} -\description{ -Faster split-apply-combine for data frames, when the results of FUN -are homogeneous with respect to the number, order, data type and (if -applicable) levels of columns in the returned data frame. -} diff --git a/man/transpose_community.Rd b/man/transpose_community.Rd deleted file mode 100644 index fad66ab..0000000 --- a/man/transpose_community.Rd +++ /dev/null @@ -1,23 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utilities.R -\name{transpose_community} -\alias{transpose_community} -\title{Convert from a long form abundance dataframe to a time by species dataframe.} -\usage{ -transpose_community(df, time.var, species.var, abundance.var) -} -\arguments{ -\item{df}{A dataframe containing time.var, species.var and abundance.var columns} - -\item{time.var}{The name of the time column from df} - -\item{species.var}{The name of the species column from df} - -\item{abundance.var}{The name of the abundance column from df} -} -\value{ -A dataframe of species abundances x time -} -\description{ -Convert from a long form abundance dataframe to a time by species dataframe. -} diff --git a/man/turnover_twoyears.Rd b/man/turnover_twoyears.Rd index d286230..8778de3 100644 --- a/man/turnover_twoyears.Rd +++ b/man/turnover_twoyears.Rd @@ -4,8 +4,8 @@ \alias{turnover_twoyears} \title{A function to calculate species turnover between two years} \usage{ -turnover_twoyears(d1, d2, species.var, metric = c("total", "disappearance", - "appearance")) +turnover_twoyears(d1, d2, species.var, metric = c("total", + "disappearance", "appearance")) } \arguments{ \item{d1}{A dataframe containing a species column from one year} diff --git a/man/variance_ratio.Rd b/man/variance_ratio.Rd index 54e984e..a97558c 100644 --- a/man/variance_ratio.Rd +++ b/man/variance_ratio.Rd @@ -5,7 +5,8 @@ \title{Variance Ratio} \usage{ variance_ratio(df, time.var, species.var, abundance.var, bootnumber, - replicate.var = NA, average.replicates = TRUE, level = 0.95, li, ui) + replicate.var = NA, average.replicates = TRUE, level = 0.95, li, + ui) } \arguments{ \item{df}{A data frame containing time, species and abundance columns and an optional column of replicates}