sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData

• Module: sdynpy.fileio.sdynpy_rattlesnake

• Source: GitHub

Signature¶

class sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData(sample_rate: 'int', time_data: 'np.ndarray', channel_table: 'pd.DataFrame', file_version: 'str' = None, time_per_write: 'float' = None, time_per_read: 'float' = None, hardware: 'int' = None, hardware_file: 'str' = None, output_oversample: 'int' = None, task_trigger: 'int' = None, task_trigger_output_channel: 'str' = None, environment_names: 'list | np.ndarray' = [], environment_active_channels: 'list | np.ndarray' = [], environments: 'dict[str, RattlesnakeRandomEnvironmentData]' = {}, **kwargs)

Top-level container for all data read from a Rattlesnake nc4 file.

Provides the global channel table, per-environment data objects, and convenience methods for assembling sdynpy array objects directly from the file data.

Instances are normally created via :meth:read_rattlesnake_nc4 rather than by calling the constructor directly.

Parameters¶

• sample_rate : int Acquisition sample rate in Hz.

• time_data : np.ndarray Raw time-domain data array loaded from the nc4 file.

• channel_table : pd.DataFrame Channel metadata table loaded from the channels group of the nc4 file.

• file_version : str, optional Version string stored in the nc4 file’s global attributes.

• time_per_write : float, optional Duration of each write block in seconds.

• time_per_read : float, optional Duration of each read block in seconds.

• hardware : int, optional Hardware identifier stored in the nc4 file.

• hardware_file : str, optional Path to the hardware configuration file recorded in the nc4 file.

• output_oversample : int, optional Output oversample factor.

• task_trigger : int, optional Trigger channel index used to start/stop acquisition.

• task_trigger_output_channel : str, optional Name of the output channel used for task triggering.

• environment_names : list or np.ndarray, optional Ordered list of environment group names present in the nc4 file. Default is [].

• environment_active_channels : list or np.ndarray, optional Per-environment active channel masks. Default is [].

• environments : dict, optional Mapping from environment name to the corresponding :class:RattlesnakeRandomEnvironmentData instance. Populated by :meth:read_rattlesnake_nc4. Default is {}.

• **kwargs

• Any additional global nc4 attributes or variables not covered by

• the explicit parameters above are stored as instance attributes via

• __setattr__.

Attributes¶

coordinate¶

Coordinate array for all physical channels.

Builds a CoordinateArray from the node_number and node_direction columns of the channel table.

Returns¶

• CoordinateArray

• Coordinate array for all physical channels.

excitation_coordinate¶

Coordinate array for excitation (drive) channels.

Selects channels whose feedback_channel entry in the channel table is non-empty, which identifies them as drive/excitation channels.

Returns¶

• CoordinateArray

• Subset of the full channel coordinate array containing only

• channels that have a non-empty feedback_channel value.

response_coordinate¶

Coordinate array for response (non-excitation) channels.

Returns all channel coordinates that are not present in :attr:excitation_coordinate.

Returns¶

• CoordinateArray

• Subset of the full channel coordinate array containing only

• channels that do not have a non-empty feedback_channel value.

Methods¶

__init__¶

• Source: GitHub

def sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData.__init__(self, sample_rate: 'int', time_data: 'np.ndarray', channel_table: 'pd.DataFrame', file_version: 'str' = None, time_per_write: 'float' = None, time_per_read: 'float' = None, hardware: 'int' = None, hardware_file: 'str' = None, output_oversample: 'int' = None, task_trigger: 'int' = None, task_trigger_output_channel: 'str' = None, environment_names: 'list | np.ndarray' = [], environment_active_channels: 'list | np.ndarray' = [], environments: 'dict[str, RattlesnakeRandomEnvironmentData]' = {}, **kwargs)

Store all data parameters as instance attributes.

Every named parameter is assigned directly to self. Any additional keyword arguments (extra global nc4 attributes or variables) are stored via __setattr__. See the class docstring for parameter descriptions.

get_coordinate¶

• Source: GitHub

def sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData.get_coordinate(self, env_name: 'str' = None) -> 'CoordinateArray'

Coordinate array for all channels, optionally including virtual channels.

Parameters¶

• env_name : str, optional Name of the environment to query for a response transformation matrix. When None only the physical channel coordinates are returned.

Returns¶

• CoordinateArray

• Physical channel coordinates, with virtual transformed-channel

• coordinates appended when env_name is supplied and a

• response_transformation_matrix is present.

get_time_data¶

• Source: GitHub

def sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData.get_time_data(self, index: 'int | None' = None, env_name: 'str' = None) -> 'TimeHistoryArray | list[TimeHistoryArray]'

Build TimeHistoryArray objects from the source nc4 file data.

Iterates over all time_data variables found on this data object (populated by :meth:read_rattlesnake_nc4), converts each to a TimeHistoryArray, and optionally applies a response transformation matrix to produce virtual channel time histories which are appended to the array.

Parameters¶

• index : int or None, optional Zero-based index selecting a single time-data stream. When None (default) all streams are returned as a list.

• env_name : str, optional Name of the environment to query for a response_transformation_matrix. When provided and the environment has such a matrix, the transformed virtual-channel responses are computed and appended to each TimeHistoryArray. When None (default) no transformation is applied.

Returns¶

• TimeHistoryArray or list of TimeHistoryArray or None

• A single TimeHistoryArray when index is specified, or a list

• of TimeHistoryArray objects (one per time-data stream) when

• index is None. Returns None if time_data or

• sample_rate attributes are not present on this object.

read_rattlesnake_nc4¶

• Source: GitHub

def sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData.read_rattlesnake_nc4(cls, filename: 'os.PathLike | nc4.Dataset')

Read a Rattlesnake nc4 file and return a populated data object.

Loads global nc4 attributes, global variables (including all time_data* streams), the channel table, and each environment group into a new RattlesnakeData instance. Each environment group is tried against every class in _ENV_CLASSES (currently only :class:RattlesnakeRandomEnvironmentData); the first class that loads without error wins.

Parameters¶

• filename : os.PathLike or netCDF4.Dataset Path to a Rattlesnake nc4 file, or an already-open netCDF4.Dataset.

Returns¶

• RattlesnakeData

• Fully populated data object with channel_table and

• environments attributes set.

Raises¶

• Warning

• If environment groups are present in the file but none of the

• known environment classes can load any of them.

units¶

• Source: GitHub

def sdynpy.fileio.sdynpy_rattlesnake.RattlesnakeData.units(self, env_name: 'str' = None) -> 'np.ndarray'

Engineering-unit label for each channel, optionally including virtual channels.

Reads the unit column of the channel table. When env_name is provided and the named environment contains a response_transformation_matrix, the array is zero-padded (empty string '') for each virtual transformed channel.

Parameters¶

• env_name : str, optional Name of the environment to query for a response transformation matrix. When None (default) only the physical channel units are returned.

Returns¶

• np.ndarray of str

• Array of unit strings, one per channel (physical channels first,

• followed by empty-string placeholders for virtual transformed

• channels when env_name is supplied and a transformation matrix

• is present).