cubnm.sim.rww

rWWSimGroup

Group of reduced Wong-Wang (excitatory-inhibitory) simulations that are executed in parallel.

class cubnm.sim.rww.rWWSimGroup(*args, do_fic=True, max_fic_trials=0, I_SAMPLING_START=1000, I_SAMPLING_END=10000, init_delta=0.02, fic_penalty_scale=0.5, **kwargs)

Bases: cubnm.sim.base.SimGroup

Group of reduced Wong-Wang (excitatory-inhibitory) simulations that are executed in parallel.

Parameters

do_fic: bool

whether to apply feedback inhibition control. If provided wIE parameters will be ignored

max_fic_trials: int

maximum number of numerical FIC trials. If set to 0, FIC will be done only analytically

I_SAMPLING_START: int

starting time of numerical FIC I_E sampling (msec)

I_SAMPLING_END: int

end time of numerical FIC I_E sampling (msec)

init_delta: float

initial delta for numerical FIC adjustment

fic_penalty_scale: float

how much deviation from FIC target mean rE of 3 Hz is penalized. Set to 0 to disable FIC penalty.

*args, **kwargs:

see cubnm.sim.base.SimGroup for details

Attributes

param_lists: dict of np.ndarray

dictionary of parameter lists, including

• 'G': global coupling strength. Shape: (N_SIMS,)

• 'w_p': local excitatory recurrence. Shape: (N_SIMS, nodes)

• 'J_N': synaptic coupling strength. Shape: (N_SIMS, nodes)

• 'wIE': inhibitory to excitatory weight. Shape: (N_SIMS, nodes)

• 'sigma': noise amplitude. Shape: (N_SIMS, nodes)

• 'v': conduction velocity. Shape: (N_SIMS,)

Equations

\[\begin{split}\begin{gather} I_i^E=W^EI_b+w_i^{p} J_i^{N} S_i^E+GJ_i^{N}\sum_{j}{C_{ij}S_j^E}-w_i^{IE}S_i^I \\ I_i^I=W^II_b+J_i^{N}S_i^E-w^{II}S_i^I \\ r_i^E=H^E(I_i^E)\ =\frac{a^EI_i^E-b^E}{1\ -\ e^{-d^E(a^EI_i^E-b^E)}} \\ r_i^I=H^I(I_i^I)\ =\frac{a^II_i^I-b^I}{1\ -\ e^{-d^I(a^II_i^I-b^I)}} \\ \dot{S_i^E}=-\frac{S_i^E}{\tau_E}+(1\ -\ S_i^E)\gamma r_i^E(t)+\sigma_i\epsilon_i^E \\ \dot{S_i^I}=-\frac{S_i^I}{\tau_I}+r_i^I+\sigma_i\epsilon_i^I \\ \end{gather}\end{split}\]

References

• Deco et al. 2014 Journal of Neuroscience (10.1523/JNEUROSCI.5068-13.2014)

• Demirtas et al. 2019 Neuron (10.1016/j.neuron.2019.01.017)

• Deco et al. 2018 Current Biology (10.1016/j.cub.2018.07.083)

model_name = 'rWW'

global_param_names = ['G']

regional_param_names = ['w_p', 'J_N', 'wIE', 'sigma']

state_names = ['I_E', 'I_I', 'r_E', 'r_I', 'S_E', 'S_I']

sel_state_var = 'r_E'

n_noise = 2

default_params

get_config(*args, **kwargs)

Get the configuration of the simulation group

Parameters

include_N: bool

include N in the output config is ignored when for_reinit is True

for_reinit: bool

include the parameters that need reinitialization of the simulation core session if changed

Returns

config: dict

dictionary of simulation group configuration

_process_out(out)

Assigns model outputs (as arrays) to object attributes with correct shapes, names and types.

Parameters

out: tuple

output of cubnm._core.run_simulations function

Notes

The simulation outputs are assigned to the following object attributes:

• init_time: float

  initialization time of the simulations

• run_time: float

  run time of the simulations

• sim_bold: np.ndarray

  simulated BOLD time series. Shape: (N_SIMS, duration/TR, nodes)

• sim_states: dict of np.ndarray

  simulated state variables with keys as state names and values as arrays with the shape (N_SIMS, nodes) when states_ts is False, and (N_SIMS, duration/TR, nodes) when states_ts is True

If do_fc is True, additionally includes:

• sim_fc_trils: np.ndarray

  simulated FC lower triangle. Shape: (N_SIMS, n_pairs)

