cubnm.optimize

Optimizers of the model free parameters

GridSearch	Grid search of model free parameters
BNMProblem	Biophysical network model problem. A pymoo.core.problem.Problem
Optimizer	Helper class that provides a standard way to create an ABC using
PymooOptimizer	Helper class that provides a standard way to create an ABC using
CMAESOptimizer	Helper class that provides a standard way to create an ABC using
NSGA2Optimizer	Helper class that provides a standard way to create an ABC using
BayesOptimizer	Helper class that provides a standard way to create an ABC using

class cubnm.optimize.GridSearch(model, params, **kwargs)

Grid search of model free parameters

Parameters

model : str, {‘rWW’, ‘rWWEx’, ‘Kuramoto’} params : dict of tuple or float

a dictionary including parameter names as keys and their fixed values (float) or discrete range of values (tuple of (min, max, n)) as values.

**kwargs

Keyword arguments passed to cubnm.sim.SimGroup

Example

Run a grid search of rWW model with 10 G and 10 wEE values with fixed wEI:

from cubnm import datasets, optimize

gs = optimize.GridSearch(
    model = 'rWW',
    params = {
        'G': (0.5, 2.5, 10),
        'wEE': (0.05, 0.75, 10),
        'wEI': 0.21
    },
    duration = 60,
    TR = 1,
    sc_path = datasets.load_sc('strength', 'schaefer-100', return_path=True),
    states_ts = True
)
emp_fc_tril = datasets.load_functional('FC', 'schaefer-100', exc_interhemispheric=True)
emp_fcd_tril = datasets.load_functional('FCD', 'schaefer-100', exc_interhemispheric=True)
scores = gs.evaluate(emp_fc_tril, emp_fcd_tril)

evaluate(emp_fc_tril, emp_fcd_tril)

Runs the grid simulations and evaluates their goodness of fit to the empirical FC and FCD

Parameters

emp_fc_trilnp.ndarray

lower triangular part of empirical FC. Shape: (edges,)

emp_fcd_trilnp.ndarray

lower triangular part of empirical FCD. Shape: (window_pairs,)

Returns

pd.DataFrame

The goodness of fit measures (columns) of each simulation (rows)

class cubnm.optimize.BNMProblem(model, params, emp_fc_tril, emp_fcd_tril, het_params=[], maps=None, maps_coef_range='auto', node_grouping=None, multiobj=False, **kwargs)

Bases: pymoo.core.problem.Problem

Biophysical network model problem. A pymoo.core.problem.Problem that defines the model, free parameters and their ranges, and target empirical data (FC and FCD), and the simulation configurations (through cubnm.sim.SimGroup). cubnm.optimize.Optimizer classes can be used to optimize the free parameters of this problem.

Parameters

model : str, {‘rWW’, ‘rWWEx’, ‘Kuramoto’} params : dict of tuple or float

a dictionary including parameter names as keys and their fixed values (float) or continuous range of values (tuple of (min, max)) as values.

emp_fc_trilnp.ndarray

lower triangular part of empirical FC. Shape: (edges,)

emp_fcd_trilnp.ndarray

lower triangular part of empirical FCD. Shape: (window_pairs,)

het_paramslist of str, optional

which regional parameters are heterogeneous across nodes

mapsstr, optional

path to heterogeneity maps as a text file or a numpy array. Shape: (n_maps, nodes). If provided one free parameter per regional parameter per each map will be added.

maps_coef_range‘auto’ or tuple or list of tuple

• ‘auto’: uses (-1/max, -1/min) for maps with positive and negative

  values (assuming they are z-scored) and (0, 1) otherwise

• tuple: uses the same range for all maps

• list of tuple: n-map element list specifying the range

  of coefficients for each map

node_grouping{None, ‘node’, ‘sym’, str, np.ndarray}, optional

• None: does not use region-/group-specific parameters

• ‘node’: each node has its own regional free parameters

• ‘sym’: uses the same regional free parameters for each pair of symmetric nodes

  (e.g. L and R hemispheres). Assumes symmetry of parcels between L and R hemispheres.

• str: path to a text file including node grouping array. Shape: (nodes,)

• np.ndarray: a numpy array. Shape: (nodes,)

multiobjbool, optional

instead of combining the objectives into a single objective function (via summation) defines each objective separately. This must not be used with single-objective optimizers

**kwargs

Keyword arguments passed to cubnm.sim.SimGroup

get_config(include_sim_group=True, include_N=False)

Get the problem configuration

Parameters

include_sim_groupbool, optional

whether to include the configuration of the associated cubnm.sim.SimGroup

include_Nbool, optional

whether to include the current population size in the configuration

Returns

dict

the configuration of the problem

eval(X)

Runs the simulations based on normalized candidate free parameters X and evaluates their goodness of fit to the empirical FC and FCD of the problem.

Parameters

Xnp.ndarray

the normalized parameters of current population in range [0, 1]. Shape: (N, ndim)

Returns

pd.DataFrame

The goodness of fit measures (columns) of each simulation (rows)

class cubnm.optimize.Optimizer(**kwargs)

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Base class for evolutionary optimizers

abstract setup_problem(problem, **kwargs)

abstract optimize()

save(save_obj=False)

