obspy.core.stream.read

read(pathname_or_url=None, format=None, headonly=False, starttime=None, endtime=None, nearest_sample=True, dtype=None, apply_calib=False, check_compression=True, **kwargs)

Read waveform files into an ObsPy Stream object.

The read() function opens either one or multiple waveform files given via file name or URL using the pathname_or_url attribute.

The format of the waveform file will be automatically detected if not given. See the Supported Formats section below for available formats.

This function returns an ObsPy Stream object, a list-like object of multiple ObsPy Trace objects.

Parameters:

• pathname_or_url (str, io.BytesIO, or pathlib.Path, optional) – String containing a file name or a URL, a Path object, or a open file-like object. Wildcards are allowed for a file name. If this attribute is omitted, an example Stream object will be returned.

• format (str, optional) – Format of the file to read (e.g. "MSEED"). See the Supported Formats section below for a list of supported formats. If format is set to None it will be automatically detected which results in a slightly slower reading. If a format is specified, no further format checking is done.

• headonly (bool, optional) – If set to True, read only the data header. This is most useful for scanning available meta information of huge data sets.

• starttime (UTCDateTime, optional) – Specify the start time to read.

• endtime (UTCDateTime, optional) – Specify the end time to read.

• nearest_sample (bool, optional) – Only applied if starttime or endtime is given. Select nearest sample or the one containing the specified time. For more info, see trim().

• dtype (numpy.dtype, optional) – Convert data of all traces into given numpy.dtype.

• apply_calib (bool, optional) – Automatically applies the calibration factor trace.stats.calib for each trace, if set. Defaults to False.

• check_compression (bool, optional) – Check for compression on file and decompress if needed. This may be disabled for a moderate speed up.

• kwargs – Additional keyword arguments passed to the underlying waveform reader method.

Returns:

An ObsPy Stream object.

Basic Usage

In most cases a filename is specified as the only argument to read(). For a quick start you may omit all arguments and ObsPy will create and return a basic example seismogram. Further usages of the read() function can be seen in the Further Examples section underneath.

>>> from obspy import read
>>> st = read()
>>> print(st)  
3 Trace(s) in Stream:
BW.RJOB..EHZ | 2009-08-24T00:20:03.000000Z - ... | 100.0 Hz, 3000 samples
BW.RJOB..EHN | 2009-08-24T00:20:03.000000Z - ... | 100.0 Hz, 3000 samples
BW.RJOB..EHE | 2009-08-24T00:20:03.000000Z - ... | 100.0 Hz, 3000 samples

Supported Formats

Additional ObsPy modules extend the functionality of the read() function. The following table summarizes all known file formats currently supported by ObsPy. The table order also reflects the order of the autodetection routine if no format option is specified.

Please refer to the Linked Function Call of each module for any extra options available at the import stage.

Format	Used Module	Linked Function Call
AH	obspy.io.ah	obspy.io.ah.core._read_ah()
ALSEP_PSE	obspy.io.alsep	obspy.io.alsep.core._read_pse()
ALSEP_WTH	obspy.io.alsep	obspy.io.alsep.core._read_wth()
ALSEP_WTN	obspy.io.alsep	obspy.io.alsep.core._read_wtn()
CSS	obspy.io.css	obspy.io.css.core._read_css()
CYBERSHAKE	obspy.io.cybershake	obspy.io.cybershake.core._read_cybershake()
DMX	obspy.io.dmx	obspy.io.dmx.core._read_dmx()
GCF	obspy.io.gcf	obspy.io.gcf.core._read_gcf()
GSE1	obspy.io.gse2	obspy.io.gse2.core._read_gse1()
GSE2	obspy.io.gse2	obspy.io.gse2.core._read_gse2()
KINEMETRICS_EVT	obspy.io.kinemetrics	obspy.io.kinemetrics.core.read_evt()
KNET	obspy.io.nied	obspy.io.nied.knet._read_knet_ascii()
MSEED	obspy.io.mseed	obspy.io.mseed.core._read_mseed()
MSEED3	obspy.io.mseed3	obspy.io.mseed3.core._read_mseed3()
NNSA_KB_CORE	obspy.io.css	obspy.io.css.core._read_nnsa_kb_core()
PDAS	obspy.io.pdas	obspy.io.pdas.core._read_pdas()
PICKLE	obspy.core.stream	obspy.core.stream._read_pickle()
Q	obspy.io.sh	obspy.io.sh.core._read_q()
REFTEK130	obspy.io.reftek	obspy.io.reftek.core._read_reftek130()
RG16	obspy.io.rg16	obspy.io.rg16.core._read_rg16()
SAC	obspy.io.sac	obspy.io.sac.core._read_sac()
SACXY	obspy.io.sac	obspy.io.sac.core._read_sac_xy()
SEG2	obspy.io.seg2	obspy.io.seg2.seg2._read_seg2()
SEGY	obspy.io.segy	obspy.io.segy.core._read_segy()
SEISAN	obspy.io.seisan	obspy.io.seisan.core._read_seisan()
SH_ASC	obspy.io.sh	obspy.io.sh.core._read_asc()
SLIST	obspy.io.ascii	obspy.io.ascii.core._read_slist()
SU	obspy.io.segy	obspy.io.segy.core._read_su()
TSPAIR	obspy.io.ascii	obspy.io.ascii.core._read_tspair()
WAV	obspy.io.wav	obspy.io.wav.core._read_wav()
WIN	obspy.io.win	obspy.io.win.core._read_win()
Y	obspy.io.y	obspy.io.y.core._read_y()

