| Title: | Trend analysis of Constant Effort Site ringing data |
|---|---|
| Description: | Functions for reading EuroCES data in Euring format to produce annual indices of abundance, productivity and survival. Designed to primarily analyse data from schemes with 10-12 visits per year following methods used by the BTO. Use read.ces() to read in data, extract.data() and index() to do abundance/productivity trends and extract.ch() and mark.ces() to estimate survival probabilities. |
| Authors: | Rob Robinson <[email protected]> |
| Maintainer: | Rob Robinson <[email protected]> |
| License: | GPL-2 |
| Version: | 1.0.5 |
| Built: | 2025-02-15 04:55:07 UTC |
| Source: | https://github.com/btorobrob/cesr |
Facilities for reading EuroCES data in Euring format to produce annual indices of productivity, abundance and survival. Primarily designed to analyse data from schemes with 9-12 visits per year following Peach et al. (1996, 1998) and Robinson et al. (2007).
| Package: | cesr |
| Type: | Package |
| Version: | 1.0.2 |
| Date: | 2023-06-07 |
| License: | GPL-2 |
| LazyLoad: | yes |
Constant Effort Site (CES) ringing data provide a valuable way to monitor changes in abundance, productivity and survival through standardised capture and recapture of individuals. cesr provides some facilities to produce annual trends in abundance and productivity from these data. In order to do this cesr requires CES data organised in a plain text file according to the agreed Euring format (details of which can be found on the Euring website (http://www.euring.org/internal/ces_research_group/euro_ces_meeting_2008_notes.pdf).
The key steps are:
(i) to read in the data (with readces);
(ii) generate a table of which plots are covered in which year (with extract.coverage);
(iii) extract data for the species to be analysed (with extract.data), and
(iv) generate the annual abundance/productivity indices (with index).
Adult survival probabilities can be estimated by first using extract.ch then mark.ces. Results can be plotted using plot_trend. More details on how to do each of these can be found in the introductory manual, type
vignette('cesr-intro')
to view it.
Maintainer: Rob Robinson <[email protected]>
"Peach, W.J., Buckland, S.T. & Baillie, S.R. (1996) The use of constant effort mist-netting to measure between-year changes in the abundance and productivity of common passerines. Bird Study 43:142-156."
"Peach, W.J., Baillie, S.R. & Balmer, D.E. (1998) Long-term changes in the abundance of passerines in Britain and Ireland as measured by constant effort mist-netting. Bird Study 45:257-275."
"Robinson, R.A., Freeman, S.N., Balmer, D.E. & Grantham, M.J. (2007) Cetti's Warbler: anatomy of an expanding population. Bird Study 54:230-235."
"Robinson, R.A., Julliard, R & Saracco, J.F. (2009) Constant effort: studying avian population processes using standardized ringing. Ringing & Migration 24:199-204."
## Not run: # A sample session might look as follows: setwd('d:/data/ces') # set the working directory which contains the data file setceslang('English') # which language for species names? alldat <- readces('netherlands.csv') # read in the data plot.nl <- extract.coverage(alldat) # determine which sites covered in which years sonth.nl <- extract.data(alldat, species=12000,plots=plot.nl) # extract data for Song Thrush st.fit0 <- index(sonth.nl, year=2008) # fit an annual index st.fit1 <- index(sonth.nl, trend=30) # fit a simple linear trend writeces(st.fit0, 'sonthdata.txt') # write annual indices to a file ## End(Not run)## Not run: # A sample session might look as follows: setwd('d:/data/ces') # set the working directory which contains the data file setceslang('English') # which language for species names? alldat <- readces('netherlands.csv') # read in the data plot.nl <- extract.coverage(alldat) # determine which sites covered in which years sonth.nl <- extract.data(alldat, species=12000,plots=plot.nl) # extract data for Song Thrush st.fit0 <- index(sonth.nl, year=2008) # fit an annual index st.fit1 <- index(sonth.nl, trend=30) # fit a simple linear trend writeces(st.fit0, 'sonthdata.txt') # write annual indices to a file ## End(Not run)
Runs a specified set of models (see details) for a list of species and present the results in a table.
ces.table(cesobj, species=NA, columns=c("A-1", "P-1", "S-1"), base=100, plots=NULL, min.n=100, min.ch=50, ndigits=2, year=-1, change=FALSE, visit.corr=TRUE, save.results=FALSE)ces.table(cesobj, species=NA, columns=c("A-1", "P-1", "S-1"), base=100, plots=NULL, min.n=100, min.ch=50, ndigits=2, year=-1, change=FALSE, visit.corr=TRUE, save.results=FALSE)
cesobj |
a CES dataframe typically generated by |
species |
a numeric vector of Euring species codes, these can be checked using |
columns |
a character vector specifying which models should be applied to each species, see details. |
base |
which number should indicate no change: 0, 1, or 100? |
plots |
an object containing plot coverage data created by |
min.n |
if species is not specified, include all species with more than this number of captures. |
min.ch |
for survival models, how many individuals need to be captured for a site to be included, see |
ndigits |
numeric, how many decimal places to round the results to, see note. |
year |
the reference year for the comparisons if not the last. |
change |
logical, for comparison models return the change or the relative value (e.g. +0.2 or 1.2); for trend models TRUE gives the overall change, FALSE the (annual) slope. |
visit.corr |
logical, include an offset for missed visits in the models, see |
save.results |
logical, save the full model results, or only the annual values. Setting this to TRUE can result in a quite a large object, so it may be helpful to skip these. |
Models are specified using three characters: (i) the parameter ('A'dult and 'J'uvenile numbers, 'P'roductivity and 'S'urvival, (ii) the model type, currently either '-' to compare to previous years or '/' for a trend, and (iii) the number of (previous) years over which the comparison or trend should be calculated. Thus, for example. "A-5" would compare the current year's estimate of adult captures to the previous 5 years, see index for more details on this. The default is to compare with the previous year ("-1").
For change ('-') models the estimates will be either be the index relative to the base value (so -0.15, 0.85, or 85.0 for base = 0, 1, 100 respectively) or the relevant change (if change=TRUE then -0.15, -0.15, 15.0 in those instances). For trend ('/') models the estimate will be a slope (mean annual change), on either the log (abundance) or logit (survival/productivity) scale (and might be expressed as either 0.07 or 7.00, for example, depending on whether or not base=100).
A simple table will be printed with the change/trend estimate (along with confidence limits and an indication of significance) for each model (columns) and species (rows). These numbers are returned as a dataframe, see 'value' below.
a list with three components: table - a dataframe that mimics the printed table, so in 'wide' format; estimates - a dataframe in 'long' format, one row per entry; results - a named list of the model objects, in the form "T_xxxxx_mmm", where xxxxx is the Euring code number, mmm the model specification.
ndigits is strict, the returned 'estimates' dataframe will be rounded to this level as well.
Rob Robinson
## Not run: # compare adult numbers in the current yaer to the previous year, # survival with the previous five years and a 10-year trend in productivity results <- ces.table(ukdata, columns=c('A-0', 'S-5', 'P/10')) ## End(Not run)## Not run: # compare adult numbers in the current yaer to the previous year, # survival with the previous five years and a 10-year trend in productivity results <- ces.table(ukdata, columns=c('A-0', 'S-5', 'P/10')) ## End(Not run)
A datset containing species names in different languages for use by setceslang
data(ukdata)data(ukdata)
A data frame with 666 species names in English ad 11 other languages.
Currently just checks for rings used on multiple species
check_rings(cesdata)check_rings(cesdata)
cesdata |
A CES data object |
Checks where multiple species are associated with a single number number. Scheme is included as part of the ring number.
A dataframe containing a column of ring numbers and the species that they were ringed as; NULL if none are found. Only those rings which have apparently been put on more than one species are included.
Rob Robinson
Creates a list with individual capture histories for birds from a CES object created by readces for a survival analysis using mark.ces
extract.ch(cesdata, species=0, plots=NULL, late=FALSE, group=NA, exclude=NULL, min.n=1, min.yrs=3)extract.ch(cesdata, species=0, plots=NULL, late=FALSE, group=NA, exclude=NULL, min.n=1, min.yrs=3)
cesdata |
a CES object created by |
species |
a numeric Euring species code (including final zero which would indicate race) |
plots |
an object containing plot coverage data created by |
late |
should late visits be considered in site selection? In UK (at least) most adults are caught in first 6 visits, so defaults to FALSE (ie a site is included if, say, 4 of the first 6 visits are made). Set to TRUE to require late visits to be considered also, which will results in more site-year combinations being considered as 'missing' |
group |
a character string indicating a grouping variable for survival, such as 'sex'. Group levels should be alphabetic only (i.e. no digits (0-9) or symbols please; these confuse MARK). |
exclude |
one or more levels of 'group' to exclude, for example, '-' for unsexed birds |
min.n |
minimum total number of captures for a site to be included, may be useful with large datasets to aid convergence or memory allocation |
min.yrs |
minimum number of years for which a site has operated to be included |
Creates a '10' style capture hisory for each ringed bird (if a bird moves site it is treated as a new individual). Missing visits are preserved and handled by MARK. The additional capture within the first season is entered by shifting the first capture back a 'year' and entering a 1 subsequently (ie in the first actual year of capture) if the bird is recaught within that year, 0 otherwise. Birds initially caught as juveniles are included if they are subsequently caught as adults (with the juvenile captures removed).
A list of six items
chdata |
A data frame with columns: ring, ch and site |
begin.time |
A four digit integer indicaing the first year from which observations come |
years |
An integer indicating the number of years from which obserations come |
group |
a list consisting of name - character string indicating a grouping variable for survival or NA, and levels - a vector of the group levels |
spp |
Euring species code |
spp.name |
Name of the species in whichever language has been set by |
The matching of site names assumes that the order in whch they appear in x is the original one, avoid sorting this dataframe. If histories are extracted by group, the mark.ces will always estimate survival by group, to avoid this you will need to re-extract the data without a grouping variable.
Rob Robinson
data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.ch(ukdata, species=10990, plots=plots)data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.ch(ukdata, species=10990, plots=plots)
Extracts catch data for a particular species from a CES object, usually called through extract.data.
extract.counts(cesobj, species=0, age=0, plots=NULL)extract.counts(cesobj, species=0, age=0, plots=NULL)
cesobj |
A dataframe containing CES data usually generated by /codereadces |
species |
Species for which to extract data. This should be a standard Euring numeric code, for example Turdus merula would be 11870 (note the last digit, to indicate race, should always be zero). If species=0, summarises catch total across all species. |
age |
Euring age code 3 for juveniles and 4 for adults, any other value is an error. |
plots |
An object indicating which sites were covered in each year. Normally this would be generated by |
A datatframe containing the number of birds caught at each site in each year. Usually with an identifier for the species to which the data refer.
Rob Robinson
Creates a list which identifies which CES sites are covered in each year and the number of missing visits.
extract.coverage(cesdata, early=NA, late=NA, min.visits=1, all.visits=0, exclude=list(years=NULL, sites=NULL))extract.coverage(cesdata, early=NA, late=NA, min.visits=1, all.visits=0, exclude=list(years=NULL, sites=NULL))
cesdata |
A CES object created by |
early, late
|
Numeric vectors of length 2, the first giving the number of visits in the first/second period, the second the number of visits required in each for the site to be included. They will be reversed if necessary. |
min.visits |
The minimum number of visits that should be made in the season. An alternative to specifying early/late. |
all.visits |
The number of visits that should be made in the season. If missing will default to the highest visit number in the dataset with a warning (see details). |
exclude |
A list with one or two components listing sites or years that should be excluded from consideration. |
Creates a list containing information on coverage of sites in each year. For a site to be considered covered in a given year a certain number of visits (min.visits) must be made. Most adults will be caught earlier in the season, most juveniles later; thus an additional constraint is imposed in that a certain number (y) of the first x visits, and similarly of later visits, should also be made. This can be specified using early=c(x,y) and late=c(x,y); for example, in Britain, four of the first six and four of the last six visits are required so these would be specified as c(6,4). This has the advantage that if a site is only covered in the early period of the year, say, it can still be used for calculating adult abundance. Although normally the specification is likely to be the same for bother periods, it doesn't have to be (e.g. if you have an odd number of visits), and the periods can overlap if required.
It is wise to specify all.visits explicitly, if not the highest visit number will be taken from the dataset. This can cause problems if, say, most sites do nine visits, but one site has done ten in one year, meaning that only that one season is identified as 'complete' and greatly inflating the number of 'missing' visits. The function will try to warn if it thinks this has happened.
A list containing three objects
sites |
A dataframe consisting of site details including: habitat, latitude, longitude, net length and first/last year of operation. |
years |
A dataframe consisting of a site by year matrix and identifying whether early and late periods were covered. |
coverage |
A dataframe identifying number of visits in each period and whether each site/year should be included in the trend calculations. |
missing.visits |
A dataframe identifying which visits are missing across sites and years |
all.visits |
An integer specifying the number of visits that should be made. |
min.visits |
An integer specifying the minimum number of visits that should be made. |
The function calculates coverage from the catch data, thus if no birds are caught on a visit that visit will not be registered; hopefully this will be an infrequent occurrence!
Rob Robinson
data(ukdata) sites.cov<-extract.coverage(ukdata)data(ukdata) sites.cov<-extract.coverage(ukdata)
Creates dataframes with capture data for adult and juvenile birds from a CES object created by readces
extract.data(cesdata, species=0, plots=NULL, min.yrs=1)extract.data(cesdata, species=0, plots=NULL, min.yrs=1)
cesdata |
a CES object created by |
species |
Euring species code (including the final zero which would indicate race). |
plots |
an object containing plot coverage data created by |
min.yrs |
sites covered in fewer than min.yrs will be ignored. |
A list of up to four items
spp |
Euring species code |
spp.name |
Name of the species in whichever language has been set by |
Either or, more usually, both of the following may be present
ad.data |
data frame with summary of adult captures |
jv.data |
data frame with summary of juvenile captures |
Rob Robinson
data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.data(ukdata, species=10990, plots=plots)data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.data(ukdata, species=10990, plots=plots)
Generates a table of site information
extract.sites(cesdata, exclude=NULL)extract.sites(cesdata, exclude=NULL)
cesdata |
A CES object created by |
exclude |
A vector of sitenames to be excluded |
Currently mainly used to generate data for map.ces.
A dataframe with site (the internal numeric identifier), sitename, habitat, lat and long (in decimal degrees), netlength, number of years operated (nyears), first and last year of operation, whether the site is current, and the number of missing years in the data run.
Rob Robinson
data(ukdata) sites <- extract.sites(ukdata)data(ukdata) sites <- extract.sites(ukdata)
Search for the Euring code number of a species.
get.euring(string)get.euring(string)
string |
A character string containing (part of) a species name, in any language. |
A dataframe containg the code and scientific names of species that contain the search string.
Rob Robinson
Takes a CES object created by extract.data and, depending on what data are available, creates indices of the number of adults and juveniles caught and the ratio of the two, as an index of productivity.
index(cesdata, year=-1, begin=0, smooth=FALSE, random=FALSE, trend=0, compare=0, verbose=FALSE, visit.corr=TRUE, cl=0.95)index(cesdata, year=-1, begin=0, smooth=FALSE, random=FALSE, trend=0, compare=0, verbose=FALSE, visit.corr=TRUE, cl=0.95)
cesdata |
A CES dataset create by |
year |
A year to act as reference year, i.e. in which the index is value is 1 |
begin |
The first year for which the trend should be calculated from. May be useful if a species is not common in the first years of the dataset, but becomes so subsequently. |
visit.corr |
Logical, include the correction for missing visits when calculating indices? |
cl |
Width of confidence limits. 0.95 is default, 0.83 limits don't overlap with (approximate) probability 0.95, so may be useful when comparing (or graphing) values of the index in specific years. |
smooth |
An indicator value to determine if smoothed trends should be calculated. These are fitted with |
random |
An indicator value to determine if site and year should instead be fitted as random effects (~(1|site) + (1|year) + (1|site:year)), with both site and year as factors (only). |
trend |
An integer to indicate how many years to calculate a linear trend over. The last year of the trend will always be the last year in the dataset. If trend is greater than the number of years available then a simple linear trend will be fitted. |
compare |
An integer to indicate how many years to compare the last year to. Thus if compare=5 and the last year is 2008 then the index value for 2008 will be compared to the average values for 2003-2007 (which will be set to 1). Earlier years will be modelled as annual fixed-effects. |
verbose |
Logical. If TRUE then the annual estimates will be printed, if FALSE then a summary test will be printed. |
Uses data from sites covered in more than one year.
A list with some or all of the following components
ad.results |
Model fit information for adult birds |
jv.results |
Model fit information for juvenile birds |
ad.results |
Model fit information for adult birds |
Each of these three consists of three components: model - a glm object containing the model fit; parms - a dataframe containing the annual year parameter estimates; and test - a list containing either the results of statistical tests generated by using compare or trend, or additional model information if smooth= or random=TRUE.
model.type |
a list containing the type of model fitted (type), the reference year (refyear) and the number of years over which any trend or comparison are fitted (nyrs) |
spp |
Euring species code |
spp.name |
Name of the species in whichever language has been set by |
Rob Robinson
data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.data(ukdata, species=10990, plots=plots) result <- index(robin.dat, verbose=TRUE) res.lin <- index(robin.dat, trend=5)data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.data(ukdata, species=10990, plots=plots) result <- index(robin.dat, verbose=TRUE) res.lin <- index(robin.dat, trend=5)
Loads a datafile containing summary boxplot data to use as reference for site-specific plots
load.boxplot(filename=NULL, name='bxpdata')load.boxplot(filename=NULL, name='bxpdata')
filename |
the name of the file containing the summarised data, typically ending in 'year.Rdata' or '_speciesxxxx.RData' |
name |
the name of the object to store the boxplot data in |
A list with three components:
ds |
the (subsetted) dataset |
ds.bxp |
data for the boxplot in summary form |
ds.attr |
some useful attributes |
No error checking is done so make sure you load the right file!
Rob Robinson
Plot CES sites on a simple outline map
map.ces(cesobj, type='c', xlim=c(-20,30), ylim=c(35,70), pch=21, col=c('white','red'), file=NULL, width=640, height=480, lwd=1, cex=1, units='px', mar = c(1, 1, 1, 1), ...)map.ces(cesobj, type='c', xlim=c(-20,30), ylim=c(35,70), pch=21, col=c('white','red'), file=NULL, width=640, height=480, lwd=1, cex=1, units='px', mar = c(1, 1, 1, 1), ...)
cesobj |
A CES object with site information, usually generated by extract.sites() |
type |
How to identify sites: currently 'c' for current/non-current, 'n' for number of years operating, 'h' for habitat, and 's' for site-specific colours |
xlim |
Minimum and maximum longitude bounds, note R will make this 'pretty' |
ylim |
Minimum and maximum latitude bounds, note R will make this 'pretty' |
pch |
A numeric value (21-25) identifying symbol type, see ?pch, but 21=circles, 22=squares |
col |
A vector of colors to fill points, see type |
lwd |
if pch=21:25, weight of point borders, useful for highlighting e.g. current sites |
cex |
size of points |
file |
A valid filename to plot the map to, identified by extension, current options recognised are .png, .jpg (or .jpeg), .tif (or .tiff) and .ps |
width, height
|
size of map (normally in pixels) |
units |
Units for the size, use 'mm' if outputting to pdf/postscript file |
... |
Additional arguments passed to |
The default is to color points by whether they are current (second element of col) or historic - the latest year present is taken to represent the 'current' year. If type='n' then the plot will depend on the number of colors, two will separate sites below/above the median number of years operated; three the bottom quartile, the middle 50 percent and the upper quartile (approximately) and four will split by quartile. Any expansion of 'Current', 'No Years', 'Habitat' should work (only the first letter is significant and case is not important).
None
Rob Robinson
data(ukdata) sites<-extract.sites(ukdata) map.ces(sites)data(ukdata) sites<-extract.sites(ukdata) map.ces(sites)
Fit CJS-with-transients model to estimate annual adult survival from CES data.
mark.ces(cesobj, exclude=NULL, type='+', trend=0, constant=0, compare=0, cleanup=TRUE)mark.ces(cesobj, exclude=NULL, type='+', trend=0, constant=0, compare=0, cleanup=TRUE)
cesobj |
A CES object with capture histories, typically created by |
exclude |
A vector of sites to exclude from the survival modelling |
type |
How to model group-specific survivals, either additively '+' (the default) or in interaction ':', this requires the groups to have been specified in |
trend |
An integer to indicate how many years to calculate a linear trend over. The last year of the trend will always be the last year in the dataset. If trend is greater than the number of years available then a simple linear trend will be fitted. |
constant |
An integer indicating the last n years over which survival will be modelled as constant. |
compare |
An integer indicating the how many n previous years to compare the last year's estimate to. |
cleanup |
MARK creates a series of output files for each survival model fitted. If cleanup=FALSE, these will be stored in the sub-directory 'markfiles', if cleanup=TRUE they will be deleted. x$model$output indicates which files are associated with the survival model stored in x. |
Calls MARK to fit a CJS-with-transients model for data extracted by extract.ch, see which for details of data inclusion. Currently, fits the a model in which probability of residency id constant across sites and years, survival is year-dependent and recapture rates are site dependent (with that within the first year being a fixed proportion of the annual rate).
If a grouping variable was specified when the data were extracted, survivals will be modelled in relation to this variable, either additively or interactively, according to 'type'.
To fit a time-constant model ('phi(.)' in Mark notation) set 'constant' to be a number equal to the number of capture intervals in the data. If a number larger than that is given for 'constant' or 'compare' then it will be adjusted accordingly (to n or n-1).
A list consisting of model (the output returned by RMark), its AIC and (corrected) number of paramters (npar), and dataframes called residency, survival, recapture and recap1 with the parameter estimate, standard error and upper and lower confidence limits (as ucl, lcl) for each parameter.
Requires MARK (http://www.phidot.org/software/mark/downloads/index.html) to be installed (and the MarkPath variable to be set if it is not in the default location, see ?mark)
Rob Robinson, with thanks to Christian Kamplicher
## Not run: data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.ch(ukdata, species=10990, plots=plots) robin.res <- mark.ces(robin.dat) ## End(Not run)## Not run: data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.ch(ukdata, species=10990, plots=plots) robin.res <- mark.ces(robin.dat) ## End(Not run)
Plots an estimated trend from CES data either to the screen or to a file.
plot_trend(x, type, group=NULL, file = NULL, width=480, height=480, units='px', main=FALSE, lty=c(1,2), lcol='black', lwd=1, line=NA, rlty=3, rlwd=1, rcol='black', annual=FALSE, pch=19, pcol='black', pcex=1, ...)plot_trend(x, type, group=NULL, file = NULL, width=480, height=480, units='px', main=FALSE, lty=c(1,2), lcol='black', lwd=1, line=NA, rlty=3, rlwd=1, rcol='black', annual=FALSE, pch=19, pcol='black', pcex=1, ...)
x |
A CES object |
type |
Which trend to plot? Can be either 'Adult' or 'Juvenile' Abundance, 'Productivity' or 'Survival'. Only the first letter needs to be given, in either lower or upper case. |
group |
If survival trends have been calculated by group, the group level to be plotted. |
file |
A valid file name, ending in either '.png', '.jpg', '.jpeg', 'svg', '.tif', '.tiff', '.ps' or '.pdf' to produce a file of the appropriate type. If file=NULL (the default) the trend will be plotted to the screen. |
width |
The width of the device. |
height |
The height of the device. |
units |
The units in which height and width are given. Can be px (pixels, the default), in(ches), or mm. |
main |
should the plot have a title? If a value other than TRUE/FALSE is given then that will be used as the title. |
lty, lwd, lcol
|
a vector of length 1 or 2, if length 2 the first entry will be used for the trend line, the second for the confidence limits. |
line |
if required, the value (e.g. 1) at which a horizontal reference line will be drawn. |
rlty, rcol, rlwd
|
if a reference line is specified, the line type, color and width to use. |
annual |
logical, plot the annual estimates too? |
pch, pcol, pcex
|
if annual=TRUE, symbol, color and size to use in plotting points. |
... |
additional arguments passed to plot, such as bty, ylab or ylim. |
Plots a single CES trend to a file, or to the screen if no file is not specified. PNG format is small and lossless and so good for images of this type. Invisibly returns a dataframe with the annual values used to create the graph. If you wish a finer degree of control over the appearance of the graph, best import this data to your favourite graphing package, or plot this data directly in R.
If assigned to an object, a dataframe with the following columns: 'years', 'parm', 'se', 'index', 'lcl', 'ucl'.
If you get an error about "figure margins too large", you need to either increase the height and width (of the file, or make the plotting window larger), or check you have the correct units.
Rob Robinson
##---- Should be DIRECTLY executable !! ---- ##-- ==> Define data, use random, ##-- or do help(data=index) for the standard data sets.##---- Should be DIRECTLY executable !! ---- ##-- ==> Define data, use random, ##-- or do help(data=index) for the standard data sets.
Methods to quickly plot CES objects of different types.
## S3 method for class 'ces' plot(x, sites = FALSE, graph = "X", N=20, sitelist=NULL, col=c('red', 'blue'), ...)## S3 method for class 'ces' plot(x, sites = FALSE, graph = "X", N=20, sitelist=NULL, col=c('red', 'blue'), ...)
x |
A CES object |
sites |
Logical. If TRUE, for objects creates by |
graph |
Graph type for plotting results of |
N |
Integer. If plotting an object created by |
sitelist |
Character vector. If plotting an object created by |
col |
Character vector. If plotting an object created by |
... |
Additional arguments, see details |
Plots an appropriate summary graph (or graphs) for a ces object.
For 'raw' data (created by readces), a summary of captures by year, visit, site and species (for the top N sites/species only) with bars indicating the inter-quartile range across years.
For 'plot' data (created by extract.coverage), the number of sites operating in each year, and the number of sites operating for a particular number of years.
For 'count' data (created by extract.data), the number of adults and juveniles caught of the species in each year (black bars indicate the number of expected birds had there been no missing visits) and the cumulative number of birds caught where sites are ranked from those catching the most to fewest.
For abundance/productivity results (created by index) graphs of the annual values and parameter estimates; a single trend can be produced using the 'graph=' argument, but use plot.trend() for prettier output. Will also accept 'ylab' and 'title'.
For capture history ('ch') data (created by extract.ch), a plot of the capture histories, grouped by site, each line represents a group of individuals with the same encounter history, colored by whether they were caught or not on each occasion; darker lines indicate more frequent histories. Also accepts xlab, ylab, cex (on the y-axis, possibly to fit more site labels in) and main.
None
In the ch plots, because birds are possibly caught twice in their first year, 'Occasion' (the x-axis) is not quite the same as Year.
Rob Robinson, the ch plot was inspired by one of Marc Kery's.
data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.data(ukdata, species=10990, plots=plots) plot(robin.dat)data(ukdata) plots <- extract.coverage(ukdata) robin.dat <- extract.data(ukdata, species=10990, plots=plots) plot(robin.dat)
Largely a placeholder currently, but handles summary tables gracefully
## S3 method for class 'ces' print(x, ...)## S3 method for class 'ces' print(x, ...)
x |
A CES data object |
... |
Other arguments, currently they will have effect! |
Largely a placeholder currently, but handles summary tables gracefully.
Rob Robinson
Reads in CES data from a text file in EuroCES format
readces(file, visits='std', group.race=TRUE, fix=FALSE, winter=FALSE, verbose=FALSE) readBTO(file, species)readces(file, visits='std', group.race=TRUE, fix=FALSE, winter=FALSE, verbose=FALSE) readBTO(file, species)
file |
A valid filename |
visits |
Either 'std' to include only standard (numbered up to 13) visits, 'all' to do no checking, or a (character) vector listing allowed visit identifiers. |
group.race |
Aggregate records of different races (i.e. those where the last digit of the Euring code is not zero)? |
fix |
Logical, should presumed errors be fixed? See details. |
winter |
Logical, if TRUE days will be numbered from July 1, and year will be adjusted downwards by 1 for visits in January to June, so Jan 1 1985 will become day 185 of 1984. |
verbose |
Logical, produce a file listing records with (currently species/age/sex) errors to be fixed? |
species |
A numeric Euring species code |
For details of the file specification see the CES pages of the Euring website, the function will attempt to match similar column names; a warning will be generated if it detects anything amiss (not guaranteed!). Some of these can be safely ignored (e.g. the 'surprising species' one) if everything appears to be in order.
The function does some basic error-checking and will try to give informative messages where it detects a problem. Where records are deleted or values set to NA (missing) a warning will be given. If fix=TRUE then the function will change records as follows: - sex of all encounters for an individual will be assigned the commonest sex recorded for that species (if the sex on encounter is recorded as unknown, or the other sex). - records aged as 3 in any year other than that of first encounter will be changed to 4. - sites with multiple coordinates will be be assigned their average location (across rows) - rows will be ordered by site, followed by year, visit, species and ring number where possible the function will indicate how many records have been fixed.
A dataframe with (at a minimum) the following columns: countryID (where the scheme is), sitename(as referred by the scheme), site (a sequential numeric identifier), habitat, visit (number), day, month, year, netlength, ring, species, sex, age, race, julian (day), lat, long. Unrecognised columns in the datafile will be removed. Note, 'ring' will be a combination of scheme and ring, separated by an underscore ('_'), any '.' in the ring number will be removed.
Latitude and longitude are in decimal degrees (rounded to 3 d.p. which is ~ 0.1km, and always towards the south and west, i.e. the bottom-left of the grid cell). Race will usually be the same as species (i.e. a Euring number), unless particular races were identified in the data file (e.g. as for Motacilla alba alba/yarrelli, see group.race=). The column 'julian' gives the day of year from 1 Jan (including 29 Feb in leap years).
The CES programs expect birds aged as either juvenile (3) or adult (4), the function will recode ages where it can, 2 is also allowed; records with other ages (0, 1) will be deleted. Expect some warnings, some are for information only - they do not necessarily indicate an error.
readBTO() is provided for reading in BTO '.all' fixed format files, variables not included in this format (eg habitat, NetLength) are simply set to NA.
Rob Robinson
Euring CES pages: https://euring.org/research/ces-europe/
## Not run: ukdata <- readces("d:/data/ces/ukdata.csv", fix=TRUE) ## End(Not run)## Not run: ukdata <- readces("d:/data/ces/ukdata.csv", fix=TRUE) ## End(Not run)
Creates a datafile containing summary boxplot data to use as reference for site-specific plots
save.boxplot(data=NULL, annual=TRUE, species=TRUE, year=0, filename='bxp', ...)save.boxplot(data=NULL, annual=TRUE, species=TRUE, year=0, filename='bxp', ...)
data |
a CES dataset created by |
annual |
logical, if TRUE create boxplot summary data by year |
species |
logical, if TRUE create boxplot summary data by species |
year |
numeric, if species=TRUE, the year for which to create the summary |
filename |
a character string to use as the filestem, see details |
... |
further arguments passed to |
Saves the necessary data to create a boxplot summarising site-specific captures using siteplot. If annual=TRUE, the filename will expand to 'filename_year.RData', if species=TRUE then the data will be saved to 'filename_speciesxxxx.RData', where xxxx is the year. If year is not specified then the last year present in the dataset will be assumed. Data may be reloaded by using load.boxplot.
None. Used for its side effect of creating one or two (.RData) files.
Rob Robinson
##---- Should be DIRECTLY executable !! ---- ##-- ==> Define data, use random, ##-- or do help(data=index) for the standard data sets.##---- Should be DIRECTLY executable !! ---- ##-- ==> Define data, use random, ##-- or do help(data=index) for the standard data sets.
Select sites from a CES data object, either from a ist of specified sites or habitat.
select.data(x, sites = 0, habitat = "")select.data(x, sites = 0, habitat = "")
x |
A CES data object, typically generated by |
sites |
A vector of site codes |
habitat |
Two-letter code identifying habitat required. Generally the available codes are 'RB' Reedbed, 'WS' Wet Scrub, 'DS' Dry/Thorn Scrub and 'WD' Woodland but certain countries may have other scheme-specific codes |
An easy way of subsetting a CES data object to select particular sites. Experienced users may prefer to do this directly.
A ces data object
Rob Robinson
data(ukdata) sitelist = c(401, 403, 405, 407, 408, 414, 417, 447, 463) # select sites with complete data complete = select.data(ukdata, sites=sitelist) scrub = select.data(ukdata, habitat='DS')data(ukdata) sitelist = c(401, 403, 405, 407, 408, 414, 417, 447, 463) # select sites with complete data complete = select.data(ukdata, sites=sitelist) scrub = select.data(ukdata, habitat='DS')
Allows species names in outputs to be rendered in one of 14 languages.
setceslang(lang)setceslang(lang)
lang |
A string indicating a valid language, see details below. If no language is set most functions will default to using the scientific name |
Valid languages are "Latin", "Danish", "Dutch", "English", "Finnish", "French", "German", "Italian", "Norwegian", "Polish", "Portuguese", "Spanish", "Swedish". This is set by a call to options, use options()$ceslang to check which language is currently set.
Sets global option 'ceslang'
Names are 'sticky', that is when an object is created, for example with extract.data, cesr uses the language set at the time and this cannot easily be changed subsequently.
Names are case sensitive, that is they need to be capitalised.
Rob Robinson
setceslang("English")setceslang("English")
Generate boxplot of captures for all sites, by year or species, with those from one site highlighted.
siteplot(data, site=0, year=0, visit=FALSE, splist=NULL, nspecies=20, nyears=NA, age=0, subset=NULL, effort=FALSE, ylab=NULL, margin=8, pch=21, pt.cex=2, pt.col='red', plot=TRUE, ...)siteplot(data, site=0, year=0, visit=FALSE, splist=NULL, nspecies=20, nyears=NA, age=0, subset=NULL, effort=FALSE, ylab=NULL, margin=8, pch=21, pt.cex=2, pt.col='red', plot=TRUE, ...)
data |
either a dataframe generated by |
site |
character, the site to highlight |
year |
integer, specify a year to create a summary by species or visit |
visit |
logical, summarise catches within a year by visit number? If visit=FALSE (the default), catches will be summarised by species |
splist |
character, if a year is specified, optionally either a vector of Euring codes, or 'all' (not generally advised) |
nspecies |
numeric, if a year is specified and splist not, then plot the commonest 'n' species on the site |
nyears |
numeric, limit the number of years plotted to the number that the site operated, with this as a minimum. For example, if nyears=10 and the site has operated for 15 years, 15 bars (and dots) will be shown, but if the site has only operated for 5 years, then 10 bars will be plotted. |
age |
numeric, either 3 or 4 to select only juvenile or adult captures |
subset |
a logical expression to subset the data |
effort |
logical, should the number of captures be divided by netlength on the site? |
ylab |
character, a label for the number axis |
margin |
if year is specified, either a single number for the width of the left margin, or a vector of length 4 specifying each margin width, see details |
pch |
the symbol with which the site counts are plotted |
pt.cex |
size of the symbol with which the site counts are plotted |
pt.col |
colour of the symbol with which the site counts are plotted |
plot |
logical, should a plot be produced. For larger datasets, creating the summary data first without plotting may be helpful, see details |
... |
additional arguments passed to |
Generates a boxplot of captures per site, with those from 'site' highlighted using an overlain point. Data may be summarised either annually (if year=0), or by species (if a year is specified). In the former case the boxes will be vertical, in the latter horizontal. The width of the margin(s) can be changed (by using margin=) if there is not enough room for the species names.
For larger datasets, creating the boxplot summaries may take some time. In this case it is advised to run the function with plot=FALSE to create the data for the boxplot. This can then be supplied to data=, meaning that only the individual site counts need to be extracted and plotted each time.
A list with three components:
ds |
the (subsetted) dataset |
ds.bxp |
data for the boxplot in summary form |
ds.attr |
some useful attributes |
It is assumed that this function will be used for current sites, so the nyears argument only counts backwards from the current year.
Rob Robinson
data(ukdata) uk.bxp <- siteplot(ukdata, site='656') siteplot(uk.bxp, site='420')data(ukdata) uk.bxp <- siteplot(ukdata, site='656') siteplot(uk.bxp, site='420')
Generate a simple summary report (as MS Word documents) of captures at a site.
sitereport(cesdata, sitelist=NULL, year=0, template_file=NULL, outdir=getwd(), no.species=12, nyears=NA, verbose=TRUE)sitereport(cesdata, sitelist=NULL, year=0, template_file=NULL, outdir=getwd(), no.species=12, nyears=NA, verbose=TRUE)
cesdata |
a dataframe generated by |
sitelist |
character, a vector of sitenames for which to generate the reports; NULL and "all" are equivalent |
year |
specify a year to create a summary by species |
template_file |
the name of an RMarkdown template file |
outdir |
where to save the reports to |
nyears |
numeric, limit the number of years plotted to the number that the site operated, with this as a minimum. For example, if nyears=10 and the site has operated for 15 years, 15 bars (and dots) will be shown, but if the site has only operated for 5 years, then 10 bars will be plotted. |
no.species |
numeric, maximum number of species to include in the barplots. |
verbose |
logical, print a message when each site has been processed? |
Rob Robinson
## Not run: data(ukdata) sitereport(ukdata, sitelist=c('656','420')) ## End(Not run)## Not run: data(ukdata) sitereport(ukdata, sitelist=c('656','420')) ## End(Not run)
Methods to summarize CES objects
## S3 method for class 'ces' summary(object, age=0, sp.order='alpha', ads=FALSE, jvs=FALSE, prod=FALSE, df=FALSE, nrow=6, silent=FALSE, ...)## S3 method for class 'ces' summary(object, age=0, sp.order='alpha', ads=FALSE, jvs=FALSE, prod=FALSE, df=FALSE, nrow=6, silent=FALSE, ...)
object |
A CES object |
ads, jvs, prod
|
logical, if TRUE and x contains index results, print summary statistics for adult/juvenile abundance/productivity only. |
age |
Euring age code - either 3 juveniles or 4 for adults |
sp.order |
Should species be displayed in order of the 'alpha'bet, decreasing 'count' or, if neither specified, 'taxon'omic (Voous) order. |
df |
logical, if TRUE and x is CES data object created by |
nrow |
integer, if x is a species summary object, print this many rows, ordered by highest count. |
silent |
logical, if TRUE suppress printing of the species counts. May be useful if you just want to generate a table of species counts for further manipulation. |
... |
arguments passed to other methods. |
summary() will call the appropriate method as follows:
If given an object created by readces it will print a table of number of each species caught (only those of 'age' if that argument is given) in 'sp.order'
If given an object created by extract.data it will provide a simple summary of the number of birds caught (or only those of 'age' if that argument is given)
If given an object created by extract.coverage it will provide a summary of the number of plots operated in each year and the number of years plots have been operating
If given an object created by index it will provide summary statistics of the fit
Normally one will want to summarise results for both age-classes and productivity measure, but the facility is provided to do this for only one age-class if desired.
Invisibly, a dataframe (or a list of dataframes) containing the numerical data.
Rob Robinson
data(ukdata) summary(ukdata)data(ukdata) summary(ukdata)
CES sites may have an excess of individuals that are caught only once, and so potentially transient to the site. This function plots individuals by whether they were captured subsequently or not.
transient_plot(cesobj, col=c('blue', 'red'), border='gray10', leg.size=0.8, ...)transient_plot(cesobj, col=c('blue', 'red'), border='gray10', leg.size=0.8, ...)
cesobj |
A CES object created by |
col |
Character vector. Colors to plot re-captured and not re-captured individuals respectively. |
border |
Character. Color for the border of the bars. |
leg.size |
Numeric. Size of the legend text. |
... |
Additional parameters passed to |
CES sites may have an excess of individuals that are caught only once, and so potentially transient to the site. This function plots individuals by whether they were captured subsequently or not, specifically whether they were captured twice in their first year (and so likely to be resident), captured only once in their first year (but caught again in a later year, and so also resident), and individuals caught only once. These latter may be transients (individuals passing through, or living on the very edge of the catching area, so with low capture probability) or resident individuals that happened not to be recaptured. Two barplots are produced, one classifying individuals by their year of first capture, and the second by site. Transients have the otential to bias survival estimates low as, once they leave the site (and so can no longer be captured), the models see them as dead. The function to calculate survival (mark.ces) tries to estimate the proportion of these individuals in the sample.
A list with three elements. (i) years - the matrix necessary to draw the years barplot, (ii) sites - the matrix necessary to draw the sites barplot, and (iii) the species name.
Rob Robinson
A sample CES dataset from the UK of two species (Erithacus rubecula and Turdus philomelos) from 19 sites created by readces
data(ukdata)data(ukdata)
A data frame with 4,879 observations on the following 15 variables.
countryIDa factor with levels GBT - the scheme identifier using Euring three-letter codes
habitata factor with levels DS RB WD WS - for Dry/Thorn Scrub, Reedbed, Woodland and Wet Scrub respectively
visitnumeric - 1:12 for UK
daynumeric
monthnumeric - 1:12
yearnumeric - four digits
netlengthnumeric - length of net erected (in metres)
schemea factor with levels GBT - of ring, allows for foreign controls
ringa factor with levels 012083 012098 012100 ...
speciesnumeric - Euring numeric, aggregates races so will end in zero
sexa factor with levels F M U
agenumeric - either 3 (juvenile) or 4 (adult)
sitenamea site identifier, numeric in this case, may be character for other schemes, identical to siteID
sitenumeric - a site identifier, with sites numbered 1:n
racenumeric - Euring code as in orginal datafile, may specify races
juliannumeric - ordinal day (in year) of capture
latnumeric - latitude in decimal degrees
longnumeric - longitude in decimal degrees, East of the Greenwich meridian is positive
data(ukdata) summary(ukdata) plot(ukdata)data(ukdata) summary(ukdata) plot(ukdata)
Provides a wrapper function to write CES data objects to a comma-separated text file
writeces(cesobj, file = "", na.string = ".", age = 0, ads = FALSE, jvs = FALSE, prod = FALSE, verbose=TRUE)writeces(cesobj, file = "", na.string = ".", age = 0, ads = FALSE, jvs = FALSE, prod = FALSE, verbose=TRUE)
cesobj |
a CES object |
file |
A valid filename |
na.string |
Character(s) to use to represent missing values in the output file |
age |
Euring age code - 3 for juvenile or 4 for adult |
ads, jvs, prod
|
logical, if TRUE write out data for adult/juvenile abundance/productivity only. |
verbose |
logical, if TRUE write out individual visit data writing plot data. |
Write an object of class CES to a comma-separated text file. Use argument 'age' to just write juvenile or adult data. If outputting the results of a model fit from index, normally one will want to summarise results for both age-classes and productivity measure, but the facility is provided to do this for one age-class only if desired (by setting ads, jvs or prod equal to TRUE respectively).
Rob Robinson
## Not run: data(ukdata) robin.dat=extract.data(ukdata,species=10990) writeces(robin.dat, file="d:\data\robin.csv") ## End(Not run)## Not run: data(ukdata) robin.dat=extract.data(ukdata,species=10990) writeces(robin.dat, file="d:\data\robin.csv") ## End(Not run)