Saves the output of the optimizer, including history of particles, history of optima, the optimal point, and its simulation data. The output will be saved to out_dir of the problem’s cubnm.sim.SimGroup. If a directory with the same type of optimizer already exists, a new directory with a new index will be created.

Parameters

save_objbool, optional

saves the optimizer object which also includes the simulation data of all simulations and therefore can be large file. Warning: this file is very large.

get_config()

Get the optimizer configuration

Returns

dict

the configuration of the optimizer

class cubnm.optimize.PymooOptimizer(termination=None, n_iter=2, seed=0, print_history=True, save_history_sim=False, **kwargs)

Bases: Optimizer

Helper class that provides a standard way to create an ABC using inheritance.

Generic wrapper for pymoo optimizers.

Parameters:

terminationpymoo.termination.Termination, optional

The termination object that defines the stopping criteria for the optimization process. If not provided, the termination criteria will be based on the number of iterations (n_iter).

n_iterint, optional

The maximum number of iterations for the optimization process. This parameter is only used if termination is not provided.

seedint, optional

The seed value for the random number generator used by the optimizer.

print_historybool, optional

Flag indicating whether to print the optimization history during the optimization process.

save_history_simbool, optional

Flag indicating whether to save the simulation data of each iteration. Default is False to avoid consuming too much memory across iterations.

**kwargs

Additional keyword arguments that can be passed to the pymoo optimizer.

setup_problem(problem, pymoo_verbose=False, **kwargs)

Registers a cubnm.optimizer.BNMProblem with the optimizer, so that the optimizer can optimize its free parameters.

Parameters

problemcubnm.optimizer.BNMProblem

The problem to be set up with the algorithm.

pymoo_verbosebool, optional

Flag indicating whether to enable verbose output from pymoo. Default is False.

**kwargs

Additional keyword arguments to be passed to the algorithm setup method.

optimize()

Optimizes the associated cubnm.optimizer.BNMProblem free parameters through an evolutionary optimization approach by running multiple generations of parallel simulations until the termination criteria is met or maximum number of iterations is reached.

class cubnm.optimize.CMAESOptimizer(popsize, x0=None, sigma=0.5, use_bound_penalty=False, algorithm_kws={}, **kwargs)

Bases: PymooOptimizer

Helper class that provides a standard way to create an ABC using inheritance.

Covariance Matrix Adaptation Evolution Strategy (CMA-ES) optimizer

Parameters

popsizeint

The population size for the optimizer

x0array-like, optional

The initial guess for the optimization. If None (default), the initial guess will be estimated based on 20 random samples as the first generation

sigmafloat, optional

The initial step size for the optimization

use_bound_penaltybool, optional

Whether to use a bound penalty for the optimization

algorithm_kwsdict, optional

Additional keyword arguments for the CMAES algorithm

**kwargs

Additional keyword arguments

Example

Run a CMAES optimization for 10 iterations with a population size of 20:

from cubnm import datasets, optimize

problem = optimize.BNMProblem(
    model = 'rWW',
    params = {
        'G': (0.5, 2.5),
        'wEE': (0.05, 0.75),
        'wEI': 0.15,
    },
    emp_fc_tril = datasets.load_functional('FC', 'schaefer-100', exc_interhemispheric=True),
    emp_fcd_tril = datasets.load_functional('FCD', 'schaefer-100', exc_interhemispheric=True),
    duration = 60,
    TR = 1,
    sc_path = datasets.load_sc('strength', 'schaefer-100', return_path=True),
    states_ts = True
)
cmaes = optimize.CMAESOptimizer(popsize=20, n_iter=10, seed=1)
cmaes.setup_problem(problem)
cmaes.optimize()
cmaes.save()

setup_problem(problem, **kwargs)

Extends cubnm.optimizer.PymooOptimizer.setup_problem() to set up the optimizer with the problem and set the bound penalty option based on the optimizer’s use_bound_penalty attribute.

Parameters

problemcubnm.optimizer.BNMProblem

The problem to be set up with the algorithm.

**kwargs

Additional keyword arguments to be passed to cubnm.optimizer.PymooOptimizer.setup_problem()

class cubnm.optimize.NSGA2Optimizer(popsize, algorithm_kws={}, **kwargs)

Bases: PymooOptimizer

Helper class that provides a standard way to create an ABC using inheritance.

Non-dominated Sorting Genetic Algorithm II (NSGA-II) optimizer

Parameters

popsizeint

The population size for the optimizer

algorithm_kwsdict, optional

Additional keyword arguments for the NSGA2 algorithm

kwargsdict

Additional keyword arguments for the base class

class cubnm.optimize.BayesOptimizer(popsize, n_iter, seed=0)

Bases: Optimizer

Helper class that provides a standard way to create an ABC using inheritance.

Bayesian optimizer

Parameters

popsizeint

The population size for the optimizer

n_iterint

The number of iterations for the optimization process

seedint, optional

The seed value for the random number generator used by the optimizer.

setup_problem(problem, **kwargs)

Sets up the optimizer with the problem

Parameters

problemcubnm.optimizer.BNMProblem

The problem to be set up with the algorithm.

**kwargs

Additional keyword arguments to be passed to skopt.Optimizer

optimize()

Optimizes the associated cubnm.optimizer.BNMProblem free parameters through an evolutionary optimization approach by running multiple generations of parallel simulations until the termination criteria is met or maximum number of iterations is reached.