Get started

The goal of the R package popbayes is to fit population trajectories over time from counts of individuals collected at various dates and with a variety of methods. It does so under a Bayesian framework where the primary quantity being modeled is the rate of increase between successive years (or any other time units for that matter, the one used for date). The package can deal with multiple species and multiple locations presented in a single data set, but each count series made of the counts relative to one species at one location will be processed independently.

The strength of popbayes is to handle, in a single series, counts collected under different types of surveys (aerial vs ground surveys), and estimated by different census methods (total counts, sampling counts, and even guesstimates [i.e. expert estimates]).

Before using this package, users need to install the freeware JAGS.

The workflow of popbayes consists in three main steps:

Formatting data (format_data())
Fitting trends (fit_trend())
Visualizing results (plot_trend())

The package also provides a lot of functions to handle individual count series and model outputs. The following figure shows a more complete usage of the package.

Framework of popbayes

The Garamba dataset

The package popbayes comes with an example dataset: garamba. It contains counts of individuals from 10 African mammal species surveyed in the Garamba National Park (Democratic Republic of the Congo) from 1976 to 2017.

## Define filename path ----
file_path <- system.file("extdata", "garamba_survey.csv", package = "popbayes")

## Read CSV file ----
garamba <- read.csv(file = file_path)

The Garamba dataset (first 20 rows)
location	species	date	stat_method	field_method	count	lower_ci	upper_ci	pref_field_method	conversion_A2G	rmax
Garamba	Alcelaphus buselaphus	1976	S	A	7750	6280	9220	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1983	S	A	1932	1120	2744	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1984	S	A	1224	782	1666	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1986	S	A	1705	1116	2294	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1991	S	A	987	663	1311	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1993	S	A	3444	1290	5598	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1995	S	A	2819	1620	4018	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	1998	S	A	1685	1287	2083	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2000	S	A	1169	945	1393	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2002	S	A	1139	907	1371	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2003	S	A	1595	1142	2048	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2004	S	A	1204	811	1597	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2012	T	A	552	NA	NA	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2014	T	A	698	NA	NA	G	2.302	0.2748
Garamba	Alcelaphus buselaphus	2017	T	A	1051	NA	NA	G	2.302	0.2748
Garamba	Giraffa camelopardalis	1976	S	A	350	100	600	A	3.011	0.1750
Garamba	Giraffa camelopardalis	1983	S	A	175	12	338	A	3.011	0.1750
Garamba	Giraffa camelopardalis	1984	S	A	237	93	381	A	3.011	0.1750
Garamba	Giraffa camelopardalis	1986	S	A	153	13	293	A	3.011	0.1750
Garamba	Giraffa camelopardalis	1991	S	A	346	143	549	A	3.011	0.1750

This dataset has a typical structure with a location field (location), a species name field (species), a date field (date), and a count field (count).

Statistical method

In addition to the fields location, species, date, and count, a fourth field is mandatory: stat_method. This field specifies the census method that produced the count. It can be T for a total count, X for a guesstimate (i.e. expert estimate), or S for a sampling count.

To be usable by the Bayesian model, individual counts are to be accompanied by information on precision in the form of a 95% confidence interval. If counts are :

T or X, a confidence interval will be computed automatically by the function format_data() according respectively to the following formulas:

CI_(T) = [ 0.95 × count ; 1.20 × count ] CI_(X) = [ 0.80 × count ; 1.20 × count ]

S, users need to supply 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 (as in the garamba dataset). Alternatively, it may also be given in the form of a standard deviation (sd), a variance (var), or a coefficient of variation (cv). Note that precision metrics can be different between counts. For instance, some S counts may have an sd value and others lower_ci and upper_ci. In that case, three precision columns would be required (lower_ci, upper_ci, and sd). An S count with no measure of precision will be detected as an anomaly by format_data() by default. The option na.rm = TRUE may be used to automatically remove such counts from the series. If it is desirable to maintain such counts in the count series, we suggest to enter a value for the coefficient of variation, e.g. the average coefficient of variation of the other counts in the series.

