Dose Response Curve Fitting (thunor.curve_fit)

exception thunor.curve_fit.AAFitWarning
exception thunor.curve_fit.AUCFitWarning
exception thunor.curve_fit.DrugCombosNotImplementedError

This function does not support drug combinations yet

class thunor.curve_fit.HillCurve(popt)

Base class defining Hill/log-logistic curve functionality

null_response_fn(axis=None, dtype=None, out=None, keepdims=<no value>, *, where=<no value>)

Compute the arithmetic mean along the specified axis.

Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. float64 intermediate and return values are used for integer inputs.

Parameters:
  • a (array_like) – Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

  • axis (None or int or tuple of ints, optional) –

    Axis or axes along which the means are computed. The default is to compute the mean of the flattened array.

    New in version 1.7.0.

    If this is a tuple of ints, a mean is performed over multiple axes, instead of a single axis or all the axes as before.

  • dtype (data-type, optional) – Type to use in computing the mean. For integer inputs, the default is float64; for floating point inputs, it is the same as the input dtype.

  • out (ndarray, optional) – Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See ufuncs-output-type for more details.

  • keepdims (bool, optional) –

    If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

    If the default value is passed, then keepdims will not be passed through to the mean method of sub-classes of ndarray, however any non-default value will be. If the sub-class’ method does not implement keepdims any exceptions will be raised.

  • where (array_like of bool, optional) –

    Elements to include in the mean. See ~numpy.ufunc.reduce for details.

    New in version 1.20.0.

Returns:

m – If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

Return type:

ndarray, see dtype parameter above

See also

average

Weighted average

std, var, nanmean, nanstd, nanvar

Notes

The arithmetic mean is the sum of the elements along the axis divided by the number of elements.

Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-precision accumulator using the dtype keyword can alleviate this issue.

By default, float16 results are computed using float32 intermediates for extra precision.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.mean(a)
2.5
>>> np.mean(a, axis=0)
array([2., 3.])
>>> np.mean(a, axis=1)
array([1.5, 3.5])

In single precision, mean can be inaccurate:

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.mean(a)
0.54999924

Computing the mean in float64 is more accurate:

>>> np.mean(a, dtype=np.float64)
0.55000000074505806 # may vary

Specifying a where argument:

>>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]])
>>> np.mean(a)
12.0
>>> np.mean(a, where=[[True], [False], [False]])
9.0
class thunor.curve_fit.HillCurveLL2(popt)
classmethod fit_fn(x, b, e)

Two parameter log-logistic function (“Hill curve”)

Parameters:
  • x (np.ndarray) – One-dimensional array of “x” values

  • b (float) – Hill slope

  • e (float) – EC50 value

Returns:

Array of “y” values using the supplied curve fit parameters on “x”

Return type:

np.ndarray

classmethod initial_guess(x, y)

Heuristic function for initial fit values

Uses the approach followed by R’s drc library: https://cran.r-project.org/web/packages/drc/index.html

Parameters:
  • x (np.ndarray) – Array of “x” (dose) values

  • y (np.ndarray) – Array of “y” (response) values

Returns:

Four-valued list corresponding to initial estimates of the parameters defined in the ll4() function.

Return type:

list

class thunor.curve_fit.HillCurveLL3u(popt)

Three parameter log logistic curve, for viability data

classmethod fit_fn(x, b, c, e)

Three parameter log-logistic function (“Hill curve”)

Parameters:
  • x (np.ndarray) – One-dimensional array of “x” values

  • b (float) – Hill slope

  • c (float) – Maximum response (lower plateau)

  • e (float) – EC50 value

Returns:

Array of “y” values using the supplied curve fit parameters on “x”

Return type:

np.ndarray

classmethod initial_guess(x, y)

Heuristic function for initial fit values

Uses the approach followed by R’s drc library: https://cran.r-project.org/web/packages/drc/index.html

Parameters:
  • x (np.ndarray) – Array of “x” (dose) values

  • y (np.ndarray) – Array of “y” (response) values

Returns:

Four-valued list corresponding to initial estimates of the parameters defined in the ll4() function.

Return type:

