Overview
The signal utilities module provides functions for converting signal state representations and validating signal structure. Signals in AveniECA represent perceptual or response states as numerical arrays.
Functions
get_state_as_array()
Converts a signal’s state to a NumPy array format.
Import:
from avenieca.utils.signal import get_state_as_array
Parameters
The signal dictionary containing a state field. The state can be a string (JSON), list, or NumPy array.
dtype
numpy.dtype
default:"np.float64"
The NumPy data type for the resulting array.
Returns
None (modifies the signal dictionary in-place, setting signal["state"] to a NumPy array)
Example
import numpy as np
from avenieca.utils.signal import get_state_as_array
# Signal with state as JSON string
signal = {
"state": "[0.5, 0.3, 0.8]",
"module_id": "visual_cortex",
"valence": 0.6,
"score": 85
}
get_state_as_array(signal)
print(signal["state"]) # numpy array: [0.5 0.3 0.8]
print(type(signal["state"])) # <class 'numpy.ndarray'>
get_state_as_list()
Converts a signal’s state to a Python list format.
Import:
from avenieca.utils.signal import get_state_as_list
Parameters
The signal dictionary containing a state field. The state can be a string (JSON), list, or NumPy array.
dtype
numpy.dtype
default:"np.float64"
The intermediate NumPy data type used during conversion.
Returns
None (modifies the signal dictionary in-place, setting signal["state"] to a Python list)
Example
from avenieca.utils.signal import get_state_as_list
import numpy as np
# Signal with state as NumPy array
signal = {
"state": np.array([0.2, 0.7, 0.9]),
"module_id": "motor_cortex",
"valence": 0.75,
"score": 92
}
get_state_as_list(signal)
print(signal["state"]) # [0.2, 0.7, 0.9]
print(type(signal["state"])) # <class 'list'>
verify_signal()
Validates the structure and content of a signal dictionary.
Import:
from avenieca.utils.signal import verify_signal
Parameters
The signal dictionary to validate. Must contain exactly 4 fields including a valid state field.
Returns
None (raises an exception if validation fails)
Validation Rules
- Signal must be a dictionary
- Signal must have exactly 4 fields
- State cannot be
None
- State cannot be an empty string
- State must be 1-dimensional (not multi-dimensional arrays)
- State values must be integers or floats
- Automatically converts NumPy arrays to lists
Raises
AssertionError - If signal is not a dict or doesn’t have 4 fieldsException - If state is None, empty, has wrong dimension, or contains invalid values
Examples
Valid Signal:
from avenieca.utils.signal import verify_signal
signal = {
"state": [0.1, 0.5, 0.9],
"module_id": "perception_module",
"valence": 0.7,
"score": 88
}
verify_signal(signal) # Passes validation
print(signal["state"]) # [0.1, 0.5, 0.9]
from avenieca.utils.signal import verify_signal
signal = {
"state": "[0.3, 0.6, 0.2]",
"module_id": "auditory",
"valence": 0.5,
"score": 75
}
verify_signal(signal) # Converts JSON string to list
print(signal["state"]) # [0.3, 0.6, 0.2]
import numpy as np
from avenieca.utils.signal import verify_signal
signal = {
"state": np.array([0.4, 0.8]),
"module_id": "tactile",
"valence": 0.6,
"score": 80
}
verify_signal(signal) # Converts numpy array to list
print(signal["state"]) # [0.4, 0.8]
print(type(signal["state"])) # <class 'list'>
from avenieca.utils.signal import verify_signal
# Empty state - raises Exception
signal = {
"state": "",
"module_id": "test",
"valence": 0.5,
"score": 50
}
verify_signal(signal) # Exception: signal state cannot be empty
# None state - raises Exception
signal = {
"state": None,
"module_id": "test",
"valence": 0.5,
"score": 50
}
verify_signal(signal) # Exception: signal state cannot be None
# Multi-dimensional array - raises Exception
signal = {
"state": [[0.1, 0.2], [0.3, 0.4]],
"module_id": "test",
"valence": 0.5,
"score": 50
}
verify_signal(signal) # Exception: state signal should be of dimension 1
Common Workflows
Preparing Signals for API Submission
from avenieca.utils.signal import verify_signal, get_state_as_list
import numpy as np
# Create signal from numpy computation
state_vector = np.random.rand(128) # 128-dimensional state
signal = {
"state": state_vector,
"module_id": "embedding_layer",
"valence": 0.85,
"score": 95
}
# Validate and convert to list format for JSON serialization
verify_signal(signal) # Converts to list automatically
# Now ready for API submission
print(type(signal["state"])) # <class 'list'>
Processing Received Signals
from avenieca.utils.signal import get_state_as_array
import numpy as np
# Signal received from API (state as JSON string)
received_signal = {
"state": "[0.1, 0.2, 0.3, 0.4]",
"module_id": "response_module",
"valence": 0.6,
"score": 78
}
# Convert to array for numerical operations
get_state_as_array(received_signal)
# Perform computation
state_magnitude = np.linalg.norm(received_signal["state"])
print(f"State magnitude: {state_magnitude}")