cardinal_pythonlib.psychiatry.simhelpers

Original code copyright (C) 2009-2022 Rudolf Cardinal (rudolf@pobox.com).

This file is part of cardinal_pythonlib.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Helper functions for simulating behaviour.

cardinal_pythonlib.psychiatry.simhelpers.gen_params_around_centre(param_order: Sequence[str] | None = None, debug: bool = False, **kwargs: List | Tuple) → Iterable[Dict][source]

OVERALL PURPOSE. Used to generate parameter combinations for a parameter recovery simulation (where you vary known parameters, simulate behaviour, and check that your analytical method recovers the known values of the parameters).

STRATEGY. Parameter recovery is often computationally expensive. You might (for example) simulate 100 virtual subjects for each parameter combination (there’s nothing special about that number, but e.g. after Wilson & Collins, 2019, PMID 31769410, Box 2/Figure 1B), because simulating a subject that chooses based on calculated probabilities introduces random noise. You will want to simulate a range of parameter combinations.

You might want to explore the entire parameter space (in which case, see cardinal_pythonlib.iterhelp.product_dict()), but that may be computationally unfeasible – creating the simulations takes time and energy, and analysing them to recover those parameters takes time and energy.

An alternative strategy is to take central values of all parameters, and then vary one parameter at a time about those central values. For example, if you have n = 6 parameters with k = 5 possible values each, the combinatorial approach gives you k ^ n = 5 ^ 6 = 15,625 combinations – each requiring e.g. 100 subjects to be simulated, and parameters recovered. This alternative strategy gives 1 + (k - 1) * n = 1 + 4 * 6 = 25 combinations instead. This sort of method is used in e.g. Kanen et al. (2019), PMID 31324936.

Parameters:

  • kwargs – Keyword arguments, whose values are sequences (lists or tuples) of possible parameter values for the parameter with that keyword’s name.

  • param_order – The default order of parameters in the resulting dictionaries is alphabetical. You can specify a list of strings here; any parameters with these names will appear in the order in which they appear this list, and any others will be sorted alphabetically at the end.

  • debug – Report the interesting part of each combination to the log? This skips parameters that are always constant.

Yields:

Dictionaries containing one combination of possibilities (one value for each keyword). Unlike cardinal_pythonlib.iterhelp.product_dict(), the parameters vary one at a time, with the others being held at their central value (defined as the midpoint of the list of input values for that parameter, not in some numerical way). (If there is no central value, the one just before the centre is used, and a warning is given.)

Examples:

from cardinal_pythonlib.psychiatry.simhelpers import gen_params_around_centre
list(gen_params_around_centre(a=[1, 2, 3], b=[4, 5, 6], c=[7, 8, 9], d=[10]))