list

max_fit_evals = None
static null_response_fn(_)

Compute the arithmetic mean along the specified axis.

Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. float64 intermediate and return values are used for integer inputs.

Parameters:
  • a (array_like) – Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

  • axis (None or int or tuple of ints, optional) –

    Axis or axes along which the means are computed. The default is to compute the mean of the flattened array.

    New in version 1.7.0.

    If this is a tuple of ints, a mean is performed over multiple axes, instead of a single axis or all the axes as before.

  • dtype (data-type, optional) – Type to use in computing the mean. For integer inputs, the default is float64; for floating point inputs, it is the same as the input dtype.

  • out (ndarray, optional) – Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See ufuncs-output-type for more details.

  • keepdims (bool, optional) –

    If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

    If the default value is passed, then keepdims will not be passed through to the mean method of sub-classes of ndarray, however any non-default value will be. If the sub-class’ method does not implement keepdims any exceptions will be raised.

  • where (array_like of bool, optional) –

    Elements to include in the mean. See ~numpy.ufunc.reduce for details.

    New in version 1.20.0.

Returns:

m – If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

Return type:

ndarray, see dtype parameter above

See also

average

Weighted average

std, var, nanmean, nanstd, nanvar

Notes

The arithmetic mean is the sum of the elements along the axis divided by the number of elements.

Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-precision accumulator using the dtype keyword can alleviate this issue.

By default, float16 results are computed using float32 intermediates for extra precision.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.mean(a)
2.5
>>> np.mean(a, axis=0)
array([2., 3.])
>>> np.mean(a, axis=1)
array([1.5, 3.5])

In single precision, mean can be inaccurate:

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.mean(a)
0.54999924

Computing the mean in float64 is more accurate:

>>> np.mean(a, dtype=np.float64)
0.55000000074505806 # may vary

Specifying a where argument:

>>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]])
>>> np.mean(a)
12.0
>>> np.mean(a, where=[[True], [False], [False]])
9.0
class thunor.curve_fit.HillCurveLL4(popt)
aa(min_conc, max_conc)

Find the activity area (area over the curve)

Parameters:
  • min_conc (float) – Minimum concentration to consider for fitting the curve

  • max_conc (float) – Maximum concentration to consider for fitting the curve

Returns:

Activity area value

Return type:

float

auc(min_conc)

Find the area under the curve

Parameters:

min_conc (float) – Minimum concentration to consider for fitting the curve

Returns:

Area under the curve (AUC) value

Return type:

float

ec(ec_num=50)

Find the effective concentration value (e.g. IC50)

Parameters:

ec_num (int) – EC number between 0 and 100 (response level)

Returns:

Effective concentration value for requested response value

Return type:

float

classmethod fit_fn(x, b, c, d, e)

Four parameter log-logistic function (“Hill curve”)

Parameters:
  • x (np.ndarray) – One-dimensional array of “x” values

  • b (float) – Hill slope

  • c (float) – Maximum response (lower plateau)

  • d (float) – Minimum response (upper plateau)

  • e (float) – EC50 value

Returns:

Array of “y” values using the supplied curve fit parameters on “x”

Return type:

np.ndarray

ic(ic_num=50)

Find the inhibitory concentration value (e.g. IC50)

Parameters:

ic_num (int) – IC number between 0 and 100 (response level)

Returns:

Inhibitory concentration value for requested response value

Return type:

float

classmethod initial_guess(x, y)

Heuristic function for initial fit values

Uses the approach followed by R’s drc library: https://cran.r-project.org/web/packages/drc/index.html

Parameters:
  • x (np.ndarray) – Array of “x” (dose) values

  • y (np.ndarray) – Array of “y” (response) values

Returns:

Four-valued list corresponding to initial estimates of the parameters defined in the ll4() function.

Return type:

list

class thunor.curve_fit.HillCurveNull(popt)
exception thunor.curve_fit.ValueWarning
thunor.curve_fit.aa_obs(responses, doses=None)

Activity Area (observed)

Parameters:
  • responses (np.array or pd.Series) – Response values, with dose values in the Index if a Series is supplied

  • doses (np.array or None) – Dose values - only required if responses is not a pd.Series