Field method

Another optional column, field_method, may be provided. It refers to the type of survey used to collect data. This can be A for aerial survey or G for ground survey. This column becomes mandatory as soon as both field methods are present in a series.

The detectability of a species is indeed strongly dependent on the survey method and each species has its own preferred field method, the one that is assumed to provide estimates closer to the truth. So, even if a series is homogeneous relative to the field method, it is recommended to provide the column field_method if counts have been collected under the not preferred field method. That will force conversion towards the preferred field method.

Count conversion

The function format_data() will convert counts (and 95% CI bounds) into their equivalent in the preferred field method for the species. To this aim, two pieces of information are required :

pref_field_method: the preferred field method for the species (A or G);
conversion_A2G: the multiplicative factor used to convert an aerial count into an equivalent ground count.

The package popbayes provides the species_info dataset, which contains these two pieces of information for 15 African mammal species.

data("species_info")

Species with count conversion information in popbayes
species	category	pref_field_method	conversion_A2G	rmax
Aepyceros melampus	MLB	G	6.747	0.4010
Alcelaphus buselaphus	LLB	G	2.302	0.2748
Connochaetes taurinus	LLB	G	2.302	0.2679
Damaliscus lunatus	MLB	G	6.747	0.2990
Eudorcas rufifrons	MLB	G	6.747	0.5270
Giraffa camelopardalis	Giraffe	A	3.011	0.1750
Hippotragus equinus	LLB	G	2.302	0.2420
Kobus ellipsiprymnus	MLB	G	6.747	0.2702
Kobus kob	MLB	G	6.747	0.3802
Loxodonta africana	Elephant	A	0.659	0.1120
Ourebia ourebi	MLB	G	6.747	0.5988
Redunca redunca	MLB	G	6.747	0.4010
Syncerus caffer	LD	A	0.561	0.2080
Tragelaphus derbianus	LLB	G	2.302	0.1500
Tragelaphus scriptus	MLB	G	6.747	0.4487

If users work only with species in this table, the package popbayes can automatically retrieve the values of pref_field_method and conversion_A2G from the species_info data set. But for other species, users need to supply the information themselves when running format_data(). These values may be provided as additional fields in the count data set. Care must then be taken that the same value is consistently repeated for each count of the same species. For users with sufficient command of R, we recommend rather to create an independent additional table similar to species_info and to pass it to the function format_data() as the data frame argument info.

Note: Currently format_data() takes its information for count conversion from one source only with priority given to info, then to additional fields in data (if info is not provided), and eventually to the species_info table of the package (when the other two sources are lacking). That means that the source with the highest priority must be complete with respect to the species present in data, as it will be used exclusively to any other source. If, say, you use info, you cannot expect format_data() to retrieve conversion information for a species undocumented in info from the species_info table of the package. However, you can easily construct info from a copy of species_info, which additionally provides a ready template. It suffices to add any species not already in species_info as shown below.

Let’s assume that, in addition to other species present in the package species_info table, we have counts of Taurotragus oryx and Taurotragus derbianus. We can construct info as follows.

## Extract the relevant columns of the package table "species_info" ----
info_from_package <- species_info[ , c("species", "pref_field_method", "conversion_A2G", "rmax")]

## Add the new species ----
new_conversion_info <- data.frame("species"           = c("Taurotragus oryx","Taurotragus derbianus"),
                                  "pref_field_method" = "G",
                                  "conversion_A2G"    = 2.302,
                                  "rmax"              = 0.1500)

