Change range_bin to range_sample (#595)

* change range_bin to range_sample * modify references to range_sample * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * add variable name for ping number in doc string Co-authored-by: Wu-Jung Lee <leewujung@gmail.com> * add more descriptive name in comment for sample Co-authored-by: Wu-Jung Lee <leewujung@gmail.com> * add back ticks to variable name and remove s in ping_times Co-authored-by: Wu-Jung Lee <leewujung@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Wu-Jung Lee <leewujung@gmail.com>
OSOceanAcoustics · Mar 28, 2022 · 4239a88 · 4239a88
1 parent 1afc16a
commit 4239a88
Show file tree

Hide file tree

Showing 28 changed files with 244 additions and 236 deletions.
diff --git a/docs/source/convert.rst b/docs/source/convert.rst
@@ -285,7 +285,7 @@ currently not supported.
 .. note::
 
    Zarr datasets will be automatically chunked with default chunk sizes of
-   25000 for ``range_bin`` and 2500 for ``ping_time`` dimensions.
+   25000 for ``range_sample`` and 2500 for ``ping_time`` dimensions.
 
 
 Non-uniform data
@@ -301,7 +301,7 @@ change in the middle of the file. For example:
 - Data from different frequency channels can also be collected with
   different sampling intervals.
 
-These changes produce different number of samples along range (the ``range_bin``
+These changes produce different number of samples along range (the ``range_sample``
 dimension in the converted ``.nc`` file), which are incompatible with the goal
 to save the data as a multi-dimensional array that can be easily indexed using xarray.
 

diff --git a/docs/source/process.rst b/docs/source/process.rst
@@ -22,7 +22,7 @@ Functionality
     from the calibrated data.
   - Compute mean volume backscattering strength (MVBS) based
     on either the number of pings and sample intervals
-    (the ``range_bin`` dimension in the dataset) or a
+    (the ``range_sample`` dimension in the dataset) or a
     specified ping time interval and range interval in
     physics units (seconds and meters, respectively).
 
@@ -70,7 +70,7 @@ The steps for performing these analyses are summarized below:
       # Reduce data based on sample number
       ds_MVBS = ep.preprocess.compute_MVBS_index_binning(
            ds_Sv,             # calibrated Sv dataset
-           range_bin_num=30,  # number of sample bins to average along the range_bin dimensionm
+           range_sample_num=30,  # number of sample bins to average along the range_sample dimensionm
            ping_num=5         # number of pings to average
        )
 
@@ -81,7 +81,7 @@ The steps for performing these analyses are summarized below:
       # Remove noise
       ds_Sv_clean = ep.preprocess.remove_noise(    # obtain a denoised Sv dataset
          ds_Sv,             # calibrated Sv dataset
-         range_bin_num=30,  # number of samples along the range_bin dimension for estimating noise
+         range_sample_num=30,  # number of samples along the range_sample dimension for estimating noise
          ping_num=5,        # number of pings for estimating noise
       )
 

diff --git a/echopype/calibrate/calibrate_ek.py b/echopype/calibrate/calibrate_ek.py
@@ -594,7 +594,7 @@ def compress_pulse(self, chirp, freq_BB=None):
         for freq in freq_BB:
             backscatter_freq = (
                 backscatter.sel(frequency=freq)
-                .dropna(dim="range_bin", how="all")
+                .dropna(dim="range_sample", how="all")
                 .dropna(dim="quadrant", how="all")
                 .dropna(dim="ping_time")
             )
@@ -604,7 +604,7 @@ def compress_pulse(self, chirp, freq_BB=None):
             replica = xr.DataArray(np.conj(chirp[channel_id]), dims="window")
             # Pulse compression via rolling
             pc = (
-                backscatter_freq.rolling(range_bin=replica.size)
+                backscatter_freq.rolling(range_sample=replica.size)
                 .construct("window")
                 .dot(replica)
                 / np.linalg.norm(chirp[channel_id]) ** 2

diff --git a/echopype/convert/api.py b/echopype/convert/api.py
@@ -21,7 +21,7 @@
     "zarr": {"compressor": zarr.Blosc(cname="zstd", clevel=3, shuffle=2)},
 }
 
-DEFAULT_CHUNK_SIZE = {"range_bin": 25000, "ping_time": 2500}
+DEFAULT_CHUNK_SIZE = {"range_sample": 25000, "ping_time": 2500}
 
 NMEA_SENTENCE_DEFAULT = ["GGA", "GLL", "RMC"]
 
@@ -152,7 +152,7 @@ def _save_groups_to_file(echodata, output_path, engine, compress=True):
         io.save_file(
             echodata.beam.chunk(
                 {
-                    "range_bin": DEFAULT_CHUNK_SIZE["range_bin"],
+                    "range_sample": DEFAULT_CHUNK_SIZE["range_sample"],
                     "ping_time": DEFAULT_CHUNK_SIZE["ping_time"],
                 }
             ),
@@ -166,7 +166,7 @@ def _save_groups_to_file(echodata, output_path, engine, compress=True):
         io.save_file(
             echodata.beam_power.chunk(
                 {
-                    "range_bin": DEFAULT_CHUNK_SIZE["range_bin"],
+                    "range_sample": DEFAULT_CHUNK_SIZE["range_sample"],
                     "ping_time": DEFAULT_CHUNK_SIZE["ping_time"],
                 }
             ),

diff --git a/echopype/convert/convert_combine.py b/echopype/convert/convert_combine.py
@@ -103,7 +103,7 @@ def coerce_type(ds, group):
         io.save_file(
             ds_beam.chunk(
                 {
-                    "range_bin": DEFAULT_CHUNK_SIZE["range_bin"],
+                    "range_sample": DEFAULT_CHUNK_SIZE["range_sample"],
                     "ping_time": DEFAULT_CHUNK_SIZE["ping_time"],
                 }
             ),  # these chunk sizes are ad-hoc

diff --git a/echopype/convert/parse_ad2cp.py b/echopype/convert/parse_ad2cp.py
@@ -117,9 +117,9 @@ class Dimension(Enum):
     TIME_ECHOSOUNDER_RAW = "ping_time_echosounder_raw"
     TIME_ECHOSOUNDER_RAW_TRANSMIT = "ping_time_echosounder_raw_transmit"
     BEAM = "beam"
-    RANGE_BIN_BURST = "range_bin_burst"
-    RANGE_BIN_AVERAGE = "range_bin_average"
-    RANGE_BIN_ECHOSOUNDER = "range_bin_echosounder"
+    RANGE_SAMPLE_BURST = "range_sample_burst"
+    RANGE_SAMPLE_AVERAGE = "range_sample_average"
+    RANGE_SAMPLE_ECHOSOUNDER = "range_sample_echosounder"
     NUM_ALTIMETER_SAMPLES = "num_altimeter_samples"
     SAMPLE = "sample"
     SAMPLE_TRANSMIT = "sample_transmit"
@@ -890,21 +890,21 @@ def checksum(data: bytes) -> int:
         return checksum
 
 
-RANGE_BINS = {
-    DataRecordType.AVERAGE_VERSION2: Dimension.RANGE_BIN_AVERAGE,
-    DataRecordType.AVERAGE_VERSION3: Dimension.RANGE_BIN_AVERAGE,
-    DataRecordType.BURST_VERSION2: Dimension.RANGE_BIN_BURST,
-    DataRecordType.BURST_VERSION3: Dimension.RANGE_BIN_BURST,
-    DataRecordType.ECHOSOUNDER: Dimension.RANGE_BIN_ECHOSOUNDER,
+RANGE_SAMPLES = {
+    DataRecordType.AVERAGE_VERSION2: Dimension.RANGE_SAMPLE_AVERAGE,
+    DataRecordType.AVERAGE_VERSION3: Dimension.RANGE_SAMPLE_AVERAGE,
+    DataRecordType.BURST_VERSION2: Dimension.RANGE_SAMPLE_BURST,
+    DataRecordType.BURST_VERSION3: Dimension.RANGE_SAMPLE_BURST,
+    DataRecordType.ECHOSOUNDER: Dimension.RANGE_SAMPLE_ECHOSOUNDER,
 }
 
 
-def range_bin(data_record_type: DataRecordType) -> Dimension:
+def range_sample(data_record_type: DataRecordType) -> Dimension:
     """
-    Gets the correct range bin dimension for the given data record type
+    Gets the correct range sample dimension for the given data record type
     """
 
-    return RANGE_BINS[data_record_type]
+    return RANGE_SAMPLES[data_record_type]
 
 
 class HeaderOrDataRecordFormat:
@@ -1104,7 +1104,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_BURST,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="m/s",
                     field_unit_conversion=lambda packet, x: x
@@ -1123,7 +1123,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_AVERAGE,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="m/s",
                     field_unit_conversion=lambda packet, x: x
@@ -1142,7 +1142,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_ECHOSOUNDER,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="m/s",
                     field_unit_conversion=lambda packet, x: x
@@ -1161,7 +1161,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_BURST,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="dB/count",
                     field_unit_conversion=lambda packet, x: x / 2,
@@ -1179,7 +1179,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_AVERAGE,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="dB/count",
                     field_unit_conversion=lambda packet, x: x / 2,
@@ -1197,7 +1197,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_ECHOSOUNDER,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="dB/count",
                     field_unit_conversion=lambda packet, x: x / 2,
@@ -1215,7 +1215,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_BURST,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="0-100",
                     field_exists_predicate=lambda packet: packet.is_burst()
@@ -1232,7 +1232,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_AVERAGE,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="0-100",
                     field_exists_predicate=lambda packet: packet.is_average()
@@ -1249,7 +1249,7 @@ def data_record_format(
                     field_dimensions=lambda data_record_type: [
                         Dimension.TIME_ECHOSOUNDER,
                         Dimension.BEAM,
-                        range_bin(data_record_type),
+                        range_sample(data_record_type),
                     ],
                     field_units="0-100",
                     field_exists_predicate=lambda packet: packet.is_echosounder()
@@ -1397,7 +1397,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_BURST,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="m/s",
                 field_unit_conversion=lambda packet, x: x
@@ -1416,7 +1416,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_AVERAGE,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="m/s",
                 field_unit_conversion=lambda packet, x: x
@@ -1435,7 +1435,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_ECHOSOUNDER,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="m/s",
                 field_unit_conversion=lambda packet, x: x
@@ -1454,7 +1454,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_BURST,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="dB/count",
                 field_unit_conversion=lambda packet, x: x / 2,
@@ -1472,7 +1472,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_AVERAGE,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="dB/count",
                 field_unit_conversion=lambda packet, x: x / 2,
@@ -1490,7 +1490,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_ECHOSOUNDER,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="dB/count",
                 field_unit_conversion=lambda packet, x: x / 2,
@@ -1508,7 +1508,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_BURST,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="0-100",
                 field_exists_predicate=lambda packet: packet.is_burst()
@@ -1525,7 +1525,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_AVERAGE,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="0-100",
                 field_exists_predicate=lambda packet: packet.is_average()
@@ -1542,7 +1542,7 @@ def data_record_format(
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME_ECHOSOUNDER,
                     Dimension.BEAM,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="0-100",
                 field_exists_predicate=lambda packet: packet.is_echosounder()
@@ -1644,7 +1644,7 @@ def data_record_format(
                 ],
                 field_dimensions=[
                     Dimension.TIME_ECHOSOUNDER,
-                    Dimension.RANGE_BIN_ECHOSOUNDER,
+                    Dimension.RANGE_SAMPLE_ECHOSOUNDER,
                 ],
                 field_units="dB/count",
                 field_unit_conversion=lambda packet, x: x / 100,
@@ -1759,7 +1759,7 @@ def data_record_format(
                 field_shape=lambda packet: [packet.data.get("num_cells", 0)],
                 field_dimensions=lambda data_record_type: [
                     Dimension.TIME,
-                    range_bin(data_record_type),
+                    range_sample(data_record_type),
                 ],
                 field_units="%",
                 field_exists_predicate=lambda packet: packet.data[

diff --git a/echopype/convert/parse_base.py b/echopype/convert/parse_base.py
@@ -40,7 +40,7 @@ def __init__(self, file, params, storage_options):
         self.config_datagram = None
         self.ping_data_dict = defaultdict(lambda: defaultdict(list))
         self.ping_time = defaultdict(list)  # store ping time according to channel
-        self.num_range_bin_groups = None  # number of range_bin groups
+        self.num_range_sample_groups = None  # number of range_sample groups
         self.ch_ids = defaultdict(
             list
         )  # Stores the channel ids for each data type (power, angle, complex)

diff --git a/echopype/convert/set_groups_ad2cp.py b/echopype/convert/set_groups_ad2cp.py
@@ -177,9 +177,9 @@ def set_platform(self) -> xr.Dataset:
                 "ping_time_average": self.ds.get("ping_time_average"),
                 "ping_time_echosounder": self.ds.get("ping_time_echosounder"),
                 "beam": self.ds.get("beam"),
-                "range_bin_burst": self.ds.get("range_bin_burst"),
-                "range_bin_average": self.ds.get("range_bin_average"),
-                "range_bin_echosounder": self.ds.get("range_bin_echosounder"),
+                "range_sample_burst": self.ds.get("range_sample_burst"),
+                "range_sample_average": self.ds.get("range_sample_average"),
+                "range_sample_echosounder": self.ds.get("range_sample_echosounder"),
             },
             attrs={
                 "platform_name": self.ui_param["platform_name"],
@@ -191,8 +191,8 @@ def set_platform(self) -> xr.Dataset:
 
     def set_beam(self) -> xr.Dataset:
         # TODO: should we divide beam into burst/average (e.g., beam_burst, beam_average)
-        # like was done for range_bin (we have range_bin_burst, range_bin_average,
-        # and range_bin_echosounder)?
+        # like was done for range_sample (we have range_sample_burst, range_sample_average,
+        # and range_sample_echosounder)?
         data_vars = {
             "number_of_beams": self.ds.get("num_beams"),
             "coordinate_system": self.ds.get("coordinate_system"),
@@ -241,9 +241,9 @@ def set_beam(self) -> xr.Dataset:
                 "ping_time_average": self.ds.get("ping_time_average"),
                 "ping_time_echosounder": self.ds.get("ping_time_echosounder"),
                 "beam": self.ds.get("beam"),
-                "range_bin_burst": self.ds.get("range_bin_burst"),
-                "range_bin_average": self.ds.get("range_bin_average"),
-                "range_bin_echosounder": self.ds.get("range_bin_echosounder"),
+                "range_sample_burst": self.ds.get("range_sample_burst"),
+                "range_sample_average": self.ds.get("range_sample_average"),
+                "range_sample_echosounder": self.ds.get("range_sample_echosounder"),
                 "altimeter_sample_bin": self.ds.get("altimeter_sample_bin"),
             },
             attrs={"pulse_compressed": self.pulse_compressed},
@@ -350,9 +350,9 @@ def set_vendor(self) -> xr.Dataset:
                 "sample": self.ds.get("sample"),
                 "sample_transmit": self.ds.get("sample_transmit"),
                 "beam": self.ds.get("beam"),
-                "range_bin_average": self.ds.get("range_bin_average"),
-                "range_bin_burst": self.ds.get("range_bin_burst"),
-                "range_bin_echosounder": self.ds.get("range_bin_echosounder"),
+                "range_sample_average": self.ds.get("range_sample_average"),
+                "range_sample_burst": self.ds.get("range_sample_burst"),
+                "range_sample_echosounder": self.ds.get("range_sample_echosounder"),
             },
             attrs={**attrs, "pulse_compressed": self.pulse_compressed},
         )