utils

templates.tvboptim.utils

TVB-Optim Template Utilities

Reusable Python functions for tvboptim Mako templates. Import these in template blocks to avoid code duplication.

Usage in templates

<% from tvbo.templates.tvboptim.utils import ( safe_name, as_list, is_network_observation, parse_loss_function, get_observation_refs ) %>

Functions

Name	Description
as_list	Convert dict or list to list of values.
get_all_hyperparams	Get all hyperparameters including from included algorithms.
get_all_observations_from_algo	Get all observation names including from included algorithms.
get_attr	Safe attribute access.
get_domain_bounds	Lookup domain bounds from model.parameters or coupling.parameters.
get_include_info	Extract algorithm name and argument overrides from AlgorithmInclude.
get_observation_refs	Categorize observations into network vs simulation-derived.
get_param_info	Extract parameter names, defaults, and shapes from a parameters collection.
is_external_observation	Check if observation is external (has data_source or network.observations source).
is_network_observation	Check if observation is a network observation (static data from BIDS).
obs_has_all_args	Check if observation has all required arguments satisfied.
parse_exploration	Parse exploration specification from YAML.
parse_free_param	Parse a free_parameter entry.
parse_loss_arguments	Parse loss function call arguments.
parse_loss_function	Parse optimization loss function specification.
safe_name	Convert name to valid Python identifier.
to_numeric	Convert string to numeric if possible.

as_list

templates.tvboptim.utils.as_list(obj)

Convert dict or list to list of values.

get_all_hyperparams

templates.tvboptim.utils.get_all_hyperparams(algo, algorithms_dict)

Get all hyperparameters including from included algorithms.

get_all_observations_from_algo

templates.tvboptim.utils.get_all_observations_from_algo(algo, algorithms_dict)

Get all observation names including from included algorithms.

get_attr

templates.tvboptim.utils.get_attr(obj, name, default=None)

Safe attribute access.

get_domain_bounds

templates.tvboptim.utils.get_domain_bounds(param_name, model, all_couplings)

Lookup domain bounds from model.parameters or coupling.parameters.

Returns (lo, hi) tuple, where None means unbounded.

get_include_info

templates.tvboptim.utils.get_include_info(inc)

Extract algorithm name and argument overrides from AlgorithmInclude.

Returns (algo_name, {param_name: value}) tuple.

get_observation_refs

templates.tvboptim.utils.get_observation_refs(observations_dict)

Categorize observations into network vs simulation-derived.

Returns

Name	Type	Description
	Tuple[Set[str], List[str]]	(network_observation_names, observation_names_with_all_args)

get_param_info

templates.tvboptim.utils.get_param_info(parameters)

Extract parameter names, defaults, and shapes from a parameters collection.

Works for both model.parameters and coupling.parameters.

Parameters

Name	Type	Description	Default
parameters	dict	dict-like of Parameter objects	required

Returns

Name	Type	Description
tuple	Tuple[List[str], Dict[str, float], Dict[str, str]]	(param_names, param_defaults, param_shapes) - param_names: list of parameter names - param_defaults: dict of name -> scalar value (for DEFAULT_PARAMS) - param_shapes: dict of name -> shape string (only for params with shape attribute)

is_external_observation

templates.tvboptim.utils.is_external_observation(obs)

Check if observation is external (has data_source or network.observations source).

is_network_observation

templates.tvboptim.utils.is_network_observation(obs)

Check if observation is a network observation (static data from BIDS).

Network observations have source starting with ‘network.observations’.

obs_has_all_args

templates.tvboptim.utils.obs_has_all_args(obs)

Check if observation has all required arguments satisfied.

Returns True if all pipeline step arguments either have values or are implicitly satisfied by source.

parse_exploration

templates.tvboptim.utils.parse_exploration(
    expl,
    all_couplings,
    get_pipeline_output_key_fn=None,
)

Parse exploration specification from YAML.

Returns dict with: name, label, mode, n_parallel, axes, observable_*

parse_free_param

templates.tvboptim.utils.parse_free_param(
    fp,
    coupling_keys,
    model=None,
    all_couplings=None,
)

Parse a free_parameter entry.

Handles: str, dotted notation, stringified dict, dict, and Parameter objects.

name, heterogeneous, shape, coupling_key, dynamics_key,

lower_bound, upper_bound

parse_loss_arguments

templates.tvboptim.utils.parse_loss_arguments(loss_call)

Parse loss function call arguments.

Returns

Name	Type	Description
	List[Dict]	(parsed_args, obs_refs) where:
	Set[str]	- parsed_args: list of dicts with ‘name’, ‘type’, and type-specific keys
	Tuple[List[Dict], Set[str]]	- obs_refs: set of observation names referenced

parse_loss_function

templates.tvboptim.utils.parse_loss_function(opt)

Parse optimization loss function specification.

Returns dict with: opt_name, func_name, args, obs_refs, agg_over, agg_type or None if no loss defined.

safe_name

templates.tvboptim.utils.safe_name(name)

Convert name to valid Python identifier.

to_numeric

templates.tvboptim.utils.to_numeric(val)

Convert string to numeric if possible.