## Append the new species ----
info <- rbind(info_from_package, new_conversion_info)
info
#>                   species pref_field_method conversion_A2G   rmax
#> 1      Aepyceros melampus                 G          6.747 0.4010
#> 2   Alcelaphus buselaphus                 G          2.302 0.2748
#> 3   Connochaetes taurinus                 G          2.302 0.2679
#> 4      Damaliscus lunatus                 G          6.747 0.2990
#> 5      Eudorcas rufifrons                 G          6.747 0.5270
#> 6  Giraffa camelopardalis                 A          3.011 0.1750
#> 7     Hippotragus equinus                 G          2.302 0.2420
#> 8    Kobus ellipsiprymnus                 G          6.747 0.2702
#> 9               Kobus kob                 G          6.747 0.3802
#> 10     Loxodonta africana                 A          0.659 0.1120
#> 11         Ourebia ourebi                 G          6.747 0.5988
#> 12        Redunca redunca                 G          6.747 0.4010
#> 13        Syncerus caffer                 A          0.561 0.2080
#> 14  Tragelaphus derbianus                 G          2.302 0.1500
#> 15   Tragelaphus scriptus                 G          6.747 0.4487
#> 16       Taurotragus oryx                 G          2.302 0.1500
#> 17  Taurotragus derbianus                 G          2.302 0.1500

If you do not have conversion information of your own for a new species, you can rely on the conversion information of species with similar characteristics (for example the two Taurotragus species belong to the category LLB). The package popbayes distinguishes five categories of species:

MLB: Medium-sized Light and Brown species (20-150kg)
LLB: Large Light and Brown species (>150kg)
LD: Large Dark (>150kg)
Elephant
Giraffe

The field category of the species_info table indicates which species belong to each.

Relative rate of increase

The demographic potential of a species is limited. The intrinsic rate of increase (called rmax) is the maximum increase in log population size that a species can attain in a year.

We strongly recommend using the rmax values while estimating population trend to limit yearly population growth estimated by the model (the default).

As for pref_field_method and conversion_A2G, rmax values (specific to a species) can be provided in an additional field of the count dataset (garamba), as additional field of the info data frame, or internally can be retrieved from the internal dataset of popbayes.

How to find the species rmax value?

According to Sinclair (2003), rmax is related to the body mass of adult females W by the formula:

rmax = 1.375 × W^−0.315

Body masses are found in the literature in publications such as Kingdon & Hoffman (2013), Cornelis et al. (2014), Illius & Gordon (1992), Sinclair (1996), Suraud et al. (2012), or Foley & Faust (2010).

If you know the body mass of adult females of the species, you can compute the rmax value with the function w_to_rmax().

Alternatively, rmax can be obtained from previous demographic analyses.

Important note: The intrinsic rate of increase refers to a change over one year. If a different time unit is used for the dates (say a month), the rmax to provide must be adapted (here divided by 12). The rmax values in popbayes cannot be used for time units other than one year.

Checking data

The first thing that the function format_data() does is to check the validity of the content of the different fields of the count data set. Here we will explore our data to avoid errors when using the function format_data().

In particular, we need to check location and species spelling, date and count field format, and the stat_method and field_method categories.

Check location field

unique(garamba$"location")
#> [1] "Garamba"

sum(is.na(garamba$"location"))   # Are there any missing values?
#> [1] 0

Field location can be either a character or a factor. It cannot contain any NA values.

Check species field

unique(garamba$"species")
#>  [1] "Alcelaphus buselaphus"  "Giraffa camelopardalis" "Hippotragus equinus"   
#>  [4] "Kobus ellipsiprymnus"   "Kobus kob"              "Loxodonta africana"    
#>  [7] "Ourebia ourebi"         "Redunca redunca"        "Syncerus caffer"       
#> [10] "Tragelaphus scriptus"

sum(is.na(garamba$"species"))   # Are there any missing values?
#> [1] 0

## Are there species absent from the 'species_info' popbayes dataset?
garamba_species <- unique(garamba$"species")
garamba_species[which(!(garamba_species %in% species_info$"species"))]
#> character(0)

Field species can be either a character or a factor. It cannot contain any NA values.

Check date field

is.numeric(garamba$"date")     # Are dates in a numerical format?
#> [1] TRUE

sum(is.na(garamba$"date"))     # Are there any missing values?
#> [1] 0

