Minimize

class Minimize(model=None, data=None, initial_guess=None, minimisation=None, method='Nelder-Mead', cl=None, parallel=False, libraries=['numpy', 'pandas'], prior=False, metrics=None, number_of_starts=1, ppt_identifier=None, display=False, hessian='numdifftools', **kwargs)

Bases: object

Class representing scipy’s Minimize algorithm wrapped for subject-level parameter estimations.

Parameters:

modelcpm.generators.Wrapper

The model to be optimized.

datapd.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. See the minimise module for more information. User-defined loss functions are also supported.

priorbool

Whether to include the prior in the optimization. Default is False. When True, each entry of fit additionally records log_likelihood and log_prior, the summed log likelihood and the summed log prior density at the optimised parameter values, because fun is then the negative summed log posterior density and cannot be split apart after the fact.

metricsdict, iterable, callable() or None

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 - likelihood and log_likelihood (both the summed log likelihood), log_prior, predicted, observed, n, k and parameters - so a metric takes what it needs and absorbs the rest in **kwargs, as cpm.optimisation.compare.PenalisedLikelihoods and the loss functions in cpm.optimisation.minimise already do. Default is None.

number_of_startsint

The number of random initialisations for the optimization. Default is 1.

initial_guesslist or array_like

The initial guess for the optimization. Default is None. If number_of_starts is set, and the initial_guess parameter is ‘None’, the initial guesses are randomly generated from a uniform distribution.

parallelbool

Whether to use parallel processing. Default is False.

clint

The number of cores to use for parallel processing. Default is None. If None, the number of cores is set to 2. If cl is set to None and parallel is set to True, the number of cores is set to the number of cores available on the machine.

librarieslist, optional

The libraries to import for parallel processing for ipyparallel with the IPython kernel. Default is ["numpy", "pandas"]

ppt_identifierstr

The column (or the key in the participant data dictionaries) that contains the participant identifier, returned in the optimization details. Required if data is a pd.DataFrame. If data is a pd.DataFrameGroupBy grouped by a single column, such as data.groupby("ppt"), it defaults to the name of that column. Default is None.

hessian{“numdifftools”, “finite_differences”}

How the Hessian matrix recorded in details is 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 (see cpm.core.optimisers.finite_difference_hessian()), once per participant, for the best start only, together with log_likelihood, log_prior and metrics. Default is “numdifftools”.

**kwargsdict

Additional keyword arguments. See the scipy.optimize.minimize() documentation for what is supported.

Attributes:

number_of_startsint

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_guess currently 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 to False.

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_starts times, and only the best-fitting output from the best guess is stored.

optimise()

Performs the optimization process.

Returns:

None

reset(initial_guess=True)

Resets the optimization results and fitted parameters.

Parameters:

initial_guessbool, optional

Whether to reset the initial guess (generates a new set of random numbers within parameter bounds). Default is True.

Returns:

None

export()

Exports the optimization results and fitted parameters as a pandas.DataFrame.

Returns:

pandas.DataFrame

A pandas DataFrame containing the optimization results and fitted parameters.