simplemseed
Package Contents
Classes
A FDSN Source Id. |
|
An abbreviated source id representing a station-location, like FDSN:CO_BIRD_00 |
|
Represents the fixed header section of a mseed3 record. |
|
Represents a mseed3 record. |
|
Represents the fixed header section of a miniseed2 record |
|
Represents a miniseed2 record |
|
An abbreviated source id representing a network, like FDSN:CO or FDSN:XD1994 |
|
Older style NSLC SEED Id. Consists of 2 char network, 5 char station, 2 char location and 3 char channel. |
|
An abbreviated source id representing a station, like FDSN:CO_BIRD |
|
This class acts as a container to hold encoded bytes processed by a Steim compression routine, as well as supporting information relating to the data processed. It also facilitates Steim notation and the formation of the data frames. This class stores the Steim encoding, but is ignorant of the encoding process itself…it’s just for self-referencing. |
Functions
Describe the band code. |
|
Calculates the band code for the given sample rate/period. |
|
True if the given encoding can be decompressed by this library. |
|
CRC as printable string. |
|
Decode Steim1 compression |
|
Decode Steim2 data. |
|
Decompress the samples from the provided bytes and return an array of the decompressed values. Only 16 bit short, 32 bit int, 32 bit float and 64 bit double along with Steim1 and Steim2 are supported. |
|
Encode the given numpy.ndarray or array.array into bytes. |
|
Encode samples as Steim1 compression. |
|
Encode samples as Steim2 compress. |
|
Textual name for integer SEED encoding. |
|
True if the compression is one of the primitive types, short, int float or double. |
|
Convert to ISO8601. |
|
Generator to read miniseed3 records from a file-like object. |
|
Read miniseed2 records from a file. |
|
Describe the source code. |
|
Unpacks a fixed header from bytes. |
|
Unpack a miniseed3 record from bytes, optionally verifying the CRC. |
|
Data
Data is big endian, 1 |
|
const for offset to crc in record, 28 |
|
const for fdsn prefix for extra headers, ‘FDSN:’. Note includes colon. |
|
const for size of fixed header part of record, 40 |
|
Data is little endian, 0 |
|
The SS, single station network code. |
|
Encoding for Steim1 compression |
|
Encoding for Steim2 compression |
|
The XX, testing data, network code. |
|
Current version |
API
- simplemseed.BIG_ENDIAN = 1
Data is big endian, 1
- simplemseed.CRC_OFFSET = 28
const for offset to crc in record, 28
- class simplemseed.FDSNSourceId(networkCode: Union[str, simplemseed.fdsnsourceid.NetworkSourceId], stationCode: str, locationCode: str, bandCode: str, sourceCode: str, subsourceCode: str)
A FDSN Source Id.
Defined in the specification, http://docs.fdsn.org/projects/source-identifiers/en/v1.0.
Initialization
Creates a new source id with the given codes.
- SPECIFICATION_URL = 'http://docs.fdsn.org/projects/source-identifiers/en/v1.0'
URL to specification
- SPECIFICATION_VERSION = '1.0'
FDSN Specification version that this class corresponds to.
- asNslc() simplemseed.fdsnsourceid.NslcId
Convert the source id into an older seed-style nslc.
If the source and subsource are single characters, then a 3 char channel code will be created, like BHZ. But if any are larger, then a longer string with separators will be creates, like B_AA_QW
- static createUnknown(sampRate: Optional[Union[float, int]] = None, sourceCode: str = 'H', response_lb: Optional[Union[float, int]] = None, networkCode: str = TESTDATA_NETCODE, stationCode: str = 'ABC', locationCode: str = '', subsourceCode: str = 'U') simplemseed.fdsnsourceid.FDSNSourceId
Creates a Source Id for non-real data.
Unless specified, this will have network code XX, which is defined to be a “do not use” test network. The band code can be calculated based on the optional sample rate and response lower bound. See bandCodeForRate() for details.
- static fromNslc(net: str, sta: str, loc: str, channelCode: str, startYear: str | int | None = None) simplemseed.fdsnsourceid.FDSNSourceId
Create a FDSN Source Id from an older seed-style nslc, network, station location, channel.
Optionally give the start year of the network, which will be appended if it is a SEED-style temporary network like XD.
- locationSourceId() simplemseed.fdsnsourceid.LocationSourceId
The location sourceid containing this channel.
- networkSourceId() simplemseed.fdsnsourceid.NetworkSourceId
The network sourceid containing this channel.
- static parse(sid: str) Union[simplemseed.fdsnsourceid.FDSNSourceId, simplemseed.fdsnsourceid.NetworkSourceId, simplemseed.fdsnsourceid.StationSourceId, simplemseed.fdsnsourceid.LocationSourceId]
Parse a FDSN Source Id string, like FDSN:CO_BIRD_00_H_H_Z into its constituant parts.
Also will handle parsing abbreviated codes for network, FDSN:CO station, FDSN:CO_BIRD location, FDSN:CO_BIRD_00
- static parseNslc(nslc: str, sep='.', startYear: str | int | None = None) simplemseed.fdsnsourceid.FDSNSourceId
Create a FDSN Source Id by parsing an older seed-style nslc, network, station location, channel, wheret the 4 sections are separated by the given separator, which defaults to a dot, ‘.’.
- shortChannelCode() str
Convert the channel part of the source id into an older seed-style nslc.
If the source and subsource are single characters, then a 3 char channel code will be created, like BHZ. But if any are larger, then a longer string with separators will be creates, like B_AA_QW
- stationSourceId() simplemseed.fdsnsourceid.StationSourceId
The station sourceid containing this channel.
- validate()
Validates a source id, primarily for length limitations.
Returns a tuple of either (True, None) or (False, <reason>)
- simplemseed.FDSN_PREFIX = 'FDSN:'
const for fdsn prefix for extra headers, ‘FDSN:’. Note includes colon.
- simplemseed.FIXED_HEADER_SIZE = 40
const for size of fixed header part of record, 40
- simplemseed.LITTLE_ENDIAN = 0
Data is little endian, 0
- class simplemseed.LocationSourceId(networkCode: Union[str, simplemseed.fdsnsourceid.NetworkSourceId], stationCode: str, locationCode: str)
An abbreviated source id representing a station-location, like FDSN:CO_BIRD_00
Note if the location segment in zero length, the code will end with the underscore like FDSN:IU_ANMO_
Initialization
- createFDSNSourceId(bandCode: str, sourceCode: str, subsourceCode: str) simplemseed.fdsnsourceid.FDSNSourceId
Create a channel-level FDSNSourceId within this location.
- networkSourceId() simplemseed.fdsnsourceid.NetworkSourceId
The network sourceid containing this location.
- stationSourceId() simplemseed.fdsnsourceid.StationSourceId
The station sourceid containing this location.
- validate()
Validation checks.
- class simplemseed.MSeed3Header
Represents the fixed header section of a mseed3 record.
See the [specification](http://docs.fdsn.org/projects/miniseed3/en/latest/).
Fixed header is defined as:
Field
Description
Type
Length
Offset
Content
1
Record header indicator
CHAR
2
0
ASCII ‘MS’
2
Format version
UINT8
1
2
Value of 3
3
Flags
UINT8
1
3
Record start time
4a
Nanosecond (0 - 999999999)
UINT32
4
4
4b
Year (0-65535)
UINT16
2
8
4c
Day-of-year (1 - 366)
UINT16
2
10
4d
Hour (0 - 23)
UINT8
1
12
4e
Minute (0 - 59)
UINT8
1
13
4f
Second (0 - 60)
UINT8
1
14
5
Data payload encoding
UINT8
1
15
6
Sample rate/period
FLOAT64
8
16
7
Number of samples
UINT32
4
24
8
CRC of the record
UINT32
4
28
9
Data publication version
UINT8
1
32
10
Length of identifier
UINT8
1
33
11
Length of extra headers
UINT16
2
34
12
Length of data payload
UINT32
4
36
Initialization
Create a valid but empty fixed header.
See unpackMSeed3FixedHeader() to parse form bytes.
- clone()
- crcAsHex()
String representation of CRC for record.
- property endtime
End time of record, time of last sample.
- pack()
Pack into byte array.
- recordSize()
Total record size in bytes.
- property samplePeriod
Sampling as a period, number of seconds between samples.
- property sampleRate
Sampling as a rate, number of samples per second.
- sanityCheck()
Validation checks.
- property starttime
Start time of record, time of first sample.
- class simplemseed.MSeed3Record(header: simplemseed.mseed3.MSeed3Header, identifier: Union[simplemseed.fdsnsourceid.FDSNSourceId, str], data: Union[numpy.ndarray, bytes, bytearray, array.array, list[int], list[float]], extraHeaders: Union[str, dict, None] = None)
Represents a mseed3 record.
See the [specification](http://docs.fdsn.org/projects/miniseed3/en/latest/).
Initialization
- clone()
- decompress() numpy.ndarray
Decompress data to an numpy ndarray.
- decompressedRecord()
Create a new record with decompressed data and the header encoding set to one of the primitive types: short, int, float or double
- details(showExtraHeaders=True, showData=False)
More detailed description of record.
- property eh
Extra headers, from json.
- encodedDataBytes()
Encodes data into bytes.
- encodingName()
Name of encoding, for display.
- property endtime
End time of record, time of last sample.
- getSize()
Calculates the size of the record.
Returns None if any of the identifier, extra headers or data lengths are not yet calculated.
- hasExtraHeaders()
True if record contains extra headers, ie json is not empty.
- header: simplemseed.mseed3.MSeed3Header = None
- identifier: Union[simplemseed.fdsnsourceid.FDSNSourceId, str] = None
- pack()
Pack the record contents into a bytearray.
Header values for the lengths and CRC are updated, so the record header represents the output bytes after packing.
- parseIdentifier() simplemseed.fdsnsourceid.FDSNSourceId
Parse identifier as an FDSNSOurceId.
Identifier must start with ‘FDSN:’ to be parsed.
- property starttime
Start time of record, time of first sample.
- summary()
One line summary of the record.
- exception simplemseed.Miniseed3Exception
Bases:
ExceptionException in parsing a miniseed3 record from bytes-like.
Initialization
Initialize self. See help(type(self)) for accurate signature.
- class simplemseed.MiniseedHeader(network, station, location, channel, starttime, numSamples, sampleRate, encoding=-1, byteorder=BIG_ENDIAN, sampRateFactor=0, sampRateMult=0, actFlag=0, ioFlag=0, qualFlag=0, numBlockettes=0, timeCorr=0, dataOffset=0, blocketteOffset=0, sequence_number=0, dataquality='D')
Represents the fixed header section of a miniseed2 record
Initialization
starttime can be datetime or BTime if sampleRate is zero, will be calculated from sampRateFactor and sampRateMult
- calcSeedMultipilerFactor()
- codes(sep='.')
- fdsnSourceId()
- pack()
- packBTime(header, time)
- setSampleRate(sampleRate)
- setStartTime(starttime)
- class simplemseed.MiniseedRecord(header: simplemseed.miniseed.MiniseedHeader, data, encodedDataBytes=None, blockettes=None)
Represents a miniseed2 record
Initialization
Create a new miniseed record. header - miniseed header data - uncompressed data, usually numpy array, or EncodedDataSegment if compressed encodedDataBytes - raw bytes for encoded data blockettes - miniseed blockettes
- clone()
- codes(sep='.')
- createB100()
- createB1000()
- createB1001()
- decompress()
- decompressed()
- details(showData=False)
- endtime()
- property identifier
- next_starttime()
- pack()
- packB100(recordBytes, offset, b)
- packB1000(recordBytes, offset, b)
- packB1001(recordBytes, offset, b)
- packBlockette(recordBytes, offset, b)
- packBlocketteUnknown(recordBytes, offset, bUnk)
- packData(recordBytes, offset, data)
- starttime()
- summary()
- class simplemseed.NetworkSourceId(networkCode: str, startYear: str | int | None = None)
An abbreviated source id representing a network, like FDSN:CO or FDSN:XD1994
Initialization
- createStationSourceId(stationCode) simplemseed.fdsnsourceid.StationSourceId
Create a station-level source id within this network.
- isSeedTempNet() bool
True if the network code is a 2 digit SEED-style temporary network code.
This starts with a digit or one of X,Y,Z, followed by another digit or letter, but not XX which is the network code for test data.
- isTempNetConvention() bool
True if the network code follows the temporary network code convention where the last 4 characters of the code are the start year of the network.
Generally permanant networks should not be formed in this way.
- isTempNetHistorical() bool
True if the network code follows the FDSN SourceId network code mapping for historical temporary networks.
This starts with a digit or one of X,Y,Z, followed by another digit or letter and then the 4 digit starting year of the network. For example XD1994 is the temporary network assigned the SEED code XD that started in 1994.
- isTemporary() bool
True if the network code is follows one of the temporary conventions.
For example XD, XD1994 or ABCD2025
- validate()
Validation checks.
- class simplemseed.NslcId(net: str, sta: str, loc: str, chan: str)
Older style NSLC SEED Id. Consists of 2 char network, 5 char station, 2 char location and 3 char channel.
Initialization
- simplemseed.SINGLE_STATION_NETCODE = 'SS'
The SS, single station network code.
This code may be used by any institution running a Single Station, the station should be registered with the International Registry of Seismograph Stations. Care must be taken to ensure that the station code is not the same as another station using the SS network code..
- class simplemseed.StationSourceId(networkCode: Union[str, simplemseed.fdsnsourceid.NetworkSourceId], stationCode: str)
An abbreviated source id representing a station, like FDSN:CO_BIRD
Initialization
- createLocationSourceId(locationCode) simplemseed.fdsnsourceid.LocationSourceId
Create a location-level source id within this station.
- networkSourceId() simplemseed.fdsnsourceid.NetworkSourceId
The network sourceid containing this station.
- validate()
Validation checks.
- class simplemseed.SteimFrameBlock(maxNumFrames: int = 0, steimVersion: int = 2)
This class acts as a container to hold encoded bytes processed by a Steim compression routine, as well as supporting information relating to the data processed. It also facilitates Steim notation and the formation of the data frames. This class stores the Steim encoding, but is ignorant of the encoding process itself…it’s just for self-referencing.
Converted to Python from Java, edu.iris.dmc.seedcodec @author Robert Casey (IRIS DMC) @version 12/10/2001
Initialization
Create a new block of Steim frames for a particular version of Steim copression. Instantiate object with the number of 64-byte frames that this block will contain (should connect to data record header such that a proper power of 2 boundary is formed for the data record) AND the version of Steim compression used (1 and 2 currently) the number of frames remains static…frames that are not filled with data are simply full of Nones. @param maxNumFrames the max number of frames in this Steim record, zero for unlimited @param steimVersion which version of Steim compression is being used (1,2,3).
- addEncodedWord(word: numpy.int32, samples: int, nibble: int)
Add a single 32-bit word to current frame. @param samples the number of sample differences in the word @param nibble a value of 0 to 3 that reflects the W0 encoding for this word @return boolean indicating true if the block is full (ie: the calling app should not add any more to this object)
- addEncodingNibble(bitFlag: numpy.int32)
Add encoding nibble to W0.
@param bitFlag a value 0 to 3 representing an encoding nibble
- currentSteimFrame: simplemseed.steimframeblock.SteimFrame = None
- getEncodedData()
Return the compressed byte representation of the data for inclusion in a data record. @return byte array containing the encoded, compressed data @throws IOException from called method(s)
- getNumFrames()
Return the number of frames in this frame block @return integer value indicating number of frames
- getNumSamples()
Return the number of data samples represented by this frame block @return integer value indicating number of samples
- getSteimFrames()
- getSteimVersion()
Return the version of Steim compression used @return integer value representing the Steim version (1,2,3)
- pack()
- setXsubN(word: numpy.int32)
Set the reverse integration constant X(N) explicitly to the provided word value. This method is typically used to reset X(N) should the compressor fill the frame block before all samples have been read. @param word integer value to be placed in X(N)
- steimFrameList: list[simplemseed.steimframeblock.SteimFrame] = None
- simplemseed.TESTDATA_NETCODE = 'XX'
The XX, testing data, network code.
This code is not real. It is reserved for test data, examples or transient usage when a real code cannot be used. Data with this network code should never be distributed.
- exception simplemseed.UnsupportedCompressionType(message)
- simplemseed.VERSION = None
Current version
- simplemseed.bandCodeDescribe(bandCode: str) str
Describe the band code.
See http://docs.fdsn.org/projects/source-identifiers/en/v1.0/channel-codes.html#band-code
- simplemseed.bandCodeForRate(sampRatePeriod: Optional[Union[float, int]] = None, response_lb: Optional[Union[float, int]] = None) str
Calculates the band code for the given sample rate/period.
Optionally taking into account the lower bound of the response, response_lb, to distinguish broadband from short period in the higher sample rates, where 0.1 hertz is the boundary.
If sampRatePeriod is negative, then interpreted as a period instead of a rate. So 0.1 and -10 both mean one sample every 10 seconds. Similar for response_lb.
See http://docs.fdsn.org/projects/source-identifiers/en/v1.0/channel-codes.html#band-code
- simplemseed.canDecompress(encoding: int) bool
True if the given encoding can be decompressed by this library.
- simplemseed.crcAsHex(crc)
CRC as printable string.
- simplemseed.decodeSteim1(dataBytes: bytearray, numSamples, bias=np.int32(0))
Decode Steim1 compression
Decode Steim1 compression format from the provided byte array, which contains numSamples number of samples. bias represents a previous value which acts as a starting constant for continuing differences integration. At the very start, bias is set to 0.
- simplemseed.decodeSteim2(dataBytes: bytearray, numSamples: int, bias: int = 0)
Decode Steim2 data.
Decode the indicated number of samples from the provided byte array and return an integer array of the decompressed values. Being differencing compression, there may be an offset carried over from a previous data record. This offset value can be placed in <b>bias</b>, otherwise leave the value as 0.
- simplemseed.decompress(compressionType: int, dataBytes: bytearray, numSamples: int, littleEndian: bool) numpy.ndarray
Decompress the samples from the provided bytes and return an array of the decompressed values. Only 16 bit short, 32 bit int, 32 bit float and 64 bit double along with Steim1 and Steim2 are supported.
@param compressionType compression format as defined in SEED blockette 1000 @param dataBytes input bytes to be decoded @param numSamples the number of samples that can be decoded from array <b>b</b> @param littleEndian if True, dataBytes is little-endian (intel byte order) <b>b</b>. @returns array of length <b>numSamples</b>. @throws CodecException fail to decompress. @throws UnsupportedCompressionType unsupported compression type
- simplemseed.encode(data, encoding=None, littleEndian=True)
Encode the given numpy.ndarray or array.array into bytes.
Note that currently no actual compression is done, the resulting bytes will occupy the same space, just converted for output. If encoding is not given, the encoding will be guessed from the array type. If endian is not given, defaults to little endian.
- simplemseed.encodeSteim1(samples: Union[numpy.ndarray, list[int]], frames: int = 0, bias: numpy.int32 = 0, offset: int = 0) bytearray
Encode samples as Steim1 compression.
Encode the array of integer values into a Steim 1 * compressed byte frame block. For miniseed2 you should not create a byte block any greater than 63 64-byte frames. maxFrames=0 implies unlimited number of frames, usually for miniseed3. <b>maxFrames</b> represents the number of frames to be written. This number should be determined from the desired logical record length <i>minus</i> the data offset from the record header (modulo 64) If <b>samples</b> is exhausted before all frames are filled, the remaining frames will be Nones. <b>bias</b> is a value carried over from a previous data record, representing X(-1)…set to 0 otherwise @param samples the data points represented as signed integers @param frames the number of Steim frames to use in the encoding @param bias offset for use as a constant for the first difference, otherwise set to 0 @return SteimFrameBlock containing encoded byte array @throws SteimException samples array is zero size @throws SteimException number of frames is a negative value
- simplemseed.encodeSteim1FrameBlock(samples: Union[numpy.ndarray, list[int]], frames: int = 0, bias: numpy.int32 = 0, offset: int = 0) simplemseed.steimframeblock.SteimFrameBlock
- simplemseed.encodeSteim2(samples: Union[numpy.ndarray, list[int]], frames: int = 0, bias: numpy.int32 = 0)
Encode samples as Steim2 compress.
Encode the array of integer values into a Steim 2 * compressed byte frame block. For miniseed2 you should not create a byte block any greater than 63 64-byte frames. <b>frames</b> represents the number of frames to be written. This number should be determined from the desired logical record length <i>minus</i> the data offset from the record header (modulo 64) If <b>samples</b> is exhausted before all frames are filled, the remaining frames will be None. <b>bias</b> is a value carried over from a previous data record, representing X(-1)…set to 0 otherwise @param samples the data points represented as signed integers @param frames the number of Steim frames to use in the encoding @param bias offset for use as a constant for the first difference, otherwise set to 0 @return SteimFrameBlock containing encoded byte array @throws SteimException samples array is zero size @throws SteimException number of frames is not a positive value @throws SteimException cannot encode more than 63 frames
- simplemseed.encodeSteim2FrameBlock(samples: Union[numpy.ndarray, list[int]], frames: int = 0, bias: numpy.int32 = 0) simplemseed.steimframeblock.SteimFrameBlock
- simplemseed.encodingName(encoding)
Textual name for integer SEED encoding.
- simplemseed.isPrimitiveCompression(compressionType: int) bool
True if the compression is one of the primitive types, short, int float or double.
- simplemseed.isoWZ(time) str
Convert to ISO8601.
Convert a datetime object to an ISO8601 string, replacing the ending timezone with a Z if it is +00:00.
- simplemseed.readMSeed3Records(fileptr, check_crc=True, matchsid=None, merge=False, verbose=False)
Generator to read miniseed3 records from a file-like object.
Optionally filter on matchsid regular expression. Also optionally merge contiguous records.
Example: .. code-block:: python
- for msr in simplemseed.readMSeed3Records(infile):
# do something… pass
- simplemseed.readMiniseed2Records(fileptr, matchsid=None)
Read miniseed2 records from a file.
Optionally, filter records by matching the source id with a regular expression.
- simplemseed.sourceCodeDescribe(sourceCode: str) str
Describe the source code.
See http://docs.fdsn.org/projects/source-identifiers/en/v1.0/channel-codes.html
- simplemseed.unpackBlockette(recordBytes, offset, endianChar, dataOffset)
- simplemseed.unpackMSeed3FixedHeader(recordBytes)
Unpacks a fixed header from bytes.
Returns a MSeed3Header object.
- simplemseed.unpackMSeed3Record(recordBytes, check_crc=True)
Unpack a miniseed3 record from bytes, optionally verifying the CRC.
Returns a MSeed3Record object.
- simplemseed.unpackMiniseedHeader(recordBytes, endianChar='>')
- simplemseed.unpackMiniseedRecord(recordBytes)