utils
utils
Utilities Module for TVB-O
Core utilities: Bunch container, PyTree formatting, YAML I/O, and metadata traversal helpers.
Plotting utilities (colors, colormaps, multiview) have moved to tvbo.plot.utils and are re-exported here for backward compatibility.
Analysis functions (per_window_fc, ttest_correlation_strength) have moved to tvbo.analysis.
Attributes
| Name | Description |
|---|---|
| ROOT_DIR | |
| cm |
Classes
| Name | Description |
|---|---|
| Bunch | Dictionary with attribute access and optional JAX PyTree support. |
Bunch
utils.Bunch()Dictionary with attribute access and optional JAX PyTree support.
Extends dict to allow both bunch["key"] and bunch.key access. If JAX is installed, registered as a PyTree via register_pytree_node_class with deterministic (sorted-key) traversal order.
Based on scikit-learn’s sklearn.utils.Bunch.
See Also
https://scikit-learn.org/stable/modules/generated/sklearn.utils.Bunch.html
Functions
| Name | Description |
|---|---|
| add_to_parameters_collection | Adds a value to a Bunch object using the provided path, without inserting a redundant sub-level. |
| deep_merge | Recursively merge override onto base, returning a new dict. |
| domain_enforcement | Normalise a state-variable domain’s enforcement mode to a plain string. |
| format_pytree_as_string | Recursively formats a JAX pytree structure as a string with Unicode box-drawing characters. |
| from_yaml | Load a LinkML datamodel object from a YAML file. |
| is_array_valued | Return True if a parameter value is an array constant rather than a scalar. |
| numbered_print | |
| pretty_print_pytree | Prints a pretty formatted representation of a JAX pytree structure. |
| to_yaml | Dump a LinkML datamodel object to YAML. |
| traverse_metadata | Recursively traverses the attributes of a metadata object, calling a callback on each Parameter. |
add_to_parameters_collection
utils.add_to_parameters_collection(key, value, path, parameters)Adds a value to a Bunch object using the provided path, without inserting a redundant sub-level.
deep_merge
utils.deep_merge(base, override)Recursively merge override onto base, returning a new dict.
Nested dicts are merged key-by-key, so an override can replace a single leaf while inheriting its siblings from base — e.g. {parameters: {a: {value: 1}}} overrides only a.value and keeps every other parameter from base. Any key whose two sides are not both dicts is taken from override. Neither input is mutated.
This is the field-level precedence used when a spec sourced by iri is refined by inline metadata: the inline value supervenes and the source (registry entry / ontology default) fills the gaps.
domain_enforcement
utils.domain_enforcement(domain)Normalise a state-variable domain’s enforcement mode to a plain string.
Returns one of 'none' (default — descriptive metadata only), 'clamp' (hard-clip to [lo, hi]) or 'wrap' (periodic). Accepts a Range/domain object (reads its enforce slot), a bare DomainEnforcement value, or None. Normalises across both generated representations of the enum — the pydantic (str, Enum) (compare via .value) and the gen-python permissible value (compare via str()) — so callers can simply test domain_enforcement(sv.domain) == 'clamp'.
format_pytree_as_string
utils.format_pytree_as_string(
pytree,
name='root',
prefix='',
is_last=False,
show_numerical_only=False,
is_root=True,
hide_none=False,
show_array_values=False,
)Recursively formats a JAX pytree structure as a string with Unicode box-drawing characters.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pytree | Any | The pytree to format. | required |
| name | str | The name of the current node. | 'root' |
| prefix | str | Current line prefix. | '' |
| is_last | bool | Whether the current node is the last child of its parent. | False |
| show_numerical_only | bool | If True, only show arrays and numerical types (float, int, etc.). | False |
| is_root | bool | Whether this node is the root of the tree. | True |
| hide_none | bool | If True, fields with None values will be hidden. | False |
| show_array_values | bool | If True, print full array values instead of summaries. | False |
Returns
| Name | Type | Description |
|---|---|---|
| str | str | The formatted string representation of the pytree. |
from_yaml
utils.from_yaml(filepath, cls)Load a LinkML datamodel object from a YAML file.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| filepath | str | Path to the YAML file. | required |
| cls | type | The datamodel class to instantiate. | required |
Returns
| Name | Type | Description |
|---|---|---|
| object | object | An instance of the datamodel class populated with data from the YAML file. |
is_array_valued
utils.is_array_valued(value)Return True if a parameter value is an array constant rather than a scalar.
Array-valued parameters (e.g. mode-coupling matrices, Gaussian-quadrature vectors) are stored as nested lists/tuples in YAML or as np.ndarray when set programmatically. Scalar-only call sites (float(p.value) substitution, sympy subs) must skip them. Single source of truth so list/tuple and ndarray are treated consistently everywhere.
numbered_print
utils.numbered_print(text)pretty_print_pytree
utils.pretty_print_pytree(
pytree,
name='root',
prefix='',
show_numerical_only=False,
hide_none=False,
)Prints a pretty formatted representation of a JAX pytree structure.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pytree | Any | The pytree to print. | required |
| name | str | The name of the current node. | 'root' |
| prefix | str | Current line prefix. | '' |
| show_numerical_only | bool | If True, only show arrays and numerical types (float, int, etc.). | False |
| hide_none | bool | If True, fields with None values will be hidden. | False |
Returns
| Name | Type | Description |
|---|---|---|
| None | None |
to_yaml
utils.to_yaml(obj, filepath=None)Dump a LinkML datamodel object to YAML.
- If filepath is provided, write YAML to that file and return the path.
- If filepath is None, return the YAML string.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| obj | object | Datamodel object to serialize. | required |
| filepath | str | None | Optional path to write YAML. | None |
Returns
| Name | Type | Description |
|---|---|---|
| str | str | File path when written to disk, otherwise the YAML string. |
traverse_metadata
utils.traverse_metadata(
metadata,
target_instance=None,
path=None,
callback=None,
callback_kwargs=None,
keys_to_exclude=(),
)Recursively traverses the attributes of a metadata object, calling a callback on each Parameter.