IO Package (ria_toolkit_oss.io)

The IO package contains utilities for input and output operations, such as loading and saving recordings to and from file.

ria_toolkit_oss.io.exists(fid)[source]

Check if the file or directory exists.

Todo

This method is not yet implemented.

Parameters:: fid (str or PathLike) – The path to the file or directory to check for existence.
Returns:: True if the file or directory exists, False otherwise.
Return type:: bool

ria_toolkit_oss.io.copy(source_path, destination_path)[source]

Copy the file or directory at source_path to destination_path.

Todo

This function is not yet implemented.

Parameters:

source_path (str or PathLike) – The path to the source file or directory.
destination_path (str or PathLike) – The path to the destination directory.

Raises:

RuntimeError – If the copy was unsuccessful.

Returns:

None

ria_toolkit_oss.io.move(source_path, destination_path, copy=False)[source]

Recursively move a file or directory at source_path to destination_path.

Todo

This method is not yet implemented.

Parameters:

source_path (str or PathLike) – The path to the source file or directory.
destination_path (str or PathLike) – The path to the destination directory.
copy (bool, optional) – If True, perform a copy instead of a move. Default is False.

Raises:

RuntimeError – If the move was unsuccessful.

Returns:

None

ria_toolkit_oss.io.validate(fid)[source]

Validate the contents of the file or directory to ensure it is not corrupted, the correct format for its extension, and readable RIA.

Todo

This method is not yet implemented.

Parameters:: fid (str or PathLike) – The path to the file or directory to validate.
Returns:: True if the file or directory is valid and readable, False otherwise.

ria_toolkit_oss.io.load_recording(file)[source]

Load a recording from file.

Parameters:

file (PathLike) – The directory path to the file(s) to load, with the file extension. To loading from SigMF, the file extension must be one of sigmf, sigmf-data, or sigmf-meta, either way both the SigMF data and meta files must be present for a successful read.

Raises:

IOError – If there is an issue encountered during the file reading process.
ValueError – If the inferred file extension is not supported.

Returns:

The recording, as initialized from file(s).

Return type:

Recording

ria_toolkit_oss.io.to_sigmf(recording, filename=None, path=None, overwrite=False)[source]

Write recording to a set of SigMF files.

The SigMF io format is defined by the SigMF Specification Project

Parameters:

recording (Recording) – The recording to be written to file.
filename (PathLike or str, optional) – The name of the file where the recording is to be saved. Defaults to auto generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.

Raises:

IOError – If there is an issue encountered during the file writing process.

Returns:

None

Examples:

>>> from ria_toolkit_oss.sdr import Synth
>>> from ria_toolkit_oss.data import Recording
>>> from ria_toolkit_oss.io import to_sigmf
>>> sdr = Synth()
>>> rec = sdr.record(center_frequency=2.4e9, sample_rate=20e6)
>>> to_sigmf(recording=rec, file="sample_recording")

ria_toolkit_oss.io.from_sigmf(file)[source]

Load a recording from a set of SigMF files.

Parameters:: file (str or PathLike) – The directory path to the SigMF recording files, without any file extension. The recording will be initialized from file_name.sigmf-data and file_name.sigmf-meta. Both the data and meta files must be present for a successful read.
Raises:: IOError – If there is an issue encountered during the file reading process.
Returns:: The recording, as initialized from the SigMF files.
Return type:: Recording

ria_toolkit_oss.io.to_npy(recording, filename=None, path=None, overwrite=False)[source]

Write recording to .npy binary file.

Parameters:

recording (Recording) – The recording to be written to file.
filename (PathLike or str, optional) – The name of the file where the recording is to be saved. Defaults to auto generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.

Raises:

IOError – If there is an issue encountered during the file writing process.

Returns:

Path where the file was saved.

Return type:

str

Examples:

>>> from ria_toolkit_oss.sdr import Synth
>>> from ria_toolkit_oss.data import Recording
>>> from ria_toolkit_oss.io import to_npy
>>> sdr = Synth()
>>> rec = sdr.record(center_frequency=2.4e9, sample_rate=20e6)
>>> to_npy(recording=rec, file="sample_recording.npy")