range(garamba$"date")          # What is the temporal extent?
#> [1] 1976 2017

Field date must be a numeric. It cannot contain any NA values. This said, the time unit is arbitrary, and fractional values of years (or another unit) are allowed. As long as numeric values are entered, the package will work.

On the other hand, if you have a date format (e.g. ‘2021/05/19’), you need to convert it to a numeric format. For instance:

## Convert a character to a date object ----
x <- as.Date("2021/05/19")
x
#> [1] "2021-05-19"

## Convert a date to a numeric (number of days since 1970/01/01) ----
x <- as.numeric(x)
x
#> [1] 18766

## Check ----
as.Date(x, origin = as.Date("1970/01/01"))
#> [1] "2021-05-19"

Other methods exist to convert a date to a numeric format. You may prefer computing the number of days since the first date of your survey. It’s up to you.

Check count field

is.numeric(garamba$"count")   # Are counts in a numerical format?
#> [1] TRUE

range(garamba$"count")        # What is the range of values?
#> [1]     0 53312

sum(is.na(garamba$"count"))   # Are there any missing values?
#> [1] 0

Field count must be a positive numeric (zero counts are allowed). NA counts cannot be used for fitting trends. The format_data() function (see below) has an option for dropping them.

Check stat_method field

unique(garamba$"stat_method")
#> [1] "S" "T"

sum(is.na(garamba$"stat_method"))   # Are there any missing values?
#> [1] 0

Field stat_method can be either a character or a factor. It must contain only T, X, or S categories and cannot contain any NA values.

Check field_method field

unique(garamba$"field_method")
#> [1] "A"

sum(is.na(garamba$"field_method"))   # Are there any missing values?
#> [1] 0

Field field_method can be either a character or a factor. It must contain only A, or G categories and cannot contain any NA values.

Formatting data

This first popbayes function to use is format_data(). This function provides an easy way to get individual count series ready to be analyzed by the package. It must be used prior to all other functions.

First let’s define the path (relative or absolute) to save objects/results, namely the formatted count series that can be extracted from the data set.

path <- "the_folder_to_store_outputs"

The function format_data() has many arguments to provide the names of the columns in the user’s dataset that contain location, species, lower_ci, etc. By default column names are the same as in the Garamba dataset. If your location field, say, is “site”, you’ll need to use the argument location as follows: location = "site".

garamba_formatted <- popbayes::format_data(data              = garamba, 
                                           path              = path,
                                           field_method      = "field_method",
                                           pref_field_method = "pref_field_method",
                                           conversion_A2G    = "conversion_A2G",
                                           rmax              = "rmax")
#> ✔ Detecting 10 count series

As said above, if you have to add your own count conversion data, you need specify the names of columns for the preferred field method, the conversion factor, and rmax as this: pref_field_method = "column_with_preferred_field_method", conversion_A2G = "column_with_conversion_A2Gor", rmax = "column_with_conversion_rmax", or alternatively use the argument info: info = "dataframe_with_conversion_info".

Let’s explore the output.

## Class of the object ----
class(garamba_formatted)
#> [1] "list"

## Number of elements (i.e. number of count series) ----
length(garamba_formatted)
#> [1] 10

## Get series names ----
popbayes::list_series(path)
#>  [1] "garamba__alcelaphus_buselaphus"  "garamba__giraffa_camelopardalis"
#>  [3] "garamba__hippotragus_equinus"    "garamba__kobus_ellipsiprymnus"  
#>  [5] "garamba__kobus_kob"              "garamba__loxodonta_africana"    
#>  [7] "garamba__ourebia_ourebi"         "garamba__redunca_redunca"       
#>  [9] "garamba__syncerus_caffer"        "garamba__tragelaphus_scriptus"

Let’s work with the count series "garamba__alcelaphus_buselaphus". We can use the function filter_series().

## Retrieve series by species and location ----
a_buselaphus <- popbayes::filter_series(data     = garamba_formatted, 
                                        species  = "Alcelaphus buselaphus",
                                        location = "Garamba")
