torchsig.utils.abstractions.HierarchicalMetadataObject

class torchsig.utils.abstractions.HierarchicalMetadataObject(seed: int | None = None, parent: HierarchicalMetadataObject | None = None, metadata: dict[str, Any] | None = None, **kwargs: Any)

Bases: Seedable

A class for representing objects which have metadata in a hierarchical relationship.

Metadata can be accessed directly (e.g., obj[“some_field”]), or through the metadata field (e.g., obj.metadata[“some_field”]). Metadata fields can be treated as class fields for access; i.e., obj.some_field is equivalent to obj[“some_field”] or obj.metadata[“some_field”] as long as some_field is not already a class field of obj. Metadata fields are inherited in a parent/child relationship such that if parent.metadata = {“field_1”:4,”field_2”:5}, and child.metadata = {“field_2”:6} then child.field_1==4 and child.field_2==6. The parent of a HierarchicalMetadataObject (as defined in the Seedable class) should always be another HierarchicalMetadataObject.

_metadata

Dictionary containing the object’s metadata.

Methods

add_parent	Add parent Seedable object and set up RNGs accordingly.
copy	Create a copy of the object.
get_distribution	Create distribution function with proper seeding.
get_full_metadata	Function for modifying and returning a new metadata with all the fields in parent or child, with child overriding parent in conflicts.
get_second_seed	Gets second seed, usually used to seed both torch and numpy generators with slightly different seeds.
key_lookup	Lookup a metadata key with enhanced error reporting.
keys	Get all metadata keys.
seed	Seed number generators with given seed.
setup_rngs	Initialize torch and numpy number generators, and update its children.
update_from_parent	Update numpy and torch number generators with parent seed.

__init__(seed: int | None = None, parent: HierarchicalMetadataObject | None = None, metadata: dict[str, Any] | None = None, **kwargs: Any) → None

Initialize the HierarchicalMetadataObject.

Parameters:

• seed – Random seed for reproducibility. Defaults to None.

• parent – Parent object in the hierarchy. Defaults to None.

• metadata – Initial metadata dictionary. Defaults to None.

• **kwargs – Additional metadata fields to set.

Note

This will override fields in the object passed in with arguments directly given to the generator; useful for making multiple similar but not identical objects.

get_full_metadata() → dict[str, Any]

Function for modifying and returning a new metadata with all the fields in parent or child, with child overriding parent in conflicts.

Returns:

Dictionary containing all metadata from parent and child, with child values overriding parent values in case of conflicts.

Example

>>> parent = HierarchicalMetadataObject(metadata={"field_1": 4, "field_2": 5})
>>> child = HierarchicalMetadataObject(parent=parent, metadata={"field_2": 6})
>>> child.get_full_metadata()
{'field_1': 4, 'field_2': 6}

keys() → list[str]

Get all metadata keys.

Returns:

List of all metadata keys.

Example

>>> obj = HierarchicalMetadataObject(metadata={"key1": 1, "key2": 2})
>>> list(obj.keys())
['key1', 'key2']

copy() → HierarchicalMetadataObject

Create a copy of the object.

Returns:

A new instance of the same class with the same metadata and parent.

Example

>>> obj = HierarchicalMetadataObject(metadata={"key": "value"})
>>> copy_obj = obj.copy()
>>> copy_obj["key"]
'value'

key_lookup(key: str) → Any

Lookup a metadata key with enhanced error reporting.

Parameters:

key – The metadata key to lookup.

Returns:

The value associated with the key.

Raises:

MetadataAttributeError – If the key is not found in the metadata or parent metadata.

Example

>>> obj = HierarchicalMetadataObject(metadata={"key": "value"})
>>> obj.key_lookup("key")
'value'

__repr__() → str

Printable representation with seed and parent.

Returns:

String representation of the object.

add_parent(parent: Seedable, register: bool = True) → None

Add parent Seedable object and set up RNGs accordingly.

Parameters:

• parent – Parent Seedable object to add.

• register – If True (default), add self to parent.children so that future seed propagation reaches this object. Pass False for transient objects (e.g. per-sample Signal instances) that only need the parent link for metadata/RNG access during their lifetime but must not accumulate in the parent’s child list, which would otherwise cause unbounded memory growth.

get_distribution(params: list | tuple | float, scaling: str = 'linear') → Distribution

Create distribution function with proper seeding.

Parameters:

• params – Parameters for distribution.

• scaling – Scaling param for distribution. Defaults to ‘linear’.

Returns:

Distribution function, seeded.

Return type:

Distribution

get_second_seed(seed: int) → int

Gets second seed, usually used to seed both torch and numpy generators with slightly different seeds.

Parameters:

seed – Seed to use.

Returns:

New seed.

seed(seed: int) → None

Seed number generators with given seed.

Parameters:

seed – Seed to use.

setup_rngs() → None

Initialize torch and numpy number generators, and update its children.

update_from_parent() → None

Update numpy and torch number generators with parent seed.