ria_toolkit_oss.io.from_npy(file, legacy=False)[source]

Load a recording from a .npy binary file.

Parameters:

file (str or PathLike) – The directory path to the recording file, with or without the .npy file extension.
legacy (bool, optional) – If True, load legacy format (iqdata, meta[4], extended_meta dict). If False, load current format (data, metadata dict, annotations list). Default is False.

Raises:

IOError – If there is an issue encountered during the file reading process.

Returns:

The recording, as initialized from the .npy file.

Return type:

Recording

ria_toolkit_oss.io.from_npy_legacy(file)[source]

Load a recording from legacy NPY format.

Legacy format (pre-utils) stores three numpy arrays: 1. iqdata: shape (2, N) with I and Q as separate rows (float32) 2. meta: shape (4,) with [center_freq, rec_length, decimation, sample_rate] 3. extended_meta: dict with additional metadata

Parameters:: file (str or PathLike) – The directory path to the recording file, with or without the .npy file extension.
Raises:: IOError – If there is an issue encountered during the file reading process.
Returns:: The recording, as initialized from the legacy .npy file.
Return type:: Recording

Examples:

Load legacy SRS recordings:

>>> from ria_toolkit_oss.io import from_npy_legacy
>>> rec = from_npy_legacy("~/sample_recs/srs/example_srs_recordings/bw40M_Youtube_sr46.08/iq3775MHz053601.npy")
>>> print(rec.metadata.get('protocol'))
5G40

ria_toolkit_oss.io.to_wav(recording, filename=None, path=None, target_sample_rate=48000, bits_per_sample=32, overwrite=False)[source]

Write recording to WAV file with embedded YAML metadata in LIST INFO chunk.

WAV format uses stereo audio with I (in-phase) in left channel and Q (quadrature) in right channel. Metadata is stored in standard LIST INFO chunks with RF-specific metadata encoded as YAML in the ICMT (comment) field for human readability.

Parameters:

recording (Recording) – The recording to be written to file.
filename (str, optional) – The name of the file where the recording is to be saved. Defaults to auto-generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.
target_sample_rate (int, optional) – Sample rate written to the WAV header when the recording metadata does not specify one. Defaults to 48 kHz. No decimation is performed— IQ samples are written sample-for-sample exactly as provided.
bits_per_sample (int, optional) – Bits per sample (32 for float32, 16 for int16). Default is 32 (float32).
overwrite (bool, optional) – Whether to overwrite existing files. Default is False.

Raises:

IOError – If file already exists and overwrite is False.
ValueError – If recording has multiple channels.
ValueError – If bits_per_sample is not 16 or 32.
ValueError – If 16-bit export is requested but samples fall outside [-1, 1).

Returns:

Path where the file was saved.

Return type:

str

ria_toolkit_oss.io.from_wav(file)[source]

Load recording from WAV file and extract RF metadata.

Parameters:

file (str or PathLike) – The path to the WAV file to load.

Raises:

IOError – If there is an issue reading the file.
ValueError – If file is not stereo or has unsupported format.

Returns:

The recording, as initialized from the WAV file.

Return type:

Recording

ria_toolkit_oss.io.to_blue(recording, filename=None, path=None, data_format='CI', overwrite=False)[source]

Write recording to MIDAS Blue file format.

MIDAS Blue is a legacy RF file format with a 512-byte binary header. Commonly used with X-Midas and other RF/radar signal processing tools.

Parameters:

recording (Recording) – The recording to be written to file.
filename (str, optional) – The name of the file where the recording is to be saved. Defaults to auto-generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.
data_format (str, optional) – Format code (default ‘CI’ = complex int16). Common formats: ‘CI’ (complex int16), ‘CF’ (complex float32), ‘CD’ (complex float64).
overwrite (bool, optional) – Whether to overwrite existing files. Default is False.

Raises:

IOError – If file already exists and overwrite is False.
ValueError – If recording has multiple channels.
ValueError – If data_format is not supported.
ValueError – If integer formats are requested but samples fall outside [-1, 1).

Returns:

Path where the file was saved.

Return type:

str

