delicatessen.estimating_equations.dose_response.ee_4p_logistic

ee_4p_logistic(theta, X, y)

Estimating equations for the 4-parameter logistic model (4PL). The estimating equations are

\[\begin{split}\sum_{i=1}^n \begin{bmatrix} -2 (Y_i - \hat{Y}_i) (1 - 1/(1 + \rho)) \\ 2 (Y_i - \hat{Y}_i) (\theta_3 - \theta_0) \frac{\theta_2}{\theta_1} \frac{\rho}{(1 + \rho)^2} \\ 2 (Y_i - \hat{Y}_i) (\theta_3 - \theta_0) \log(D_i / \theta_1) \frac{\rho}{(1 + \rho)^2} \\ 2 (Y_i - \hat{Y}_i) (1 / (1 + \rho))) \end{bmatrix} = 0\end{split}\]

where \(R_i\) is the response of individual \(i\), \(D_i\) is the dose, \(\rho = \frac{D_i}{\theta_1}^{\theta_2}\), and \(\hat{Y_i} = \theta_0 + \frac{\theta_3 - \theta_0}{1+\rho}\).

Here, theta is a 1-by-4 array. The first theta corresponds to lower limit (\(\theta_0\)), the second corresponds to the effective dose (ED50) (\(\theta_1\)), the third corresponds to the steepness of the curve (\(\theta_2\)), and the fourth corresponds to the upper limit (\(\theta_3\)).

Parameters

theta (ndarray, list, vector) – Theta in this case consists of 4 values. In general, starting values \(>0\) are better choices for the 4PL model
X (ndarray, list, vector) – 1-dimensional vector of n dose values.
y (ndarray, list, vector) – 1-dimensional vector of n response values.

Returns

Returns a 4-by-n NumPy array evaluated for the input theta.

Return type

array

Examples

Construction of a estimating equation(s) with ee_4p_logistic should be done similar to the following

>>> from delicatessen import MEstimator
>>> from delicatessen.data import load_inderjit
>>> from delicatessen.estimating_equations import ee_4p_logistic

For demonstration, we use dose-response data from Inderjit et al. (2002), which can be loaded from delicatessen directly.

>>> d = load_inderjit()   # Loading array of data
>>> dose_data = d[:, 1]   # Dose data
>>> resp_data = d[:, 0]   # Response data

Defining psi, or the stacked estimating equations

>>> def psi(theta):
>>>     return ee_4p_logistic(theta=theta, X=dose_data, y=resp_data)

The 4PL model and others are harder to solve compared to other estimating equations. Namely, the root-finder is not aware of implicit bounds on the parameters. To reduce non-convergence issues, we can give the root-finder good starting values.

For the 4PL, the upper limit should always be greater than the lower limit. Second, the ED50 should be between the lower and upper limits. Third, the sign for the steepness depends on whether the response declines (positive) or the response increases (negative). Finally, some solvers may be better suited to the problem, so try a few different options.

Here, we use some general starting values that should perform well in many cases. For the lower-bound, give the minimum response value as the initial. For ED50, give the mid-point between the maximum response and the minimum response. The initial value for steepness is more difficult. Ideally, we would give a starting value of zero, but that will fail in this example. Giving a small positive starting value works in this example. For the upper-bound, give the maximum response value as the initial. Finally, we use the lm solver.

Note

To summarize the recommendations, be sure to examine your data (e.g., scatterplot). This will help to determine the initial starting values for the root-finding procedure. Otherwise, you may come across a convergence error.

>>> estr = MEstimator(psi, init=[np.min(resp_data),
>>>                              (np.max(resp_data)+np.min(resp_data)) / 2,
>>>                              (np.max(resp_data)+np.min(resp_data)) / 2,
>>>                              np.max(resp_data)])
>>> estr.estimate(solver='lm')

Inspecting the parameter estimates, variance, and confidence intervals

>>> estr.theta
>>> estr.variance
>>> estr.confidence_intervals()

Inspecting the parameter estimates

>>> estr.theta[0]    # lower limit
>>> estr.theta[1]    # ED(50)
>>> estr.theta[2]    # steepness
>>> estr.theta[3]    # upper limit

References

Ritz C, Baty F, Streibig JC, & Gerhard D. (2015). Dose-response analysis using R. PloS One, 10(12), e0146021.

An H, Justin TL, Aubrey GB, Marron JS, & Dittmer DP. (2019). dr4pl: A Stable Convergence Algorithm for the 4 Parameter Logistic Model. R J., 11(2), 171.

Inderjit, Streibig JC, & Olofsdotter M. (2002). Joint action of phenolic acid mixtures and its significance in allelopathy research. Physiologia Plantarum, 114(3), 422-428.