#> ✔ Found 1 series with 'Alcelaphus buselaphus' and 'Garamba'.

Let’s display the series content.

print(a_buselaphus)
#> $garamba__alcelaphus_buselaphus
#> $garamba__alcelaphus_buselaphus$location
#> [1] "Garamba"
#> 
#> $garamba__alcelaphus_buselaphus$species
#> [1] "Alcelaphus buselaphus"
#> 
#> $garamba__alcelaphus_buselaphus$dates
#>  [1] 1976 1983 1984 1986 1991 1993 1995 1998 2000 2002 2003 2004 2012 2014 2017
#> 
#> $garamba__alcelaphus_buselaphus$n_dates
#> [1] 15
#> 
#> $garamba__alcelaphus_buselaphus$stat_methods
#> [1] "S" "T"
#> 
#> $garamba__alcelaphus_buselaphus$field_methods
#> [1] "A"
#> 
#> $garamba__alcelaphus_buselaphus$pref_field_method
#> [1] "G"
#> 
#> $garamba__alcelaphus_buselaphus$conversion_A2G
#> [1] 2.302
#> 
#> $garamba__alcelaphus_buselaphus$rmax
#> [1] 0.2748
#> 
#> $garamba__alcelaphus_buselaphus$data_original
#>    location               species date stat_method field_method
#> 1   Garamba Alcelaphus buselaphus 1976           S            A
#> 2   Garamba Alcelaphus buselaphus 1983           S            A
#> 3   Garamba Alcelaphus buselaphus 1984           S            A
#> 4   Garamba Alcelaphus buselaphus 1986           S            A
#> 5   Garamba Alcelaphus buselaphus 1991           S            A
#> 6   Garamba Alcelaphus buselaphus 1993           S            A
#> 7   Garamba Alcelaphus buselaphus 1995           S            A
#> 8   Garamba Alcelaphus buselaphus 1998           S            A
#> 9   Garamba Alcelaphus buselaphus 2000           S            A
#> 10  Garamba Alcelaphus buselaphus 2002           S            A
#> 11  Garamba Alcelaphus buselaphus 2003           S            A
#> 12  Garamba Alcelaphus buselaphus 2004           S            A
#> 13  Garamba Alcelaphus buselaphus 2012           T            A
#> 14  Garamba Alcelaphus buselaphus 2014           T            A
#> 15  Garamba Alcelaphus buselaphus 2017           T            A
#>    pref_field_method conversion_A2G   rmax count_orig lower_ci_orig
#> 1                  G          2.302 0.2748       7750          6280
#> 2                  G          2.302 0.2748       1932          1120
#> 3                  G          2.302 0.2748       1224           782
#> 4                  G          2.302 0.2748       1705          1116
#> 5                  G          2.302 0.2748        987           663
#> 6                  G          2.302 0.2748       3444          1290
#> 7                  G          2.302 0.2748       2819          1620
#> 8                  G          2.302 0.2748       1685          1287
#> 9                  G          2.302 0.2748       1169           945
#> 10                 G          2.302 0.2748       1139           907
#> 11                 G          2.302 0.2748       1595          1142
#> 12                 G          2.302 0.2748       1204           811
#> 13                 G          2.302 0.2748        552            NA
#> 14                 G          2.302 0.2748        698            NA
#> 15                 G          2.302 0.2748       1051            NA
#>    upper_ci_orig
#> 1           9220
#> 2           2744
#> 3           1666
#> 4           2294
#> 5           1311
#> 6           5598
#> 7           4018
#> 8           2083
#> 9           1393
#> 10          1371
#> 11          2048
#> 12          1597
#> 13            NA
#> 14            NA
#> 15            NA
#> 
#> $garamba__alcelaphus_buselaphus$data_converted
#>    location               species date stat_method field_method
#> 1   Garamba Alcelaphus buselaphus 1976           S            A
#> 2   Garamba Alcelaphus buselaphus 1983           S            A
#> 3   Garamba Alcelaphus buselaphus 1984           S            A
#> 4   Garamba Alcelaphus buselaphus 1986           S            A
#> 5   Garamba Alcelaphus buselaphus 1991           S            A
#> 6   Garamba Alcelaphus buselaphus 1993           S            A
#> 7   Garamba Alcelaphus buselaphus 1995           S            A
#> 8   Garamba Alcelaphus buselaphus 1998           S            A
#> 9   Garamba Alcelaphus buselaphus 2000           S            A
#> 10  Garamba Alcelaphus buselaphus 2002           S            A
#> 11  Garamba Alcelaphus buselaphus 2003           S            A
#> 12  Garamba Alcelaphus buselaphus 2004           S            A
#> 13  Garamba Alcelaphus buselaphus 2012           T            A
#> 14  Garamba Alcelaphus buselaphus 2014           T            A
#> 15  Garamba Alcelaphus buselaphus 2017           T            A
#>    pref_field_method conversion_A2G   rmax count_conv lower_ci_conv
#> 1                  G          2.302 0.2748  17840.500     14456.560
#> 2                  G          2.302 0.2748   4447.464      2578.240
#> 3                  G          2.302 0.2748   2817.648      1800.164
#> 4                  G          2.302 0.2748   3924.910      2569.032
#> 5                  G          2.302 0.2748   2272.074      1526.226
#> 6                  G          2.302 0.2748   7928.088      2969.580
#> 7                  G          2.302 0.2748   6489.338      3729.240
#> 8                  G          2.302 0.2748   3878.870      2962.674
#> 9                  G          2.302 0.2748   2691.038      2175.390
#> 10                 G          2.302 0.2748   2621.978      2087.914
#> 11                 G          2.302 0.2748   3671.690      2628.884
#> 12                 G          2.302 0.2748   2771.608      1866.922
#> 13                 G          2.302 0.2748   1270.704      1207.169
#> 14                 G          2.302 0.2748   1606.796      1526.456
#> 15                 G          2.302 0.2748   2419.402      2298.432
#>    upper_ci_conv field_method_conv
#> 1      21224.440                 G
#> 2       6316.688                 G
#> 3       3835.132                 G
#> 4       5280.788                 G
#> 5       3017.922                 G
#> 6      12886.596                 G
#> 7       9249.436                 G
#> 8       4795.066                 G
#> 9       3206.686                 G
#> 10      3156.042                 G
#> 11      4714.496                 G
#> 12      3676.294                 G
#> 13      1524.845                 G
#> 14      1928.155                 G
#> 15      2903.282                 G

