This function provides an easy way to get count series ready to be analyzed
by the package popbayes. It must be used prior to all other functions.
This function formats the count series (passed through the argument
data) by selecting and renaming columns, checking columns format and
content, and removing missing data (if na_rm = TRUE). It converts the
original data frame into a list of count series that will be analyzed later
by the function fit_trend() to estimate population trends.
To be usable for the estimation of population trends, counts must be
accompanied by information on precision. The population trend model requires
a 95% confident interval (CI).
If estimates are total counts or guesstimates, this function will construct
boundaries of the 95% CI by applying the rules set out in
https://frbcesab.github.io/popbayes/articles/popbayes.html.
If counts were estimated by a sampling method the user needs to specify a
measure of precision. Precision is preferably provided in the form of a 95%
CI by means of two fields: lower_ci and upper_ci. It may also be given
in the form of a standard deviation (sd), a variance (var), or a
coefficient of variation (cv). If the fields lower_ci and upper_ci are
both absent (or NA), fields sd, var, and cv are examined in this
order. When one is found valid (no missing value), a 95% CI is derived
assuming a normal distribution.
The field stat_method must be present in data to indicate
if counts are total counts ('T'), sampling ('S'), or
guesstimate ('X').
If a series mixes aerial and ground counts, a field field_method must
also be present and must contain either 'A' (aerial counts), or 'G'
(ground counts). As all counts must eventually refer to the same field
method for a correct estimation of trend, a conversion will be performed to
homogenize counts. This conversion is based on a preferred field method
and a conversion factor both specific to a species/category.
The preferred field method specifies the conversion direction. The
conversion factor is the multiplicative factor that must be applied to an
aerial count to get an equivalent ground count (note that if the preferred
field method is 'A', ground counts will be divided by the conversion
factor to get the equivalent aerial count).
The argument rmax represents the maximum change in log population size
between two dates (i.e. the relative rate of increase). It will be used
by fit_trend() but must be provided in this function.
These three parameters, named pref_field_method, conversion_A2G, and
rmax can be present in data or in a second data.frame
(passed through the argument info).
Alternatively, the package popbayes provides their values for some
African large mammals.
Note: If the field field_method is absent in data, counts are
assumed to be obtained with one field method.
format_data(
data,
info = NULL,
date = "date",
count = "count",
location = "location",
species = "species",
stat_method = "stat_method",
lower_ci = "lower_ci",
upper_ci = "upper_ci",
sd = NULL,
var = NULL,
cv = NULL,
field_method = NULL,
pref_field_method = NULL,
conversion_A2G = NULL,
rmax = NULL,
path = ".",
na_rm = FALSE
)An n-elements list (where n is the number of count series). The
name of each element of this list is a combination of location and
species. Each element of the list is a list with the following content:
location a character string. The name of the series site.
species a character string. The name of the series species.
date a numerical vector. The sequence of dates of the
series.
n_dates an integer. The number of unique dates.
stat_methods a character vector. The different stat methods
of the series.
field_methods (optional) a character vector. The different
field methods of the series.
pref_field_method (optional) a character string. The
preferred field method of the species ('A' or 'G').
conversion_A2G (optional) a numeric. The conversion factor
of the species used to convert counts to its preferred field method.
rmax a numeric. The maximum population growth rate of the
species.
data_original a data.frame. Original data of the series
with renamed columns. Some rows may have been deleted
(if na_rm = TRUE).
data_converted a data.frame. Data containing computed
boundaries of the 95% CI (lower_ci_conv and upper_ci_conv). If
counts have been obtained by different field methods, contains also
converted counts (count_conv) based on the preferred field method and
conversion factor of the species. This data.frame will be used by the
function fit_trend() to fit population models.
Note: Some original series can be discarded if one of these two conditions is met: 1) the series contains only zero counts, and 2) the series contains only a few dates (< 4 dates).
a data.frame with at least five columns: location,
species, date, count, and stat_method.
The stat_method field indicates the method used to estimate counts. It
can contain: T (total counts), X (guesstimate), and/or S (sampling).
If individual counts were estimated by sampling, additional column(s)
providing a measure of precision is also required (e.g. lower_ci and
upper_ci, or sd, cv, var). Precision metrics can be different
between counts. For instance, some sampling counts can have a sd value
and others lower_ci and upper_ci. In that case three columns are
required (lower_ci, upper_ci, and sd). See above section
Description for further information on the computation of the 95%
confident interval of estimates.
If the individuals were counted by different methods, an additional field
field_method is also required. It can contain: G (ground counts)
and/or A (aerial counts). See above section Description for further
information on the counts conversion.
Others fields can be present either in data or info (see below).
(optional) a data.frame with species in rows and the following
columns: species (species name), pref_field_method,
conversion_A2G, and rmax. See above section Description for
further information on these fields.
Default is NULL (i.e. these information must be present in data
if not available in popbayes).
a character string. The column name in data of the date.
This column date must be in a numerical form with possibly a decimal
part.
Default is 'date'.
a character string. The column name in data of the
number of individuals. This column must be numerical.
Default is 'count'.
a character string. The column name in data of the
site. This field is used to distinguish count series from different sites
(if required) and to create an unique series name.
Default is 'location'.
a character string. The column name in data (and
in info if provided) of the species. This field is used to distinguish
count series for different species (if required) and to create an unique
series name.
Default is 'species'.
a character string. The column name in data of
the method used to estimate individuals counts. It can contain 'T'
(total counts), 'X' (guesstimate), and/or 'S' (sampling). If some
counts are coded as 'S', precision column(s) must also be provided (see
below).
Default is 'stat_method'.
(optional) a character string. The column name in data
of the lower boundary of the 95% CI of the estimate (i.e. count). If
provided, the upper boundary of the 95% CI (argument upper_ci) must be
also provided. This argument is only required if some counts have been
estimated by a sampling method. But user may prefer use other precision
measures, e.g. standard deviation (argument sd), variance (argument
var), or coefficient of variation (argument cv).
Default is 'lower_ci'.
(optional) a character string. The column name in data
of the upper boundary of the 95% CI of the estimate (i.e. count). If
provided, the lower boundary of the 95% CI (argument lower_ci) must be
also provided.
Default is 'upper_ci'.
(optional) a character string. The column name in data of
the standard deviation of the estimate.
Default is NULL.
(optional) a character string. The column name in data of
the variance of the estimate.
Default is NULL.
(optional) a character string. The column name in data of
the coefficient of variation of the estimate.
Default is NULL.
(optional) a character string. The column name in
data of the field method used to count individuals. Counts can be ground
counts (coded as 'G') or aerial counts (coded as 'A'). This argument
is optional if individuals have been counted by the same method. See above
section Description for further information on the count conversion.
Default is NULL.
(optional) a character string. The column name
in data of the preferred field method of the species. This argument is
only required is field_method is not NULL (i.e. individuals have been
counted by different methods). Alternatively, this value can be passed in
info (or internally retrieved if the species is listed in the package).
See above section Description for further information on the count
conversion.
Default is NULL.
(optional) a character string. The column name
in data of the count conversion factor of the species. This argument is
only required if field_method is not NULL (i.e. individuals have been
counted by different methods). Alternatively this value can be passed in
info (or internally retrieved if the species is listed in the package).
See above section Description for further information on the count
conversion.
Default is NULL.
(optional) a character string. The column name in data of
the species demographic potential (i.e. the relative rate of increase of
the population). This is the change in log population size between two
dates and will be used later by fit_trend().
Default is NULL.
a character string. The directory to save formatted data.
This directory must exist and can be an absolute or a relative path.
Default is the current working directory.
a logical. If TRUE, counts with NA values will be
removed.
Default is FALSE (returns an error to inform user if NA are detected).
## Load Garamba raw dataset ----
file_path <- system.file("extdata", "garamba_survey.csv",
package = "popbayes")
garamba <- read.csv(file = file_path)
## Create temporary folder ----
temp_path <- tempdir()
## Format dataset ----
garamba_formatted <- popbayes::format_data(
data = garamba,
path = temp_path,
field_method = "field_method",
pref_field_method = "pref_field_method",
conversion_A2G = "conversion_A2G",
rmax = "rmax")
## Number of count series ----
length(garamba_formatted)
## Retrieve count series names ----
popbayes::list_series(path = temp_path)
## Print content of the first count series ----
names(garamba_formatted[[1]])
## Print original data ----
garamba_formatted[[1]]$"data_original"
## Print converted data ----
garamba_formatted[[1]]$"data_converted"
Run the code above in your browser using DataLab