torchsig.signals.signal_types.Signal¶

class torchsig.signals.signal_types.Signal(data: ndarray | None = None, component_signals: list[Signal] = [], **kwargs: Any)[source]¶

Bases: SignalMetadataObject

Represents a signal with data and metadata.

This class extends SignalMetadataObject to include actual signal data and component signals.

Parameters:

data – Signal IQ data. Defaults to empty numpy array.
component_signals – List of component signals. Defaults to empty list.
**kwargs – Additional metadata key-value pairs.

Methods

`add_parent`	Add parent Seedable object and set up RNGs accordingly.
`copy`	Returns a copy of the Signal.
`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.
`to_dict`	Returns SignalMetadataExternal as a full dictionary.
`update_from_parent`	Update numpy and torch number generators with parent seed.

Attributes

`duration`	Signal duration normalized to 0-1.0.
`lower_freq`	Calculates the lower frequency of a signal.
`oversampling_rate`	Calculates the oversampling rate for a signal.
`start`	Signal start normalized to duration of signal.
`stop`	Signal stop normalized to duration of signal.
`stop_in_samples`	Signal stop in samples.
`upper_freq`	Calculates the upper frequency of a signal.

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.

property duration: float¶

Signal duration normalized to 0-1.0.

Returns:: Signal duration as a percentage of total time (0-1).
Return type:: float

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_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}

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.

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'

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']

property lower_freq: float¶

Calculates the lower frequency of a signal.

Returns:: Lower frequency in Hz.
Return type:: float
Raises:: ValueError – If center_freq or bandwidth are not available.

property oversampling_rate: float¶

Calculates the oversampling rate for a signal.

Returns:: Oversampling rate (sample_rate / bandwidth).
Return type:: float

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.

property start: float¶

Signal start normalized to duration of signal.

Returns:: Signal start as a percentage of total time (0-1).
Return type:: float

property stop: float¶

Signal stop normalized to duration of signal.

Returns:: Signal stop as a percentage of total time (0-1).
Return type:: float

property stop_in_samples: int¶

Signal stop in samples.

Returns:: Signal stop time in samples.
Return type:: int

to_dict() → dict[str, Any]¶

Returns SignalMetadataExternal as a full dictionary.

Returns:: Dictionary containing all metadata attributes.
Return type:: Dict[str, Any]

update_from_parent() → None¶: Update numpy and torch number generators with parent seed.

property upper_freq: float¶

Calculates the upper frequency of a signal.

Returns:: Upper frequency in Hz.
Return type:: float
Raises:: ValueError – If center_freq or bandwidth are not available.

__init__(data: ndarray | None = None, component_signals: list[Signal] = [], **kwargs: Any) → None[source]¶

Initializes the Signal with data and metadata.

Parameters:

data – Signal IQ data. Defaults to np.array([]).
component_signals – List of component signals. Defaults to [].
**kwargs – Additional metadata key-value pairs.

__repr__() → str[source]¶

Returns a string representation of the Signal.

Returns:: String representation showing class name, metadata, and component signals.
Return type:: str

copy() → Signal[source]¶

Returns a copy of the Signal.

Note

Parent relationships are not guaranteed to be preserved across copies.

Returns:: A new Signal instance with copied data and metadata.
Return type:: Signal