Returns:

Activity area (observed)

Return type:

float

thunor.curve_fit.fit_drc(doses, responses, response_std_errs=None, fit_cls=<class 'thunor.curve_fit.HillCurveLL4'>, null_rejection_threshold=0.05, ctrl_dose_test=False)

Fit a dose response curve

Parameters:
  • doses (np.ndarray) – Array of dose values

  • responses (np.ndarray) – Array of response values, e.g. viability, DIP rates

  • response_std_errs (np.ndarray, optional) – Array of fit standard errors for the response values

  • fit_cls (Class) – Class to use for fitting (default: 4 parameter log logistic “Hill” curve)

  • null_rejection_threshold (float, optional) – p-value for rejecting curve fit against no effect “flat” response model by F-test (default: 0.05). Set to None to skip test.

  • ctrl_dose_test (boolean) – If True, the minimum dose is assumed to represent control values (in DIP rate curves), and will reject fits where E0 is greater than a standard deviation higher than the mean of the control response values. Leave as False to skip the test.

Returns:

A HillCurve object containing the fit parameters

Return type:

HillCurve

thunor.curve_fit.fit_params(ctrl_data, expt_data, fit_cls=<class 'thunor.curve_fit.HillCurveLL4'>, ctrl_dose_fn=<function <lambda>>)

Fit dose response curves to DIP rates or viability data

This method computes parameters including IC50, EC50, AUC, AA, Hill coefficient, and Emax. For a faster version, see fit_params_minimal().

Parameters:
  • ctrl_data (pd.DataFrame or None) – Control DIP rates from dip_rates() or ctrl_dip_rates(). Set to None to not use control data.

  • expt_data (pd.DataFrame) – Experiment (non-control) DIP rates from dip_rates() or expt_dip_rates(), or viability data from viability()

  • fit_cls (Class) – Class to use for curve fitting (default: HillCurveLL4())

  • ctrl_dose_fn (function) – Function to use to set an effective “dose” (non-zero) for controls. Takes the list of experiment doses as an argument.

Returns:

DataFrame containing DIP rate curve fits and parameters

Return type:

pd.DataFrame

thunor.curve_fit.fit_params_from_base(base_params, ctrl_resp_data=None, expt_resp_data=None, ctrl_dose_fn=<function <lambda>>, custom_ic_concentrations=frozenset({}), custom_ec_concentrations=frozenset({}), custom_e_values=frozenset({}), custom_e_rel_values=frozenset({}), include_aa=False, include_auc=False, include_hill=False, include_emax=False, include_einf=False, include_response_values=True)

Attach additional parameters to basic set of fit parameters

thunor.curve_fit.fit_params_minimal(ctrl_data, expt_data, fit_cls=<class 'thunor.curve_fit.HillCurveLL4'>, ctrl_dose_fn=<function <lambda>>)

Fit dose response curves to DIP or viability, and calculate statistics

This function only fits curves and stores basic fit parameters. Use fit_params() for more statistics and parameters.

Parameters:
  • ctrl_data (pd.DataFrame or None) – Control DIP rates from dip_rates() or ctrl_dip_rates(). Set to None to not use control data.

  • expt_data (pd.DataFrame) – Experiment (non-control) DIP rates from dip_rates() or expt_dip_rates()

  • fit_cls (Class) – Class to use for curve fitting (default: HillCurveLL4())

  • ctrl_dose_fn (function) – Function to use to set an effective “dose” (non-zero) for controls. Takes the list of experiment doses as an argument.

Returns:

DataFrame containing DIP rate curve fits and parameters

Return type:

pd.DataFrame

thunor.curve_fit.is_param_truncated(df_params, param_name)

Checks if parameter values are truncated at boundaries of measured range

Parameters:
  • df_params (pd.DataFrame) – DataFrame of DIP curve fits with parameters from fit_params()

  • param_name (str) – Name of a parameter, e.g. ‘ic50’

Returns:

Array of booleans showing whether each entry in the DataFrame is truncated

Return type:

np.ndarray