THIS IS THE CHANGELOG OF THE "bgw" PACKAGE Note that this approach to documenting changes could be changed, depending on advice or input from CRAN or others CHANGES IN VERSION 0.1.5 (2026-11-10) * [1] During a detailed review and testing using Apollo models and datasets, the fact that the "finite difference" branch in bgw_mle.R had been modified to exclude dynamic scaling factors was brought to light. This was a loose end from the original development effort when we were not using dynamic scaling. Dynamic scaling has now been restored in the finite-difference branch. * [2] A new argument, calcJ_type, has been added to bgw_mle. It indicates what the matrix returned by calcJ contains: "probability" (derivatives of R_i, the model probabilities) or "log_probability" (derivatives of log(R_i)). Earlier versions of bgw assumed derivatives of log(R_i), which is what Apollo provides. To maintain backward compatibility, if calcJ is supplied without calcJ_type, "log_probability" is assumed. The argument was added at the end of the argument list, so existing calls are unaffected. With calcJ_type = "probability", calcR is no longer called each time calcJ is evaluated, which saves one likelihood evaluation per iteration. * [3] The matrix returned by calcJ may now be either n x p or p x n; bgw determines which from its dimensions. In the rare case n = p, the matrix is read as n x p. If calcJ returns a vector, or a matrix of the wrong dimensions, bgw stops with an error message. (Previously a p x n matrix would have been silently misread.) * [4] The documentation for calcJ has been corrected. Earlier versions stated that calcJ should return a p x n matrix of derivatives of R, whereas the code expected an n x p matrix of derivatives of log(R). See the new subsection "Forms of the Jacobian (calcJ)" under Details in the help for bgw_mle. * [5] The option bgw_settings[["userRequestIndLevelGradients"]] now returns an n x p matrix whose row i is d log(R_i)/d beta at the final value of beta. It is available with both analytic (calcJ) and finite-difference derivatives, and requesting it does not affect the estimates or other results. * [6] Based on numerical testing, we have changed the default starting values for the scaling vector to be a vector of ones in the case where analytic derivatives are available. * [7] Bug fix: with finite-difference derivatives and a named betaStart, the last element of the returned estimate could be perturbed by the finite-difference step size (a relative error of about 1e-8). * [8] Minor documentation corrections: the stated defaults for maxIterations (200) and maxFunctionEvals (300) now match the values used by bgw. The help for the returned values estimate and maximum now states that they are always returned; whether the search converged is indicated by code and message. * [9] Only bgw_mle is now exported. The other R functions in the package (bgw_mle_setup, bgw_drglg, bgw_itsum, bgw_checkSetting, bgw_writeIterations) are internal and no longer have help pages. They were never intended to be called directly by users. * [10] Minor bug fixes in bgw_mle: supplying only invalid setting names in bgw_settings no longer causes an internal error; the message for an invalid setting value now shows the default value that will be used (previously it repeated the invalid value); and hessianMethodAttempted, described in the help, is now included in the returned model object. * [11] Bug fix: the Fortran code could overwrite R objects in place. With an unnamed betaStart, the starting values held by the caller could be replaced by the estimates (most often when calcJ was supplied), so that a later run reusing the same vector would start from those estimates, and the returned betaStart could also be wrong. The Fortran now works on private copies of its arrays. A named betaStart, which is what Apollo provides, was not affected. * [12] Values of maxIterations or maxFunctionEvals too large to be held as an integer (above 2,147,483,647, or Inf) are now rejected with an error message. In addition, bgw now stops with an error message if a model is too large for the work vector v to be indexed by an integer. * [13] New option bgw_settings[["userRequestModelObject"]]. If TRUE, or if maxIterations is 0, no estimation is performed and a model object evaluated at betaStart is returned, with code 20 and a variance-covariance matrix based on the BHHH matrix (NULL if singular). vcHessianMethod must be "bhhh" or "none" in this case. * [14] Some returned values were renamed. vcHessianConditionNumber was misnamed, since it is the reciprocal of the condition number; it is now vcHessianRecipCondBGW. The old name remains for now, but is deprecated. vcVec and hessianMethodUsed are now vcVecBGW and hessianMethodUsedBGW, and hessianMethodAttempted (new in this version) is hessianMethodAttemptedBGW. The printed description of this quantity was corrected in the same way. * [15] New options writeIterGradient and writeIterScaleVec write the gradient of the log-likelihood and the scale vector at each iteration to "modelName_gradients.csv" and "modelName_scaleVecs.csv", respectively. These and "modelName_iterations.csv" now share one layout: the parameter names (or beta1, beta2, ...), logLike, and two new columns, Iteration and ItType. Appending to an existing file written in the old layout keeps that layout. * [16] Bug fixes: writeIter no longer fails when betaStart has no names, and printing no longer fails when a gradient cannot be computed. When estimation fails at the start, for example because the gradient cannot be computed, the returned code and message now identify the failure, and the returned log-likelihood is its value at betaStart (previously it was 0). * [17] Bug fixes for failed evaluations. If calcJ returned NA, NaN or Inf, even in a single element, bgw did not stop, but evaluated calcR until the function evaluation limit was reached. It now stops with code 65 ("Gradient could not be computed"). If the gradient cannot be computed after the start (with calcJ, or when finite-difference steps fail in both directions), the last iterate at which it could be computed is returned, with its log-likelihood, gradient and scale vector. Previously, with finite differences, the new point was returned together with the log-likelihood of the previous one. The iteration files contain no row for such an iterate. In addition, calcR is now rejected at betaStart if it returns Inf or a value <= 0, not only NA or NaN, and during the search Inf and negative values are treated in the same way as NA. CHANGES IN VERSION 0.1.4 (2026-02-03) * [1] An option was added to bgw_settings to allow the user to request that individual-level gradients at the final value of beta be returned with the model. By this, we mean a p x n matrix that contains elements of the form dlog_lik_j/dBeta_i, where j indexes columns and i indexes rows. The default is FALSE. * [2] Some of the items in the bgw_message_table were modified by appending the terms '(favorable)' or '(unfavorable)' to clarify for the user the nature of the outcome of the search. For example, 'Relative function convergence' is a favorable outcome, and 'Singular convergence' is an unfavorable outcome. CHANGES IN VERSION 0.1.3 (2024-03-27) * [1] CRAN Package Check produced errors for two Linux OS's (apparently due to changes in Fortran compilers). CRAN Team and Prof. Brian Ripley provided clarification and advice on the issues via email ( via email (18 March, 2024). We made multiple changes to address the list of issues they describe. Whether these suffice awaits repeating the checks at CRAN (since I do not use these Linux platforms). * [2] Minor changes and bug fixes were made to bgw_mle.R. These changes ensure that 'silent mode' performs properly. Other changes fix a bug that was preventing the use of the option bgw_settings[["scalingMethod"]] = "none". CHANGES IN VERSION 0.1.2 (2023-07-10) * Two main changes in this version are due to (1) a change in CRAN fortran requirements, and (2) the need to add an option for user-provided scaling. * [1] A change in CRAN requirements was communicated from Prof. Brian Ripley via email (19 June, 2023), which disallows the use of GNU language extensions. The test is based on including the compiler option --std=f2008. Specifically, the function "isnan" is regarded as a gfortran extension relative to this standard. Suggestions were to use an old approach (that we originally were using), or to choose something that satisfies the f2003 standard. We have elected to include the ieee arithmetic module and use the function ieee_is_nan(x). If this does not meet the requirement, we will need to make changes and resubmit. * [2] The option for user-provided scaling has been added, so the options are now: "adaptive", "none", and "userScaling", where the default is "adaptive". For the user to execute this successfully, they must modify two elements of bgw_settings: bgw_settings["scalingMethod"] must be set to "userScaling", and bgw_settings["userScaleVector"] must be set to a correctly specified scaling vector. For additional information, see the documentation for "bgw_mle." CHANGES IN VERSION 0.1.1 (2023-04-3) * The original version did not include options for scaling. (A scale vector of 1's was the hard-wired option.) This version allows for two scaling options: "adaptive" and "none". (The later corresponds to using a vector 1's.) The default is "adaptive," which is the original default in the Fortran version. For additional information, see the documentation for "bgw_mle."