File Input/Output

Shakelab provides a flexible and extensible system for importing/exporting seismic waveform data from/to various file formats.

Reading Data using the Reader Function

Input operations are centralized in the reader() function and a similar read() method available from within the StreamCollection class.

These tools support loading from single files, directories, file lists, or even custom file lists defined in a text file. Here some useful example.

Load a single file:

Python 
1from shakelab.signals.io import reader
2sc = reader('record1.sac')

Load multiple files using a wildcard pattern:

Python 
1sc = reader('data/*.mseed')

Load multiple files from a given directory:

Python 
1sc = reader('path_to_data_directory')

Load from an explicit list of filenames:

Python 
1file_list = ['station1.mseed', 'station2.mseed']
2sc = reader(file_list)

Reading from an initialised StreamCollection Object

Alternatively, data can be loaded into an already initialized StreamCollection instance using its read method:

If the read method is used sequentially on multiple files, their data is progressively added to the Stream Collection.

Python 
1sc = StreamCollection()
2sc = read('event1.sac')
3sc = read('event2.sac')

You can also append data to an existing StreamCollection using the reader:

Python 
1from shakelab.signals.io import reader
2from shakelab.signals.base import StreamCollection
3
4sc = StreamCollection()
5sc = reader('event1.sac', stream_collection=sc)

Using a List File

The reader() function also supports reading a list of waveform files specified in a plain text file. To do this, set is_db=True to explicitly indicate that file_path should be interpreted as a file list (not a waveform file).

Example file list content:

data/trace1.sac
data/trace2.sac

Example usage:

Python 
1sc = reader('filelist.txt', is_db=True)

Supported Formats

The following waveform formats are currently supported in input:

  • MiniSEED / SEED (.mseed, .ms, .seed)

  • SAC (.sac)

  • DYNA ASCII (used in ITACA database)

(Others such as SEG2, ASCII, SEISAN, GSE are planned but not yet implemented)

The reader tries to determine the format automatically based on file extension. However, the format can be explicitly specified using the format argument.

Example:

Python 
1sc = reader('waveform.bin', format='sac')

Byte Order

The byte order of the binary files can be optionally specificed with the byte_order parameter. Supported options are:

  • ‘be’ for big-endian (default)

  • ‘le’ for little-endian

Example:

Python 
1sc = reader('waveform.sac', byte_order='le')

Writing data using the Write Function

Waveform data can be written to disk using the writer() function. This function supports multiple input types and output formats.

Data can be any type between Record, Stream and StreamCollection.

Write a single MiniSEED file:

Python 
1from shakelab.signals.io import writer
2writer(sc, 'output.mseed')

Write SAC files is more complex, as a StreamCollection object can contain multiple records, and a SAC file can contain only one record. For this reason, SAC files are saved separately into a folder, which name has to be specificed in input. SAC format must be expressed explicitly.

Python 
1writer(sc, 'sac_folder', format='sac')

Where sac_output is a directory that will be created if it doesn’t exist. Each record will be saved as a separate .sac file, with names like:

sac_folder/OX.FLGR1.12.HNZ_2025-03-13T00:24:42.510000Z.sac
sac_folder/OX.FLGR1.12.HNE_2025-03-13T00:24:42.510000Z.sac
sac_folder/OX.FLGR1.12.HNN_2025-03-13T00:24:42.510000Z.sac

Overwriting existing files

By default, existing output files are not overwritten. To allow overwriting, use the owrite=True argument:

Python 
1writer(sc, 'output.mseed', owrite=True)

Supported Formats

The following waveform formats are currently supported in output:

  • MiniSEED (single file)

  • SAC (one file per record, written to a directory)

See Also

  • shakelab.signals.base.StreamCollection — Main container for loaded data.