Model infrastructure

The modeling interface defines parameter metadata, model evaluation results, the base class for dose-response models, and registry lookup.

BaseDoseResponseModel

class bindcurve.BaseDoseResponseModel

Bases: ABC

Base class for dose-response models fitted through lmfit.

__init__()

Return type:

None

evaluate(concentration, **params)

Evaluate the observable response on the raw concentration axis.

Parameters:

• concentration (ndarray)

• params (float)

Return type:

ndarray

abstractmethod guess(compound)

Generate initial parameter guesses for one compound or experiment.

Parameters:

compound (CompoundData)

Return type:

dict[str, float]

response_from_components(components, **params)

Map a physical binding fraction to the measured response.

Parameters:

• components (Mapping[str, ndarray])

• params (float)

Return type:

ndarray

evaluate_components(concentration, **params)

Evaluate the observable response and any model-specific components.

Parameters:

• concentration (ndarray)

• params (float)

Return type:

ModelEvaluation

property concentration_parameter_specs: tuple[ParameterSpec, ...]

Return concentration-like parameter specifications.

property required_fixed_parameters: frozenset[str]

Return parameters that must be provided as fixed assay constants.

parameter_spec(name)

Return one parameter specification by public name.

Parameters:

name (str)

Return type:

ParameterSpec

make_lmfit_parameters(guesses, *, fixed=None, bounds=None)

Create lmfit Parameters from model specs, guesses, and user overrides.

Parameters:

• guesses (Mapping[str, float])

• fixed (Mapping[str, float] | None)

• bounds (Mapping[str, tuple[float | None, float | None]] | None)

Return type:

Parameters

residual(parameters, concentration, y, sigma=None)

Return observed-minus-predicted residuals, standardized when σ is known.

Parameters:

• parameters (Parameters)

• concentration (ndarray)

• y (ndarray)

• sigma (ndarray | None)

Return type:

ndarray

decode_parameters(parameters)

Decode optimizer coordinates to public physical parameter values.

Parameters:

parameters (Parameters)

Return type:

dict[str, float]

parameter_jacobian(parameters, variable_names)

Return d(public parameter)/d(optimizer coordinate) for varying parameters.

Parameters:

• parameters (Parameters)

• variable_names (tuple[str, ...])

Return type:

ndarray

ModelEvaluation

class bindcurve.ModelEvaluation

Bases: object

Observable response plus any model-specific component arrays.

component(name)

Return one named component array.

Parameters:

name (str)

Return type:

ndarray

__init__(concentration, response, components=<factory>)

Parameters:

• concentration (ndarray)

• response (ndarray)

• components (dict[str, ndarray])

Return type:

None

ParameterSpec

class bindcurve.ParameterSpec

Bases: object

Complete specification for one public model parameter.

scale controls only the optimizer coordinate. Model evaluation and all public results always use the parameter’s physical, linear-scale value.

property required_fixed: bool

Whether the caller must provide this non-varying parameter.

property resolved_log_name: str

Return the canonical name for the log10 representation.

__init__(name, initial=None, min=-inf, max=inf, vary=True, kind='native', scale='linear', reportable=True, log_name=None, description=None)

Parameters:

• name (str)

• initial (float | None)

• min (float)

• max (float)

• vary (bool)

• kind (Literal['native', 'concentration'])

• scale (Literal['linear', 'log10'])

• reportable (bool)

• log_name (str | None)

• description (str | None)

Return type:

None

get_model

bindcurve.get_model(name)

Return a registered model by name.

Parameters:

name (str)

Return type:

BaseDoseResponseModel