Estimation of abundance and other demographic parameters for closed populations, open populations and the robust design in capture-recapture experiments using loglinear models.
o Documentation update.
o A data set has been added to the package : the lesbian data set.
o Documentation update.
o Fonction closedpMS.t() has been added to the package. MS stands for Model Selection. This function fits every possible hierachical loglinear model for a given data set and for given constraints (see closedpMS.t() documentation for details).
o The name of a hierarchical loglinear model can now be given as 'mX' argument to a closedpCI function (see closedpMS.t() documentation to learn about the syntax of hierarchical loglinear model name in Rcapture)
o Rcapture do not use glmRcapture(), an internal version of glm(), anymore. For better maintainability, it is back to calling glm() directly. To avoid warnings from fitting the NULL model, the internal function glm.call() asks glm() to remove the intercept from the model, but an intercept is added to the model manually through an explanatory variable taking a constant value of 1. Because of this trick, the NULL deviance might not be exactly correct, but it is not used by Rcapture.
o Functions calling glm() can now pass arguments to glm() through the special argument ... (added to the closedp functions and closedp.bc()). The function closedp.Mtb() has also a new argument ..., to pass arguments to optim() as the closedpCI functions already do.
o Improvement of the warnings trace when eta parameters are removed from an heterogeneous Chao's lower bound model: the warning messages now indicate from which fit it comes.
o Non-integer capture frequencies in input data set are now accepted, but they still generate warnings from glm().
o A model design matrix with fewer rows than columns now produce a warning instead of an error, but the closedpCI functions do not calculate a multinomial profile likelihood confidence interval in that case.
o The data set 'catb' has been renamed 'cbird'.
o Closed population functions now calculate asymptotic bias for abundance estimators.
o Closed population functions now calculate a Bayesian Information Criterion (BIC) for the fitted models.
o The way Rcapture treats warnings and errors produced while fitting a closed
population model has been revised :
o If an error occurs while executing a function fitting only one model
(closedpCI functions, closedp.bc(), closedp.Mtb()), the execution is
stopped and the error message is printed (usual behavior in R, no change
here). However, if an error occurs while fitting a model in a call to
a function fitting more than one model (closedp functions), the
execution of the call is not stopped anymore. Instead, the row in the
results table for the problematic model is filled with NA and the
error message is stored in a new output value called 'glm.err'.
o Warning messages, if any, are stored in an output value called
'glm.warn', 'fit.warn' or 'optim.warn', depending on the function. In
previous versions of Rcapture, warnings produced when fitting a model
with optim() (normal heterogeneous model or the Mtb model) were not
stored. They were printed in the console. However, warnings from calls to the glmRcapture() function, used to fit any other model, were stored since version 1.3-1. o A new column called 'infoFit' has been added to the 'results' table. It contains a numerical code giving information about errors or warnings encountered (see the Rcapture documentation for details). o The output value 'converge' of closedp functions and closedp.bc() has been removed since information about convergence is now given through the column 'infoFit' of the 'results' table. In addition, in case of non convergence, the symbol '**' is not added anymore to the name of the model and no more note is added to the print.
o closedpCI functions now keep a trace of errors and warnings produced while calculating the multinomial profile likelihood confidence interval. They are stored in 'CI.err' and 'CI.warn'. A new column in the output value 'CI', named 'infoCI', gives information about errors or warnings encountered (see the closedpCI documentation for details).
o closedp.bc() can now perform a correction for negative eta parameters in the Mth Chao lower bound model, just like any other closed population function already did. This correction is done by default.
o Argument modifications for new features (described above) or consistency with closedpCI functions: o closedp.bc(): 'theta' must now be input through the new argument 'h.control', which also accepts a 'neg' element to control the correction for negative eta parameters in the Mth Chao lower bound model. o closedp.Mtb(): a new argument 'method' as been added to allow the user to modify the optim() argument 'method'.
o Output values modifications for new features (described above) or consistency: o closed population functions : 'results' contains three new columns, named 'bias', 'BIC' and 'infoFit'. o closedp functions: 'converge' has been removed, 'glm.err' has been added. o closedp.bc(): 'converge' has been removed, 'neg.eta' has been added. o closedp.Mtb(): 'fit' has been renamed 'optim', 'optim.warn' has been added. o closedpCI functions: 'glm.warn' has been renamed 'fit.warn', 'CI.err' and 'CI.warn' have been added, 'CI' contains a new column named 'infoCI'.
o The vignette from an article in the Journal of Statistical Software has been removed because it was outdated.
o Reorganisation of the internal code for closedpCI functions.
o Output values added for consistency: o 't' and 't0' in closedp.bc(), o 't' and 'fit' in closedp.Mtb().
o Bug fixes: o closedpCI functions now work with a formula containing only one term (including the intercept only model), o profileCI() now works with model Mt and 2 capture occasions.
o The data set 'ill' has been added to the package to illustrate the new feature t=Inf for captures occurring in continuous time.
o The internal function glm.call() used to call glm() from the 'stats' package to fit closed populations models. It now calls glmRcapture(), a new internal function, which is a modify version of glm() that does not calculate a NULL deviance when the model has an offset. This NULL deviance is not used by Rcapture functions. Therefore, glm.fit() is now called only once per model fit and there is no more confusion about which call of glm.fit() generated a warning.
o The warnings produced by the glmRcapture() function are no longer suppressed
for closed population models. Instead, they are stored in the output value
'glm.warn' (applies to the 'closedp' functions, the 'closedpCI' functions and
the function closedp.bc()). This new feature made the 'trace' argument of the
'closedp' functions useless. Therefore, it has been removed.
o When a model does not converge, its name is followed by ** in the output 'results' table. The print() method explains this symbol, but warnings are not printed anymore for non-convergence since they were redundant. The warning for non-convergence is stored in 'glm.warn' like any other warning.
o The 'closedpCI' functions now generate an error if unused arguments are given. This error was not generated in version 1.3 because of the addition of a ... argument to the 'closedpCI' functions (used to pass argument to optim()).
o Diagnostic messages are now written in a consistent style.
o Notes are not printed anymore when eta parameters are set to zero for Chao's lower bound models.
o The argument 'mX' of the closedpCI.t() function now accepts a formula (see the documentation for details about how to correctly write this formula).
o Minor change to the name of the loglinear parameters if a matrix is given as 'mX' argument: they are now named "mX." where "" is the name of the 'mX' columns if the given 'mX' has columns names, otherwise "*" is the number of the 'mX' columns.
o A new argument has been added to the 'closedpCI' functions, 'fmaxSupCL', which
allows to change the upper end point of the interval to be searched by uniroot() to find the upper bound of the multinomial profile likelihood confidence interval.
o Bug fixes in the public functions closedp.bc() and openp() and in the internal functions valid.t(), valid.X() and valid.mname().
o Normal heterogeneous models have been added to the package. They can be fitted with the closedpCI.t() and closedpCI.0() functions by giving the value "Normal" to the argument 'h'. This type of model is fitted with optim() instead of glm().
o For closedpCI.t() and closedpCI.0(), the argument 'theta' and 'neg' have been moved to the new 'h.control' argument. This is a list accepting elements named 'theta', 'neg', 'initcoef', 'initsig' and 'method'. The last three elements concern normal heterogeneous models.
o For closedpCI.t() and closedpCI.0(), the output value 'glm' has been renamed 'fit' since the function glm() is not used to fit normal heterogeneous models. For these models, 'fit' contains various output relative to the model fitted with optim() (see documentation).
o The print(), boxplot() and plot() methods for objects of class 'closedpCI' has been modified to deal with the new normal heterogeneous models.
o descriptive(), closedp.0() and closedpCI.0() now accept the value Inf for
the argument 't'. It indicates that captures occur in continuous time (see the help page 'Rcapture-package'). o Because of this change, the default value of 't0' for closedp.0 and closedpCI.0() is now NULL instead of t. (When t=Inf, by default the frequencies considered for the model fit are those for the units captured between 1 and tmax times, where tmax is the larger number of captures observed.)
o The impact of the argument 't0' has been changed in closedp.0(), closedpCI.0() and closedp.bc(). If t0 < t, there is no longer columns added to the design matrix of the loglinear model. Instead, observations are removed from the design matrix, the response vector and the offset vector used to fit the model. This change affects the AIC criteria for every model. For the Mh Chao model only, it also affects the degrees of freedom and the deviance.
o The code has been improved and clarified in the following ways: o Blocks of code were kept in quotes. The code has been modified in order to eliminate these quotes. Instead, many internal functions have been created. o Argument validations and default values have been standardized. o In the functions argument definition, 't' and 'mname' had no default value. Their default value is now NULL to make it clear that these arguments are not mandatory, except for 't' when dtype="nbcap". o The default value for 'h' is now NULL since when ones ask for a model without heterogeneity, this argument is no used. Also, the vector given in the function definition did not include every possible values for 'h' since it can be a function. o plotCI() is no longer a method. It is now a function like uifit().
o The documentation has been improved and updated according to the code modifications.
o Tests with 'testthat' have been added to the package in the folder 'inst/tests'.
o A file Rcapture-Ex.Rout.save has been added to the package source in the folder tests/Examples. Now R CMD check compares the output from the package examples to this file and reports any differences.
o Minor bug fixes and changes in the documentation.
o Minor modification to the package vignette : A date has been added in the title of the document 'RcaptureJSS'.
o The package vignette is now in the folder 'vignettes'. Only the PDF is left in the folder 'inst/doc'.
o The functions closedp.mX(), closedp.h() and profile.CI() are now deprecated. They are replaced by the new function closedpCI.t() which simultaneously fits a loglinear model specified by the user and computes the multinomial profile likelihood confidence interval for the abundance estimation.
o closedpCI() uses the R functions optimize() and uniroot() to obtain the profile likelihood confidence interval. The deprecated function profile.CI() used its own homemade algorithm.
o The new method plotCI(), defined for the class 'closedpCI', allows to plot a profile likelihood confidence interval. This plot used to be generated automatically by profileCI().
o The plot() method for class 'closedpCI' traces the scatterplot of the Pearson residuals in terms of fi (number of units captured i times) for the customized model.
o closedp() is now named closedp.t().
o closedp.t() now identifies the non-convergent model in the print. Also, its returned list contains an element named 'converge'. This is a logical vector indicating for each model whether it converged or not.
o The new argument 'trace' of closedp.t() allows to print a note for each
model while the function runs. It is useful to identify which model is
associated to a warning.
o In closedp.t(), some bugs were fixed in the correction for negative eta parameters in Chao's models when 'neg=TRUE'
o In closedp.t(), the estimation of capture probabilities for Mth models
was incorrect, it has been corrected.
o In closedp.t(), the returned list has changed. It now has only one glm
element, this element is a list of the glm objects for each model. Also
the output now features an element named 'parameters' which is a list of
capture-recapture parameter estimates for each model.
o The new plot() method for class 'closedp' produces scatterplots of the Pearson residuals in terms of fi (number of units captured i times) for the heterogeneous models Mh Poisson2, Mh Darroch and Mh Gamma3.5 if they converged.
o The boxplot() method for class 'closedp' does not trace boxplots for the non-convergent models anymore.
o A new heterogeneity model has been added to the package : the gamma model. This means that closedp() has two more models in its output table, Mh Gamma3.5 and Mth Gamma3.5. Also the 'h' argument of closed population functions and the 'vh' argument of robust design functions accept the value "Gamma".
o The 'a' argument of closed population functions and the 'va' argument of robust design functions are renamed 'theta' and 'vtheta' because the gamma model was added to the package and 'a' was referring to the Poisson heterogeneity model. 'theta' is a more general notation.
o Functions for closed populations now work with only 2 capture occasions (non-helpful errors were previously produced). In that case, only models M0, Mt and Mb can be fitted.
o The new functions closedp.0() and closedpCI.0() are equivalent to closedp.t() and closedpCI.t() but they fit model using the number of units capture i times instead of the frequencies of the observable capture histories. Consequently, they fit fewer models than the .t functions, but they work with much larger data set.
o closedp.0() has the same methods as closedp.t() (print(), plot() and boxplot()), closedpCI.0() has the same methods as closedpCI.t() (print(), plotCI(), plot() and boxplot()).
o The new .0 functions accept a new data format. The argument 'dtype', if set to "nbcap", allows the user to give the numbers of captures instead of the full capture histories.
o In the new .0 functions, the argument 't' is required if 'dtype' takes the value "nbcap". It represents the number of capture occasions in the experiment.
o closedp.bc() now computes bias corrected estimates for a model specified using the arguments 'm', 'h' and 'theta' as with the 'closedpCI' functions.
o Bias correction is now possible for any customized Mh model.
o For models 'M0' and 'Mh', closedp.bc() accepts a data matrix 'X' in the format 'dtype' equals to "nbcap".
o In closedp.bc(), the computations for model Mt have changed. The
abundance estimate for the Mt model when t=2 has Chapman bias correction and a standard error derived from Seber and Wittes variance estimate.
For t>2, closedp.bc() implements the bias correction of Rivest and Levesque (2001). The estimate for N and its variance are calculated by solving an estimating equation as proposed in Seber (1982), not by fitting a Poisson regression. This approach works for large values of t.
o The 't0' argument of closedp.0(), closedpCI.0() and closedp.bc() allows to fit models considering only the frequencies of units captured 1 to t0 times. The frequencies of units caught more than t0 times are given their own parameters in the loglinear model.
o descriptive() now accepts the new data formats, therefore it has two new arguments: 'dtype' and 't'.
o The plot method for class 'descriptive' now traces only the fi plot if 'dtype' took the value "nbcap" in the call to descriptive().
o The documentation for periodhist() is now more general, it talks about merging capture occasions.
o The new argument 'drop' of perdiohist() allows to omit from the output data set the unobserved capture histories (frequency of 0).
o histpos.0() now works when 'vt' is a scalar.
o histfreq.t() and histfreq.0() are now internal functions.
o Some bugs were fixed in the robustd.t and robustd.0 functions : they now work when vh contains R functions and when the data set contains only two primary periods.
o A NAMESPACE has been added to the package, therefore internal functions are now hidden (e.g. Xclosedp(), Xomega() and Zdelta())
o The documentation has been updated.
o The paper in inst/doc is now a vignette.
o Bug fixes for R 2.7.0.
o First CRAN release of the Rcapture package.