The first elements of the list provide a summary of the count series.

If we compare the two last data frames (data_original and data_converted), they are not identical. The function format_data() has 1) computed 95% CI boundaries for total counts (coded T in the column stat_method), and 2) converted all counts (and CI boundaries) to their equivalent in the preferred field method (from A to G) by applying the conversion factor of 2.302.

The Bayesian model will use counts and precision measures from the data_converted data frame.

Before fitting the population size trend we can visualize the count series with plot_series().

popbayes::plot_series("garamba__alcelaphus_buselaphus", path = path)

The function format_data() has also exported the count series as .RData files in the path folder where they have been dispatched into sub-folders, one per series.

list.files(path, recursive = TRUE)

#>  [1] "garamba__alcelaphus_buselaphus/garamba__alcelaphus_buselaphus_data.RData"  
#>  [2] "garamba__giraffa_camelopardalis/garamba__giraffa_camelopardalis_data.RData"
#>  [3] "garamba__hippotragus_equinus/garamba__hippotragus_equinus_data.RData"      
#>  [4] "garamba__kobus_ellipsiprymnus/garamba__kobus_ellipsiprymnus_data.RData"    
#>  [5] "garamba__kobus_kob/garamba__kobus_kob_data.RData"                          
#>  [6] "garamba__loxodonta_africana/garamba__loxodonta_africana_data.RData"        
#>  [7] "garamba__ourebia_ourebi/garamba__ourebia_ourebi_data.RData"                
#>  [8] "garamba__redunca_redunca/garamba__redunca_redunca_data.RData"              
#>  [9] "garamba__syncerus_caffer/garamba__syncerus_caffer_data.RData"              
#> [10] "garamba__tragelaphus_scriptus/garamba__tragelaphus_scriptus_data.RData"

