pyrocko.io.rug

Reading and writing of carpets in the RUG file format.

RUG is Pyrocko’s native file format for Carpet objects (experimental). It uses the same record-based container as the yaff trace format (see pyrocko.file), with its own record types.

A rug file is a sequence of carpets. Each carpet is stored as a sequence of records: a carpet_header record, optional carpet_comp_codes records (one per component, omitted if all component codes are empty), optional carpet_comp_axis records (one per component axis), an optional carpet_mask record (bit-packed mask of invalid samples, omitted if no sample is masked) and a carpet_data record.

Usually, rug files are accessed through Squirrel, which can index and read them like any other waveform file format. For direct access, use iload() and save().

Functions

detect(first512)	Check whether data is the start of a rug file.
extract(tr, format)	Get the attributes named in a record format as a dict.
iload(filename[, load_data, offset, nsegments])	Read carpets from a rug file.
pack_mask(mask)	Pack a boolean mask into bytes, 8 samples per byte.
save(carpets, filename_template[, ...])	Save carpets to rug files.
unpack_mask(packed, shape)	Unpack a mask packed with pack_mask().

Classes

CarpetFileIO(file)

Low-level access to the carpet records in a rug file.

Exceptions

RugLoadError(*args, **kwargs)

Raised when a rug file is invalid.

extract(tr, format)

Get the attributes named in a record format as a dict.

exception RugLoadError(*args, **kwargs)

Bases: FileLoadError

Raised when a rug file is invalid.

pack_mask(mask)

Pack a boolean mask into bytes, 8 samples per byte.

unpack_mask(packed, shape)

Unpack a mask packed with pack_mask().

class CarpetFileIO(file)

Bases: File

Low-level access to the carpet records in a rug file.

Most users should use iload() and save() instead.

Parameters:

file – Open file object, in binary mode.

get_type(key, value)

Get the record value type to use for an array.

codes_from_dict(d)

Make codes from the code fields of an unpacked record.

carpet_from_dict(d)

Make a carpet from the collected record contents.

to_header_dict(carpet)

Get the contents of the carpet_header record.

to_component_codes_dict(codes)

Get the contents of a carpet_comp_codes record.

to_component_axis_dict(pair)

Get the contents of a carpet_comp_axis record from a (name, values) pair.

to_data_dict(data)

Get the contents of the carpet_data record.

load(load_data=True)

Read carpets from the current position of the file.

Parameters:

load_data (bool) – If False, only the headers and component codes are read; the component axes, mask and data are skipped.

Yields:

(offset, carpet) pairs, offset being the position [bytes] of the carpet’s first record in the file.

save(carpets)

Write carpets at the current position of the file.

Parameters:

carpets (iterable of Carpet) – Carpets to write.

iload(filename, load_data=True, offset=0, nsegments=0)

Read carpets from a rug file.

Parameters:

• filename (str) – Path to the file.

• load_data (bool) – If False, only the headers and component codes are read; the component axes, mask and data are skipped. The resulting carpets have no data.

• offset (int) – Position [bytes] in the file to start reading at, as yielded by an earlier call.

• nsegments (int) – Number of carpets to read at most, 0 for all.

Yields:

(offset, carpet) pairs, offset being the position [bytes] of the carpet in the file.

Raises:

FileLoadError if the file cannot be read or is invalid.

save(carpets, filename_template, additional={}, max_open_files=10, overwrite=True, append=False, check_append=False, check_append_merge=False, check_append_hook=None)

Save carpets to rug files.

The carpets are distributed to files by filling the placeholders in filename_template (see fill_template()) and the files are written in turn. Missing directories are created.

If a file exists, it is overwritten or appended to, depending on overwrite, append and the result of check_append_hook:

overwrite	append	check_append_hook	file
False	False		error
False	True	None or True	append
False	True	False	error
True	False		truncate
True	True	None or True	append
True	True	False	truncate

The error is a FileSaveError.

Parameters:

• carpets (iterable of Carpet) – Carpets to save.

• filename_template (str) – Template for the file names.

• additional (dict) – Values for additional placeholders in filename_template.

• max_open_files (int) – Unused, for compatibility with the other save functions.

• overwrite (bool) – Whether existing files may be overwritten, see above.

• append (bool) – Whether to append to existing files, see above.

• check_append (bool) – When appending, check that the new carpets do not overlap with the carpets already in the file (same codes and overlapping time spans).

• check_append_merge (bool) – With check_append, merge overlapping carpets with the ones in the file instead of raising an error. The new carpets take precedence where they overlap, and the file is rewritten with the merged result.

• check_append_hook (callable) – Function called with the path of an existing file, deciding whether it may be appended to (True) or not (False), see above.

Returns:

Paths of the files written.

Return type:

list of str

Raises:

FileSaveError if a file exists and may not be overwritten or appended to, or if check_append finds overlaps and check_append_merge is not set.

detect(first512)

Check whether data is the start of a rug file.

Parameters:

first512 (bytes) – First bytes of a file (at least the size of a record header).

Returns:

True if the data starts with a carpet header record.

Return type:

bool