ria_toolkit_oss.io.from_blue(file)[source]

Load recording from MIDAS Blue file.

Parameters:

file (str or PathLike) – The path to the MIDAS Blue file to load.

Raises:

IOError – If there is an issue reading the file.
ValueError – If file format is not valid or unsupported.

Returns:

The recording, as initialized from the Blue file.

Return type:

Recording

Recording

Utilities for input/output operations on the ria_toolkit_oss.data.Recording object.

ria_toolkit_oss.io.recording.to_npy(recording, filename=None, path=None, overwrite=False)[source]

Write recording to .npy binary file.

Parameters:

recording (Recording) – The recording to be written to file.
filename (PathLike or str, optional) – The name of the file where the recording is to be saved. Defaults to auto generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.

Raises:

IOError – If there is an issue encountered during the file writing process.

Returns:

Path where the file was saved.

Return type:

str

Examples:

>>> from ria_toolkit_oss.sdr import Synth
>>> from ria_toolkit_oss.data import Recording
>>> from ria_toolkit_oss.io import to_npy
>>> sdr = Synth()
>>> rec = sdr.record(center_frequency=2.4e9, sample_rate=20e6)
>>> to_npy(recording=rec, file="sample_recording.npy")

ria_toolkit_oss.io.recording.from_npy(file, legacy=False)[source]

Load a recording from a .npy binary file.

Parameters:

file (str or PathLike) – The directory path to the recording file, with or without the .npy file extension.
legacy (bool, optional) – If True, load legacy format (iqdata, meta[4], extended_meta dict). If False, load current format (data, metadata dict, annotations list). Default is False.

Raises:

IOError – If there is an issue encountered during the file reading process.

Returns:

The recording, as initialized from the .npy file.

Return type:

Recording

ria_toolkit_oss.io.recording.from_npy_legacy(file)[source]

Load a recording from legacy NPY format.

Legacy format (pre-utils) stores three numpy arrays: 1. iqdata: shape (2, N) with I and Q as separate rows (float32) 2. meta: shape (4,) with [center_freq, rec_length, decimation, sample_rate] 3. extended_meta: dict with additional metadata

Parameters:: file (str or PathLike) – The directory path to the recording file, with or without the .npy file extension.
Raises:: IOError – If there is an issue encountered during the file reading process.
Returns:: The recording, as initialized from the legacy .npy file.
Return type:: Recording

Examples:

Load legacy SRS recordings:

>>> from ria_toolkit_oss.io import from_npy_legacy
>>> rec = from_npy_legacy("~/sample_recs/srs/example_srs_recordings/bw40M_Youtube_sr46.08/iq3775MHz053601.npy")
>>> print(rec.metadata.get('protocol'))
5G40

ria_toolkit_oss.io.recording.to_sigmf(recording, filename=None, path=None, overwrite=False)[source]

Write recording to a set of SigMF files.

The SigMF io format is defined by the SigMF Specification Project

Parameters:

recording (Recording) – The recording to be written to file.
filename (PathLike or str, optional) – The name of the file where the recording is to be saved. Defaults to auto generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.

Raises:

IOError – If there is an issue encountered during the file writing process.

Returns:

None

Examples:

>>> from ria_toolkit_oss.sdr import Synth
>>> from ria_toolkit_oss.data import Recording
>>> from ria_toolkit_oss.io import to_sigmf
>>> sdr = Synth()
>>> rec = sdr.record(center_frequency=2.4e9, sample_rate=20e6)
>>> to_sigmf(recording=rec, file="sample_recording")

ria_toolkit_oss.io.recording.from_sigmf(file)[source]

Load a recording from a set of SigMF files.

Parameters:: file (str or PathLike) – The directory path to the SigMF recording files, without any file extension. The recording will be initialized from file_name.sigmf-data and file_name.sigmf-meta. Both the data and meta files must be present for a successful read.
Raises:: IOError – If there is an issue encountered during the file reading process.
Returns:: The recording, as initialized from the SigMF files.
Return type:: Recording

ria_toolkit_oss.io.recording.to_wav(recording, filename=None, path=None, target_sample_rate=48000, bits_per_sample=32, overwrite=False)[source]

