Bads#
- class Bads(model=None, data=None, minimisation=<function LogLikelihood.continuous>, prior=False, metrics=None, number_of_starts=1, initial_guess=None, parallel=False, cl=None, libraries=['numpy', 'pandas'], ppt_identifier=None, display=True, hessian='numdifftools', **kwargs)[source]#
Bases:
objectClass representing the Bayesian Adaptive Direct Search (BADS) optimization algorithm.
- Parameters:
- modelcpm.generators.Wrapper
The model to be optimized.
- data
pd.DataFrame, pd.DataFrameGroupBy,list The data used for optimization. If a pd.Dataframe, it is grouped by the
ppt_identifier. If it is a pd.DataFrameGroupby, groups are assumed to be participants. An array of dictionaries, where each dictionary contains the data for a single participant, including information about the experiment and the results too. See Notes for more information.- minimisationfunction
The loss function for the objective minimization function. Default is
minimise.LogLikelihood.continuous. See theminimisemodule for more information. User-defined loss functions are also supported.- prior: bool
Whether to include the prior in the optimization. Default is
False. WhenTrue, each entry offitadditionally recordslog_likelihoodandlog_prior, the summed log likelihood and the summed log prior density at the optimised parameter values, becausefunis then the negative summed log posterior density and cannot be split apart after the fact.- metrics
dict, iterable,callable()orNone Goodness-of-fit metrics to evaluate at the optimised parameter values and record alongside the fit, so that they reach
export()too. Supply a mapping of output names to callables, an iterable of callables named after themselves, or a single callable. Each is called with keyword arguments only -likelihoodandlog_likelihood(both the summed log likelihood),log_prior,predicted,observed,n,kandparameters- so a metric takes what it needs and absorbs the rest in**kwargs, ascpm.optimisation.compare.PenalisedLikelihoodsand the loss functions incpm.optimisation.minimisealready do. Default isNone.- number_of_starts
int The number of random initialisations for the optimization. Default is
1.- initial_guess
listor array_like The initial guess for the optimization. Default is
None. Ifnumber_of_startsis set, and theinitial_guessparameter is ‘None’, the initial guesses are randomly generated from a uniform distribution.- parallelbool
Whether to use parallel processing. Default is
False.- cl
int The number of cores to use for parallel processing. Default is
None. IfNone, the number of cores is set to 2. Ifclis set toNoneandparallelis set toTrue, the number of cores is set to the number of cores available on the machine.- libraries
list, optional The libraries required for the parallel processing with
ipyparallelwith the IPython kernel. Default is["numpy", "pandas"].- ppt_identifier
str The column (or the key in the participant data dictionaries) that contains the participant identifier, returned in the optimization details. Required if
datais a pd.DataFrame. Ifdatais a pd.DataFrameGroupBy grouped by a single column, such asdata.groupby("ppt"), it defaults to the name of that column. Default isNone.- hessian{“numdifftools”, “finite_differences”}
How the Hessian matrix recorded in
fitis computed. With “numdifftools”, it is computed with numdifftools’ forward differences at the optimised parameter values plus 1e-3, for every start. With “finite_differences”, it is computed at the optimised parameter values with finite differences that stay within the bounds of the parameters (seecpm.core.optimisers.finite_difference_hessian()), once per participant, for the best start only, together withlog_likelihood,log_priorandmetrics. Default is “numdifftools”.- **kwargs
dict Additional keyword arguments. See the pybads.bads documentation for what is supported.
- Attributes:
- number_of_starts
int The number of starts requested, retained so that it is recoverable from a constructed optimiser rather than only implied by
initial_guess.shape[0].- initial_guess_suppliedbool
Whether
initial_guesscurrently holds guesses supplied by the user (True) or guesses drawn from the parameter bounds (False). This distinguishes a fit started from a fixed point from one started from random restarts, which is otherwise not recoverable after fitting.reset(initial_guess=True)draws new random guesses and therefore sets this attribute toFalse.
- number_of_starts
Notes
The data parameter must contain all input to the model, including the observed data. The data parameter can be a pandas DataFrame, a pandas DataFrameGroupBy object, or a list of dictionaries. If the data parameter is a pandas DataFrame, it is assumed that the data needs to be grouped by the participant identifier,
ppt_identifier. If the data parameter is a pandas DataFrameGroupBy object, the groups are assumed to be participants. If the data parameter is a list of dictionaries, each dictionary should contain the data for a single participant, including information about the experiment and the results. The observed data for each participant should be included in the dictionary under the key or column ‘observed’. The ‘observed’ key should correspond, both in format and shape, to the ‘dependent’ variable calculated by the model Wrapper.The optimization process is repeated
number_of_startstimes, and only the best-fitting output from the best guess is stored.The BADS algorithm has been designed to handle both deterministic and noisy (stochastic) target functions. A deterministic target function is a target function that returns the same exact probability value for a given dataset and proposed set of parameter values. By contrast, a stochastic target function returns varying probability values for the same input (data and parameters). The vast majority of models use a deterministic target function. We recommend that users make this explicit to BADS, by providing an
optionsdictionary that includes the keyuncertainty_handlingset toFalse. Please see that BADS options documentation for more details.