From 770b191b713c696080cb4f084b315ba71d77c84b Mon Sep 17 00:00:00 2001
From: kienle <kienle@passcal.nmt.edu>
Date: Mon, 22 May 2023 16:18:42 -0600
Subject: [PATCH] Documentation
---
.../read_mseed_experiment/mseed_helper.py | 36 ++++++++++++++-----
1 file changed, 27 insertions(+), 9 deletions(-)
diff --git a/sohstationviewer/model/mseed/read_mseed_experiment/mseed_helper.py b/sohstationviewer/model/mseed/read_mseed_experiment/mseed_helper.py
index 59f41c5fe..28f0c228b 100644
--- a/sohstationviewer/model/mseed/read_mseed_experiment/mseed_helper.py
+++ b/sohstationviewer/model/mseed/read_mseed_experiment/mseed_helper.py
@@ -16,8 +16,9 @@ class Unpacker:
def unpack(self, format: str, buffer: bytes):
"""
-
- :param format:
+ Unpack a string of bytes into a tuple of values based on the given
+ format
+ :param format: the format used to unpack the byte string
:param buffer: the byte string
:return: a tuple containing the unpacked values.
"""
@@ -31,6 +32,10 @@ class Unpacker:
@dataclass
class FixedHeader:
+ """
+ The fixed portion of the header of a data record. All fields are stored as
+ bytes to minimize time wasted on decoding unused values.
+ """
sequence_number: bytes
data_header_quality_indicator: bytes
reserved: bytes
@@ -53,6 +58,10 @@ class FixedHeader:
@dataclass
class Blockette1000:
+ """
+ Blockette 100 of a data record. All fields are stored as bytes to minimize
+ time wasted on decoding unused values.
+ """
blockette_type: bytes
next_blockette_offset: bytes
encoding_format: bytes
@@ -63,6 +72,9 @@ class Blockette1000:
@dataclass
class RecordMetadata:
+ """
+ The metadata of a data record.
+ """
station: str
location: str
channel: str
@@ -94,12 +106,11 @@ def get_header_endianness(header: FixedHeader):
not affect it. Similarly, 257 is also 2-octet-palindromic. Meanwhile, 1 and
256 are counterparts when encoded as pairs of octets. Because they are both
valid values for day of year, it is impossible to make a conclusion about
- endianness based on day of year if it is either 1 or 256 in big-endian. On
- the other hand, 257 is a palindrome. These two facts combined means that we
- cannot determine the endianness of the header that starts on the
- aforementioned dates. The way this function was written, the endianness
- will be determined to be big in these cases. This problem is also recorded
- in libmseed.
+ endianness based on day of year if it is either 1 or 256 in big-endian.
+ These facts combined means that we cannot determine the endianness of the
+ header whose record starts on the aforementioned dates. The way this
+ function was written, the endianness will be recorded as big in these
+ cases. This problem is also recorded in libmseed.
:param header: the fixed header of the data record
:return: either of the string 'big' or 'little' depending on the extracted
@@ -122,7 +133,6 @@ def get_data_endianness(blockette_1000: Blockette1000):
"""
Get endianness of a data record by examining blockette 1000.
- :param fixed_header: the fixed header of the data record.
:param blockette_1000: the blockette 1000 of the data record.
"""
# The byte order is only one byte so using big or little endian does not
@@ -160,6 +170,14 @@ def calculate_sample_rate(factor: int, multiplier: int) -> float:
def get_record_metadata(header: FixedHeader, header_unpacker: Unpacker):
+ """
+ Extract and parse the metadata of a data record from its fixed header.
+
+ :param header: the fixed header of the data record
+ :param header_unpacker: the unpacker corresponding to the data record;
+ needed so that the correct byte order can be used
+ :return: the extract record metadata
+ """
station = header.station.decode('utf-8').rstrip()
location = header.location.decode('utf-8').rstrip()
channel = header.channel.decode('utf-8').rstrip()
--
GitLab