These *_data.RData files (count series) can be imported later by running the function read_series().

a_buselaphus <- popbayes::read_series("garamba__alcelaphus_buselaphus", path = path)

Fitting trend

The function fit_trend() fits population trajectories over time from counts of individuals formatted by format_data(). It does so under a Bayesian framework where the primary quantity being modeled is the annual rate of increase (more generally, the rate of increase per the time unit used for dates).

This function only works on the output of format_data() (or filter_series()).

Here is the default usage of the function fit_trend():

a_buselaphus_bugs <- popbayes::fit_trend(a_buselaphus, path = path)

The function returns an n-element list (where n is the number of count series). Each element of the list is a BUGS output as provided by JAGS. It has also exported these BUGS outputs as .RData files in the path folder where they have been dispatched into sub-folders, one per series.

These *_bugs.RData files (BUGS outputs) can be imported later by running the function read_bugs().

a_buselaphus_bugs <- popbayes::read_bugs("garamba__alcelaphus_buselaphus", path = path)

The function diagnostic() allows to check if estimation of all parameters of the model has converged. This diagnostic is performed by comparing the Rhat value of each parameter to a threshold (default is 1.1).

popbayes::diagnostic(a_buselaphus_bugs)
#> All models have converged.

In case convergence was not reached for some series, we suggest rerunning fit_trend() on these series after increasing the number of iterations (ni) and possibly the number of initial iterations discarded (nb) from their respective defaults of 50,000 and 10,000. For example:

a_buselaphus_bugs <- popbayes::fit_trend(a_buselaphus, path = path, ni = 100000, nb = 20000)

This process may be repeated with increasing values of ni and nb until convergence is eventually reached.

Finally we can use the function plot_trend() to visualize model predictions and estimated yearly relative growth rates.

popbayes::plot_trend("garamba__alcelaphus_buselaphus", path = path)

References

Cornelis D et al. (2014) Species account: African buffalo (Syncerus caffer). In: Ecology, Evolution and Behaviour of Wild Cattle: Implications for Conservation (Eds M Melletti & J Burton). Cambridge University Press, Cambridge. DOI: 10.1017/CBO9781139568098.
Foley CAH & Faust LJ (2010) Rapid population growth in an elephant Loxodonta africana population recovering from poaching in Tarangire National Park, Tanzania. Oryx, 44, 205-212. DOI: 10.1017/S0030605309990706.
Illius AW & Gordon IJ (1992) Modelling the nutritional ecology of ungulate herbivores: evolution of body size and competitive interactions. Oecologia, 89, 428-434. DOI: 10.1017/S0030605309990706.
Kingdon J & Hoffman M (2013) Mammals of Africa. Volume VI: Pigs, Hippopotamuses, Chevrotain, Giraffes, Deer and Bovids. Bloomsbury Publishing, London, United Kingdom, 680 pp.
Sinclair ARE (1996) Mammal populations: fluctuation, regulation, life history theory, and their implications for conservation. In: Frontiers of population ecology (Eds RB Floyd & AW Sheppard), pp. 127-154. CSIRO: Melbourne, Australia.
Sinclair ARE (2003) Mammal population regulation, keystone processes and ecosystem dynamics. Philosophical Transactions: Biological Sciences, 358, 1729-1740. DOI: 10.1098/rstb.2003.1359.
Suraud JP et al. (2012) Higher than expected growth rate of the endangered West African giraffe Giraffa camelopardalis peralta: a successful human-wildlife cohabitation. Oryx, 46, 577-583. DOI: 10.1017/S0030605311000639.