sigmf.sigmffile.SigMFFile

class sigmf.sigmffile.SigMFFile(metadata=None, data_file=None, global_info=None, skip_checksum=False, map_readonly=True, autoscale=True)

Bases: SigMFMetafile

Methods

`add_annotation`	Insert annotation at start_index with length (if != None).
`add_capture`	Insert capture info for sample starting at start_index.
`archive`	Dump contents to SigMF archive format.
`calculate_hash`	Calculates the hash of the data file and adds it to the global section.
`dump`	Write metadata to a file.
`dumps`	Get a string representation of the metadata.
`get_annotations`	Get relevant annotations from metadata.
`get_capture_byte_boundaries`	Returns a tuple of the file byte range in a dataset of a given SigMF capture of the form [start, stop).
`get_capture_byte_boundarys`
`get_capture_info`	Returns a dictionary containing all the capture information at sample index.
`get_capture_start`	Returns a the start sample index of a given capture, will raise SigMFAccessError if this field is missing.
`get_captures`	Returns a list of dictionaries representing all captures.
`get_global_field`	Return a field from the global info, or default if the field is not set.
`get_global_info`	Returns a dictionary with all the global info.
`get_num_channels`	Return integer number of channels.
`get_sample_size`	Determines the size of a sample, in bytes, from the datatype of this set.
`get_schema`	Return a schema object valid for the current metadata
`ordered_metadata`	Get a nicer representation of _metadata.
`read_samples`	Reads the specified number of samples starting at the specified index from the associated data file.
`read_samples_in_capture`	Reads samples from the specified captures segment in its entirety.
`set_data_file`	Set the datafile path, then recalculate sample count.
`set_global_field`	Inserts a value into the global field.
`set_global_info`	Recursively override existing global metadata with new global metadata.
`set_metadata`	Read provided metadata as either None (empty), string, bytes, or dictionary.
`tofile`	Write metadata file or archive based on file extension.
`validate`	Check schema and throw error if issue.

Attributes

`ANNOTATION_KEY`
`AUTHOR_KEY`
`CAPTURE_KEY`
`COLLECTION_KEY`
`COMMENT_KEY`
`DATASET_KEY`
`DATATYPE_KEY`
`DATA_DOI_KEY`
`DATETIME_KEY`
`DESCRIPTION_KEY`
`EXTENSIONS_KEY`
`FREQUENCY_KEY`
`FREQ_LOWER_EDGE_KEY`
`FREQ_UPPER_EDGE_KEY`
`GENERATOR_KEY`
`GEOLOCATION_KEY`
`GLOBAL_INDEX_KEY`
`GLOBAL_KEY`
`HEADER_BYTES_KEY`
`HW_KEY`
`LABEL_KEY`
`LATITUDE_KEY`
`LICENSE_KEY`
`LONGITUDE_KEY`
`METADATA_ONLY_KEY`
`META_DOI_KEY`
`NUM_CHANNELS_KEY`
`OFFSET_KEY`
`RECORDER_KEY`
`SAMPLE_COUNT_KEY`
`SAMPLE_RATE_KEY`
`SAMPLE_START_KEY`
`SHA512_KEY`
`TRAILING_BYTES_KEY`
`UUID_KEY`
`VALID_ANNOTATION_KEYS`
`VALID_CAPTURE_KEYS`
`VALID_GLOBAL_KEYS`
`VALID_KEYS`
`VERSION_KEY`

add_annotation(start_index, length=None, metadata=None): Insert annotation at start_index with length (if != None).

add_capture(start_index, metadata=None): Insert capture info for sample starting at start_index. If there is already capture info for this index, metadata will be merged with the existing metadata, overwriting keys if they were previously set.

archive(name=None, fileobj=None, compression=None, overwrite=False)

Dump contents to SigMF archive format.

name and fileobj are passed to SigMFArchive and are defined there.

Parameters:

name (str, optional) – Name of the archive file to create. If None, a temporary file will be created.
fileobj (file-like object, optional) – A file-like object to write the archive to. If None, a file will be created at name.
compression (str, optional) – Compression type: “gz”, “xz”, “zip”, or None (default). If None and name has a recognized compressed extension, compression is auto-detected from the extension.
overwrite (bool, default False) – If False, raise exception if archive file already exists.

calculate_hash(): Calculates the hash of the data file and adds it to the global section. Also returns a string representation of the hash.

dump(filep, pretty=True)

Write metadata to a file.

Parameters:

filep (object) – File pointer or something that json.dump() can handle.
pretty (bool, default True) – When True will write more human-readable output, otherwise will be flat JSON.

