pyrocko.io

Low-level input and output of seismic waveforms, metadata and earthquake catalogs.

Input and output (IO) for various different file formats is implemented in the submodules of pyrocko.io. pyrocko.io itself provides a simple unified interface to load and save seismic waveforms to a few different file formats. For a higher-level approach to accessing seismic data see Squirrel - Data access infrastructure.

Seismic waveform IO

The data model used for the Trace objects in Pyrocko is most closely matched by the Mini-SEED file format. However, a difference is, that Mini-SEED limits the length of the network, station, location, and channel codes to 2, 5, 2, and 3 characters, respectively.

format	format identifier	load	save	note
Mini-SEED	mseed	yes	yes
SAC	sac	yes	yes	[1]
SEG Y rev1	segy	some
SEISAN	seisan, seisan.l, seisan.b	yes		[2]
KAN	kan	yes		[3]
YAFF	yaff	yes	yes	[4]
ASCII Table	text		yes	[5]
GSE1	gse1	some
GSE2	gse2	some
DATACUBE	datacube	yes
SUDS	suds	some
CSS	css	yes
TDMS iDAS	tdms_idas	yes
HDF5 iDAS	hdf5_idas	yes

Notes

[1]

For SAC files, the endianness is guessed. Additional header information is stored in the Trace’s meta attribute.

[2]

Seisan waveform files can be in little (seisan.l) or big endian (seisan.b) format. seisan currently is an alias for seisan.l.

[3]

The KAN file format has only been seen once by the author, and support for it may be removed again.

[4]

YAFF is an in-house, experimental file format, which should not be released into the wild.

[5]

ASCII tables with two columns (time and amplitude) are output - meta information will be lost.

Modules

pyrocko.io.css	Reader of CSS wfdisc waveform data.
pyrocko.io.datacube	Reader for DiGOS DATA-CUBE³ raw data.
pyrocko.io.enhanced_sacpz	Reader for enhanced SAC pole-zero files.
pyrocko.io.eventdata	Event data access interface (deprecated).
pyrocko.io.gcf	Reader for the Güralp GCF format.
pyrocko.io.gse1	Reader for GSE1 files.
pyrocko.io.gse2	Reader for GSE2.0 (IMS) waveform files.
pyrocko.io.hdf5_idas	Reader for Silixia iDAS HDF5 files.
pyrocko.io.hdf5_optodas
pyrocko.io.ims	Read and write GSE2.0, GSE2.1, and IMS1.0 files.
pyrocko.io.io_common	IO related exception definitions and utilities.
pyrocko.io.kan	Reader for KAN files.
pyrocko.io.mseed	Read/write MiniSEED files (wraps libmseed).
pyrocko.io.quakeml	QuakeML 1.2 input, output, and data model.
pyrocko.io.rdseed	Access to SEED volumes by interfacing rdseed (deprecated).
pyrocko.io.resp	Reader for RESP files.
pyrocko.io.sac	SAC waveform file input, output and data model.
pyrocko.io.segy	Reader for SEGY files.
pyrocko.io.seisan_response	Read instrument responses from SEISAN files.
pyrocko.io.seisan_waveform	Read seismic waveforms from SEISAN files.
pyrocko.io.stationxml	FDSN StationXML input, output and data model.
pyrocko.io.suds	Reader for SUDS waveforms and station information.
pyrocko.io.tdms_idas	Reader for Silixia iDAS TDMS files.
pyrocko.io.yaff	File IO module for SICK traces format.

Functions

iload(filename[, format, getdata, substitutions])	Load traces from file (iterator version).
load(filename[, format, getdata, substitutions])	Load traces from file.
save(traces, filename_template[, format, ...])	Save traces to file(s).

load(filename, format='mseed', getdata=True, substitutions=None)

Load traces from file.

Parameters:

• format – format of the file ('detect', 'from_extension', 'mseed', 'sac', 'segy', 'seisan', 'seisan.l', 'seisan.b', 'kan', 'yaff', 'gse1', 'gse2', 'gcf', 'datacube', 'suds', 'css', 'tdms_idas', 'hdf5_idas')

• getdata – if True (the default), read data, otherwise only read traces metadata

• substitutions – dict with substitutions to be applied to the traces metadata

Returns:

list of loaded traces

When format is set to 'detect', the file type is guessed from the first 512 bytes of the file. Only Mini-SEED, SAC, GSE1, and YAFF format are detected. When format is set to 'from_extension', the filename extension is used to decide what format should be assumed. The filename extensions considered are (matching is case insensitive): '.sac', '.kan', '.sgy', '.segy', '.yaff', everything else is assumed to be in Mini-SEED format.

This function calls iload() and aggregates the loaded traces in a list.

iload(filename, format='mseed', getdata=True, substitutions=None)

Load traces from file (iterator version).

This function works like load(), but returns an iterator which yields the loaded traces.

save(traces, filename_template, format='mseed', additional={}, stations=None, overwrite=True, append=False, check_append=False, check_append_merge=False, check_append_hook=None, **kwargs)

Save traces to file(s).

Parameters:

• traces – a trace or an iterable of traces to store

• filename_template – filename template with placeholders for trace metadata. Uses normal python ‘%(placeholder)s’ string templates. The following placeholders are considered: network, station, location, channel, tmin (time of first sample), tmax (time of last sample), tmin_ms, tmax_ms, tmin_us, tmax_us. The versions with ‘_ms’ include milliseconds, the versions with ‘_us’ include microseconds.

• format – 'mseed', 'sac', 'text', 'yaff', 'gse2'

• additional – dict with custom template placeholder fillins.

• overwrite' – if False, raise an exception if file exists

• append' – append traces to the file if the file exists

• check_append' – ensure that appended traces do not overlap with traces already present in the file

• check_append_merge' – try to merge traces with already stored traces where check_append finds a conflict. append and check_append must be set to use this option.

• check_append_hook – callback queried for permission to append to an existing file (for example to prevent overwriting files which existed prior to the application start but to allow appending to files created in the current run). The callback takes a single argument, the current filename. If it returns False the save will either fail (if overwrite is False) or truncate the file (if overwrite is True). If the hook returns True or if no hook is installed, appending is allowed.

Returns:

list of generated filenames

Note

Network, station, location, and channel codes may be silently truncated to file format specific maximum lengthes.