Add nlmixr_formula()

[billdenney]

Fix #6.

What it does is it implements a formula interface that allows nlmixr2 models to be estimated when all that is required is an algebraic formula. It takes inspiration from lme4::nlmer() for the way to define the formula to use.

The current state of the PR does not have testing, and documentation needs expansion. There are some design decisions that I think are worth vetting, too.

The main design decisions that are questionable to me are:

• Is there a better/simpler formula interface to use that incorporates fixed and random effects? What about automated modeling of parameters?
• How should random effects be defined? Should they be required to be different than fixed effects or should the system automatically generate the different names for the user?
• Can there be more than one type of random effect? In other words must it be just ID or are other columns also acceptable?
• There's no way to specify the starting random effect variability; it simply starts at 1. Should an interface be added for that?
• Is the way that it handles factors when generating multiple fixed effects good? Is there a better way to generate them?
• Should it handle more types of automatic parameterization than just factors? (That can be a downstream option.)

[mattfidler]

One minor comment, please adopt the style used in the rest of the package. I follow more or less the bionconductor style guide:

https://contributions.bioconductor.org/r-code.html

[mattfidler]

Mostly I really want a consistent feel from the user and developer perspective. If we follow a consistent style guide then this would be easier to achieve

[mattfidler]

Can there be more than one type of random effect? In other words must it be just ID or are other columns also acceptable?

Eventually possible right now not possible

[mattfidler]

Is the way that it handles factors when generating multiple fixed effects good? Is there a better way to generate them?

This perhaps should be generalized to the rest of nlmixr?

[billdenney]

I'm happy to modify the style. My default style is snake_case, and I needed this pretty quickly for something else. I also thought that there may be significant modifications after considerations for the ways that it works, so I'm guessing there will be some pretty big rework before it's done.

I don't see a simple way to generalize the factor handling to the rest of nlmixr2, but I'd be interested to think about it more and hear thoughts of how it could be done. The way that the nlmixr2 ini() works right now, I don't readily see a way to make it work with factors. I could imagine a few different ways that it could be augmented, but at that point, I worry that the UI would start to get cumbersome. Balancing the feature with the UI needs should be discussed in depth.

A few ideas of how I considered it were:

• Assignment with a vertical bar in the ini block could assign the same initial estimate to all factor levels (e.g. a <- fixed(1, 2, 3) | STUDYID). That would parallel what is done for random effects with fixed effects pretty simply. But, you would now have to watch for a somewhat subtle difference between <- and ~ which already trips me up sometimes when writing the models.
• Only support it with post-processing of a model (but that doesn't feel good since I think you should have all of the flexibility in the main model syntax).

[billdenney]

FYI, this PR update only changes things around the edges (documentation issues, mainly). I'll go through the coding style after the underlying functionality has been reviewed.

[billdenney]

Another thought for generating parameters for a model with a fixed effect per factor level. Should we go all the way down the path of generating orthogonal contrasts for estimation and then back-transforming them? That seems like it would be mathematically the best (in most scenarios), but it gets a lot more cumbersome.

Or, maybe that is already sufficiently covered by nlmixr2extra::preconditionFit().

[mattfidler]

Well, all factors are mu referenced so perhaps simply adding them to the linear model for covariates would be fine. If that is the case , the initial estimate would be mostly irrelevant. This speaks to adding my referenced covariates to focei like nonmem....

[billdenney]

I don't understand "all factors are mu referenced".

[billdenney]

It would be good to switch to using the reformulas package for formula processing. https://cran.r-project.org/package=reformulas

[mattfidler]

This is entirely up to you

[billdenney]

@mattfidler, I think that this is ready to merge. Do you want to take one more look?

[Copilot]

Pull Request Overview

This PR implements a formula interface for nlmixr2 that allows algebraic models to be estimated using a simplified formula syntax similar to lme4::nlmer(). The interface enables users to specify models without writing full nlmixr2 functions, making it easier to fit simple algebraic solutions.

Key changes:

• Adds nlmixrFormula() function with formula parsing and model generation capabilities
• Implements automatic parameter expansion for factor variables
• Provides support for mixed-effects models with random effects grouping

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
R/nlmixrFormula.R	Main implementation with formula parser and model setup functions
tests/testthat/test-nlmixrFormula.R	Comprehensive unit tests for formula parsing and parameter expansion
man/*.Rd	Documentation files for the new functions and internal helpers
vignettes/nlmixrFormula.Rmd	User guide demonstrating the formula interface with examples
NAMESPACE	Exports the new nlmixrFormula() function
DESCRIPTION	Updates R dependency and adds vignette builder

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[mattfidler]

This does look fine to me.

I don't exactly follow what param is supposed to be doing here, and there seems to be no examples to help me with this in the vignette.

I was also trying to see if there was a way to take out nlmixrFormula() and replace it with nlmixr()

[mattfidler]

One last question -- do you want to support iov too?

[mattfidler]

Like the rest of the nlmixr2 documentation, I have changed addErr to addSd since this is a bit more clear.

I have added a nlmixr2() method for formula that uses nlmixr2Formula.

Still haven't done anything about IOV

[mattfidler]

If you are OK with the changes I made, I am OK merging this.

[billdenney]

I like all your changes. Let me add how to use param in the vignette on top of your changes.

[Copilot]

Pull Request Overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

tests/testthat/test-nlmixrFormula.R:1

• The comment is incomplete and ends abruptly with 'so that'. Complete the explanation or remove the incomplete comment.

test_that(".nlmixrFormulaParser breaks the formula up into the correct bits", {

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The data parameter is included in the function signature but is not documented in the roxygen comment above, and it's not used in the function body. Either remove the unused parameter or document it properly.

Suggested change

	#' @param data The data used in the model
	#' @return the interior of the model()
	#' @keywords Internal
	#' @noRd
	#' @author William Denney
	.nlmixrFormulaSetupModel <- function(start, predictor, residualModel, predictorVar="value", data) {
	#' @return the interior of the model()
	#' @keywords Internal
	#' @noRd
	#' @author William Denney
	.nlmixrFormulaSetupModel <- function(start, predictor, residualModel, predictorVar="value") {

[Copilot]

[nitpick] This line performs multiple nested operations that could be hard to follow. Consider breaking it into separate steps with descriptive variable names for better readability.

Suggested change

	paramLabel <- names(rev(sort(summary(data[[param]]))))
	paramSummary <- summary(data[[param]])
	sortedParamSummary <- sort(paramSummary)
	reversedSortedParamSummary <- rev(sortedParamSummary)
	paramLabel <- names(reversedSortedParamSummary)

[Copilot]

Missing space before parenthesis in '4(when'. Should be '4 (when' for proper formatting.

Suggested change

	# Simulate the equation y = 3*x + 4(when z = 'a') or 6(when z = 'b') with normally-distributed residual error
	# Simulate the equation y = 3*x + 4 (when z = 'a') or 6 (when z = 'b') with normally-distributed residual error

[mattfidler]

Is this ready for review/merging Bill?

[billdenney]

Not quite yet. There are some issues with param that I need to fix.