dumps(pretty=True)

Get a string representation of the metadata.

Parameters:: pretty (bool, default True) – When True will write more human-readable output, otherwise will be flat JSON.
Returns:: String representation of the metadata using json formatter.
Return type:: string

get_annotations(index=None)

Get relevant annotations from metadata.

Parameters:: index (int, default None) – If provided returns all annotations that include this sample index. When omitted returns all annotations.
Returns:: Each dictionary contains one annotation for the sample at index.
Return type:: list of dict

get_capture_byte_boundaries(index): Returns a tuple of the file byte range in a dataset of a given SigMF capture of the form [start, stop). This function works on either compliant or noncompliant SigMF Recordings.

get_capture_info(index): Returns a dictionary containing all the capture information at sample index.

get_capture_start(index): Returns a the start sample index of a given capture, will raise SigMFAccessError if this field is missing.

get_captures(): Returns a list of dictionaries representing all captures.

get_global_field(key, default=None): Return a field from the global info, or default if the field is not set.

get_global_info(): Returns a dictionary with all the global info.

get_num_channels(): Return integer number of channels.

get_sample_size(): Determines the size of a sample, in bytes, from the datatype of this set. For complex data, a ‘sample’ includes both the real and imaginary part.

get_schema(): Return a schema object valid for the current metadata

ordered_metadata()

Get a nicer representation of _metadata. Will sort keys, but put the top-level fields ‘global’, ‘captures’, ‘annotations’ in front.

Returns:: ordered_meta – Cleaner representation of _metadata with top-level keys correctly ordered and the rest of the keys sorted.
Return type:: OrderedDict

read_samples(start_index=0, count=-1)

Reads the specified number of samples starting at the specified index from the associated data file.

Parameters:

start_index (int, default 0) – Starting sample index from which to read.
count (int, default -1) – Number of samples to read. -1 will read whole file.

Returns:

data – Samples are returned as an array of float or complex, with number of dimensions equal to NUM_CHANNELS_KEY. Scaling behavior depends on the autoscale parameter set during construction.

Return type:

ndarray

read_samples_in_capture(index=0)

Reads samples from the specified captures segment in its entirety.

Parameters:

index (int, default 0) – Captures segment to read samples from.
autoscale (bool, default True) – If dataset is in a fixed-point representation, scale samples from (min, max) to (-1.0, 1.0)

Returns:

data – Samples are returned as an array of float or complex, with number of dimensions equal to NUM_CHANNELS_KEY.

Return type:

ndarray

set_data_file(data_file=None, data_buffer=None, skip_checksum=False, offset=0, size_bytes=None, map_readonly=True): Set the datafile path, then recalculate sample count. Update the hash and return the hash string if enabled.

set_global_field(key, value): Inserts a value into the global field.

set_global_info(new_global): Recursively override existing global metadata with new global metadata.

set_metadata(metadata): Read provided metadata as either None (empty), string, bytes, or dictionary.

tofile(file_path, pretty=True, toarchive=False, compression=None, skip_validate=False, overwrite=False)

Write metadata file or archive based on file extension.

The file extension determines the output format: - No extension or other extension → .sigmf-meta file (and .sigmf-data if data_buffer exists) - .sigmf → uncompressed archive - .sigmf.gz, .sigmf.xz, .sigmf.zip → compressed archive

Parameters:

file_path (string) – Location to save. Extension determines output format.
pretty (bool, default True) – When True will write human-readable JSON, otherwise flat JSON.
toarchive (bool, default False) – If True, forces archive creation (writes metadata and data to archive) regardless of file extension.
compression (str, optional) – Compression type: “gz”, “xz”, “zip”, or None. If specified, must match file extension if extension implies compression. If no archive extension is present, creates a compressed archive.
skip_validate (bool, default False) – Skip validation of metadata before writing.
overwrite (bool, default False) – If False, raise exception if output file already exists.

Examples

>>> from sigmf.siggen import SigMFGenerator
>>> import tempfile
>>> from pathlib import Path
>>> meta = SigMFGenerator().generate()
>>> tmpdir = Path(tempfile.mkdtemp())
>>> meta.tofile(tmpdir / 'recording')                # creates recording.sigmf-meta and recording.sigmf-data pair
>>> meta.tofile(tmpdir / 'recording.sigmf')          # creates recording.sigmf (archive)
>>> meta.tofile(tmpdir / 'recording.sigmf.gz')       # creates recording.sigmf.gz (compressed)
>>> meta.tofile(tmpdir / 'other', compression='xz')  # creates other.sigmf.xz

validate(): Check schema and throw error if issue.