Write recording to WAV file with embedded YAML metadata in LIST INFO chunk.

WAV format uses stereo audio with I (in-phase) in left channel and Q (quadrature) in right channel. Metadata is stored in standard LIST INFO chunks with RF-specific metadata encoded as YAML in the ICMT (comment) field for human readability.

Parameters:

recording (Recording) – The recording to be written to file.
filename (str, optional) – The name of the file where the recording is to be saved. Defaults to auto-generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.
target_sample_rate (int, optional) – Sample rate written to the WAV header when the recording metadata does not specify one. Defaults to 48 kHz. No decimation is performed— IQ samples are written sample-for-sample exactly as provided.
bits_per_sample (int, optional) – Bits per sample (32 for float32, 16 for int16). Default is 32 (float32).
overwrite (bool, optional) – Whether to overwrite existing files. Default is False.

Raises:

IOError – If file already exists and overwrite is False.
ValueError – If recording has multiple channels.
ValueError – If bits_per_sample is not 16 or 32.
ValueError – If 16-bit export is requested but samples fall outside [-1, 1).

Returns:

Path where the file was saved.

Return type:

str

ria_toolkit_oss.io.recording.from_wav(file)[source]

Load recording from WAV file and extract RF metadata.

Parameters:

file (str or PathLike) – The path to the WAV file to load.

Raises:

IOError – If there is an issue reading the file.
ValueError – If file is not stereo or has unsupported format.

Returns:

The recording, as initialized from the WAV file.

Return type:

Recording

ria_toolkit_oss.io.recording.to_blue(recording, filename=None, path=None, data_format='CI', overwrite=False)[source]

Write recording to MIDAS Blue file format.

MIDAS Blue is a legacy RF file format with a 512-byte binary header. Commonly used with X-Midas and other RF/radar signal processing tools.

Parameters:

recording (Recording) – The recording to be written to file.
filename (str, optional) – The name of the file where the recording is to be saved. Defaults to auto-generated filename.
path (PathLike or str, optional) – The directory path to where the recording is to be saved. Defaults to recordings/.
data_format (str, optional) – Format code (default ‘CI’ = complex int16). Common formats: ‘CI’ (complex int16), ‘CF’ (complex float32), ‘CD’ (complex float64).
overwrite (bool, optional) – Whether to overwrite existing files. Default is False.

Raises:

IOError – If file already exists and overwrite is False.
ValueError – If recording has multiple channels.
ValueError – If data_format is not supported.
ValueError – If integer formats are requested but samples fall outside [-1, 1).

Returns:

Path where the file was saved.

Return type:

str

ria_toolkit_oss.io.recording.from_blue(file)[source]

Load recording from MIDAS Blue file.

Parameters:

file (str or PathLike) – The path to the MIDAS Blue file to load.

Raises:

IOError – If there is an issue reading the file.
ValueError – If file format is not valid or unsupported.

Returns:

The recording, as initialized from the Blue file.

Return type:

Recording

ria_toolkit_oss.io.recording.load_recording(file)[source]

Load a recording from file.

Parameters:

file (PathLike) – The directory path to the file(s) to load, with the file extension. To loading from SigMF, the file extension must be one of sigmf, sigmf-data, or sigmf-meta, either way both the SigMF data and meta files must be present for a successful read.

Raises:

IOError – If there is an issue encountered during the file reading process.
ValueError – If the inferred file extension is not supported.

Returns:

The recording, as initialized from file(s).

Return type:

Recording

ria_toolkit_oss.io.recording.convert_to_serializable(obj)[source]: Recursively convert a JSON-compatible structure into a fully JSON-serializable one. Handles cases like NumPy data types, nested dicts, lists, and sets.

ria_toolkit_oss.io.recording.generate_filename(recording, tag='rec')[source]

Generate a filename from metadata.

Parameters:: tag (str, optional) – The string at the beginning of the generated filename. Default is “rec”.
Returns:: A filename without an extension.
Return type:: str

ria_toolkit_oss.io.recording.generate_fullpath(recording, filename, path, extension, overwrite)[source]: Generate the filename, path, and fullpath of the given recording.