If do_fcd is True, additionally includes:

• sim_fcd_trils: np.ndarray

  simulated FCD lower triangle. Shape: (N_SIMS, n_window_pairs)

score(emp_fc_tril=None, emp_fcd_tril=None, emp_bold=None, **kwargs)

Calculates individual goodness-of-fit terms and aggregates them. In FIC models also calculates fic_penalty. Note that while FIC penalty is included in the cost function of optimizer, it is not included in the aggregate GOF.

Parameters

emp_fc_tril: np.ndarray

1D array of empirical FC lower triangle. Shape: (edges,)

emp_fcd_tril: np.ndarray

1D array of empirical FCD lower triangle. Shape: (window_pairs,)

emp_bold: np.ndarray or None

cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes) Motion outliers should either be excluded (not recommended as it disrupts the temporal structure) or replaced with zeros. If provided emp_fc_tril and emp_fcd_tril will be ignored.

**kwargs:

keyword arguments passed to cubnm.sim.SimGroup.score

Returns

scores: pd.DataFrame

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

_get_save_data()

Get the simulation outputs and parameters to be saved to disk

Returns

out_data: dict

dictionary of simulation outputs and parameters

_problem_init(problem)

Extends BNMProblem initialization and includes FIC penalty if indicated.

Parameters

problem: cubnm.optimize.BNMProblem

optimization problem object

_problem_evaluate(problem, X, out, *args, **kwargs)

Extends BNMProblem evaluation and includes FIC penalty in the cost function if indicated.

Parameters

X: np.ndarray

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

out: dict

the output dictionary to store the results with keys 'F' and 'G'. Currently only 'F' (cost) is used.

*args, **kwargs

classmethod _get_test_configs(cpu_gpu_identity=False)

Get configs for testing the simulations

Parameters

cpu_gpu_identity: bool

indicates whether configs are for CPU/GPU identity tests in which case force_cpu is not included in the configs since tests will be done on both CPU and GPU

Returns

configs: dict of list

classmethod _get_test_instance(opts)

Initializes an instance that is used in tests

Parameters

opts: dict

dictionary of test options

Returns

sim_group: cubnm.sim.rWWSimGroup

simulation group object of the test simulation which is not run yet

post_init()

Post-initilaization hook that normally does nothing, but can be overridden in derived classes to add custom post-initialization steps.

_check_dt()

Check if integrations steps are valid

_set_default_params(missing=True)

Set default parameters for the simulations.

Parameters

missing: bool, optional

If True (default), only sets parameters that are currently None or have an incorrect length in self.param_lists. If False, always overwrites all listed defaults.

run(force_reinit=False)

Run the simulations in parallel (as possible) on GPU/CPU through the cubnm._core.run_simulations() function which runs compiled C++/CUDA code.

Parameters

force_reinit: bool

force reinitialization of the session. At the beginning of each session (when cubnm is imported) some variables are initialized on CPU/GPU and reused in every run. Set this to True if you want to reinitialize these variables. This is rarely needed.

get_state_averages()

Get the averages of state variables across time and nodes for each simulation.

Returns

state_averages: pd.DataFrame

DataFrame of state averages with columns as state names and rows as simulations

get_noise()

Get the (recreated) noise time series. This requires recreation of the noise array if noise segmenting is on. Noise will be recreated based on shuffling indices of nodes and time steps, similar to how it is done in the core code.

Returns

noise: np.ndarray

Noise segment array. Shape: (n_noise, nodes, bw_it, inner_it)

get_sim_fc(idx)

Get the simulated FC of a given simulation idx as a square matrix.

Parameters

idx: int

index of the simulation to get the FC for

Returns

fc: np.ndarray

simulated FC matrix of shape (nodes, nodes) for the simulation with index idx

get_sim_fcd(idx)

Get the simulated FCD of a given simulation idx as a square matrix.

Parameters

idx: int

index of the simulation to get the FC for

Returns

fcd: np.ndarray

simulated FC matrix of shape (n_windows, n_windows) for the simulation with index idx

slice(key, inplace=False)

Slice the simulation group to a single simulation

Parameters

key: int

index of the simulation to slice

inplace: bool

the object will be sliced in place and therefore the data of other simulations will be removed. Otherwise a new object copied from the current object will be returned.

Returns

obj: cubnm.sim.SimGroup

sliced simulation group

clear()

Clear the simulation outputs

save()

Save simulation outputs to disk as an npz file.