Next to the read() function the write() method of the returned Stream object can be used to export the data to the file system.

Further Examples

Example waveform files may be retrieved via https://examples.obspy.org.

1. Reading multiple local files using wildcards.

   The following code uses wildcards, in this case it matches two files. Both files are then read into a single Stream object.

   >>> from obspy import read  
   >>> st = read("/path/to/loc_R*.z")  
   >>> print(st)  
   2 Trace(s) in Stream:
   .RJOB..Z | 2005-08-31T02:33:49.850000Z - ... | 200.0 Hz, 12000 samples
   .RNON..Z | 2004-06-09T20:05:59.850000Z - ... | 200.0 Hz, 12000 samples
   

2. Reading a local file without format detection.

   Using the format parameter disables the automatic detection and enforces reading a file in a given format.

   >>> from obspy import read
   >>> st = read("/path/to/loc_RJOB20050831023349.z", format="GSE2")
   >>> print(st)  
   1 Trace(s) in Stream:
   .RJOB..Z | 2005-08-31T02:33:49.850000Z - ... | 200.0 Hz, 12000 samples
   

3. Reading a remote file via HTTP protocol.

   >>> from obspy import read
   >>> st = read("https://examples.obspy.org/loc_RJOB20050831023349.z")
   >>> print(st)  
   1 Trace(s) in Stream:
   .RJOB..Z | 2005-08-31T02:33:49.850000Z - ... | 200.0 Hz, 12000 samples
   

4. Reading a compressed files.

   >>> from obspy import read
   >>> st = read("/path/to/tspair.ascii.gz")
   >>> print(st)  
   1 Trace(s) in Stream:
   XX.TEST..BHZ | 2008-01-15T00:00:00.025000Z - ... | 40.0 Hz, 635 samples
   

   >>> st = read("https://examples.obspy.org/slist.ascii.bz2")
   >>> print(st)  
   1 Trace(s) in Stream:
   XX.TEST..BHZ | 2008-01-15T00:00:00.025000Z - ... | 40.0 Hz, 635 samples
   

5. Reading a file-like object.

   >>> import requests
   >>> import io
   >>> example_url = "https://examples.obspy.org/loc_RJOB20050831023349.z"
   >>> stringio_obj = io.BytesIO(requests.get(example_url).content)
   >>> st = read(stringio_obj)
   >>> print(st)  
   1 Trace(s) in Stream:
   .RJOB..Z | 2005-08-31T02:33:49.850000Z - ... | 200.0 Hz, 12000 samples
   

6. Using ‘starttime’ and ‘endtime’ parameters

   >>> from obspy import read
   >>> dt = UTCDateTime("2005-08-31T02:34:00")
   >>> st = read("https://examples.obspy.org/loc_RJOB20050831023349.z",
   ...           starttime=dt, endtime=dt+10)
   >>> print(st)  
   1 Trace(s) in Stream:
   .RJOB..Z | 2005-08-31T02:34:00.000000Z - ... | 200.0 Hz, 2001 samples