DifferentialEvolution#

class DifferentialEvolution(model=None, data=None, minimisation=<function LogLikelihood.bernoulli>, prior=False, metrics=None, parallel=False, cl=None, libraries=['numpy', 'pandas'], ppt_identifier=None, display=False, **kwargs)[source]#

Bases: object

Class representing the Differential Evolution optimization algorithm.

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. Default is minimise.LogLikelihood.bernoulli. See the minimise module for more information. User-defined loss functions are also supported, but they must conform to the format of currently implemented ones.
prior: bool: Whether to include priors in the optimisation. 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.
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.
**kwargsdict: Additional keyword arguments. See the scipy.optimize.differential_evolution() documentation for what is supported.

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.

optimise()[source]#

Performs the optimization process.

Returns:

None

reset()[source]#

Resets the optimization results and fitted parameters.

Returns:

None

export(details=False)[source]#

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

Parameters:

detailsbool: Whether to include the various metrics related to the optimisation routine in the output.

Returns:

pandas.DataFrame: A pandas DataFrame containing the optimization results and fitted parameters. If details is True, the DataFrame will also include the optimization details.

Notes

The DataFrame will not contain the population and population_energies keys from the optimization details. If you want to investigate it, please use the details attribute.