nls( )

Fit non-linear models to data. nls() is part of base R (stats package).

Original Documentation ↗ R Documentation ↗

Required Library

# nls() is in base R (stats), loaded by default — no package installation needed

Syntax

nls(formula, data = df, start = list(param1 = value1, param2 = value2))

nls() fits non-linear models by estimating parameter values that best match the data. Unlike lm(), you write the full model equation directly in the formula.

Use nls() when your data follows a curved relationship that a straight line cannot describe well. Typical examples in pharmacy include dose-response curves (e.g., sigmoidal Emax models), dissolution profiles (e.g., Weibull models), and saturation/enzyme kinetics (e.g., Michaelis-Menten).

nls() needs reasonable starting guesses in start = list(...). They do not need to be exact, but should be in the right range.

Model Used In These Examples

For simplicity, the examples below use a 3-parameter sigmoidal model with fixed slope (Hill = 1):

\[ y = \text{Bottom} + \frac{\text{Top} - \text{Bottom}}{1 + (\text{EC}_{50}/x)} \]

Bottom and Top are the lower and upper plateaus, and EC50 is the concentration where response is halfway between them.

Examples

Fit a simple dose-response curve
Extract EC50 from the fitted model
Predict and plot the fitted non-linear curve

The points are your measured data. The line is built from many model predictions across a fine x-grid, then added with geom_line().

Evaluating Model Fit

Fitting a curve is only useful if it actually describes the data well. A few diagnostics help you judge that.

  • Residual standard error — how far, on average, the observed values fall from the fitted curve (smaller is better, in the units of your response).
  • Parameter estimates and standard errors — from summary(); large standard errors relative to the estimate suggest the parameter is poorly identified by your data.
  • Residual plot — residuals should scatter randomly around zero with no obvious curve or trend. A pattern means the model shape may be wrong.
  • Convergence — nls() should finish without a “singular gradient” or “convergence failure” error; if it does, your start values may need adjusting.
Check the model summary

summary() reports parameter estimates, standard errors, and the residual standard error.

Plot residuals to check for patterns

residuals() gives the difference between observed and predicted values for each point. Random scatter around zero suggests a good fit; a curve or trend suggests the model doesn’t match the data’s shape.

Argument Overview

Required arguments must be included when using a function while optional arguments can be included on demand.

formula — non-linear model equation formula Required

Defines the model you want to fit. Write the response on the left and the full non-linear expression on the right.

response_pct ~ Bottom + (Top - Bottom) / (1 + (EC50 / dose_uM))

Data Types: formula

data — data frame with model variables data frame | tibble Optional

Data source used to evaluate the variables in the formula.

nls(formula = ..., data = dose_response, start = ...)

Data Types: data.frame | tibble

start — starting values for parameters named list Required

Named list with initial guesses for all unknown parameters. nls() uses these values as the starting point for optimisation.

start = list(Bottom = 0, Top = 100, EC50 = 5)

Data Types: named list of numeric values