oceanstream 0.0.0.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. oceanstream/__init__.py +0 -0
  2. oceanstream/cli/__init__.py +3 -0
  3. oceanstream/cli/main.py +267 -0
  4. oceanstream/denoise/__init__.py +2 -0
  5. oceanstream/denoise/apply_masks.py +49 -0
  6. oceanstream/denoise/applying_masks_handler.py +173 -0
  7. oceanstream/denoise/background_noise_remover.py +97 -0
  8. oceanstream/denoise/create_masks.py +87 -0
  9. oceanstream/denoise/noise_masks.py +398 -0
  10. oceanstream/denoise/types.py +73 -0
  11. oceanstream/echodata/__init__.py +5 -0
  12. oceanstream/echodata/ensure_time_continuity.py +75 -0
  13. oceanstream/echodata/mvbs_computation.py +77 -0
  14. oceanstream/echodata/raw_handler.py +577 -0
  15. oceanstream/echodata/sv_computation.py +118 -0
  16. oceanstream/echodata/sv_dataset_extension.py +126 -0
  17. oceanstream/echodata/sv_interpolation.py +260 -0
  18. oceanstream/echodata/target_strength_computation.py +109 -0
  19. oceanstream/exports/__init__.py +2 -0
  20. oceanstream/exports/csv/csv_export_from_Sv.py +89 -0
  21. oceanstream/exports/csv/csv_export_from_raw.py +92 -0
  22. oceanstream/exports/csv/csv_export_nasc.py +135 -0
  23. oceanstream/exports/frequency_differencing_handler.py +210 -0
  24. oceanstream/exports/nasc.py +23 -0
  25. oceanstream/exports/nasc_computation.py +62 -0
  26. oceanstream/exports/shoals/shoal_detection_handler.py +109 -0
  27. oceanstream/exports/shoals/shoal_process.py +224 -0
  28. oceanstream/exports/shoals/shoals_handler.py +35 -0
  29. oceanstream/plot/__init__.py +2 -0
  30. oceanstream/plot/echogram.py +542 -0
  31. oceanstream/process/__init__.py +21 -0
  32. oceanstream/process/combine_zarr.py +90 -0
  33. oceanstream/process/file_processor.py +151 -0
  34. oceanstream/process/folder_processor.py +246 -0
  35. oceanstream/process/process.py +77 -0
  36. oceanstream/process/processed_data_io.py +140 -0
  37. oceanstream/settings/__init__.py +1 -0
  38. oceanstream/settings/config.py +17 -0
  39. oceanstream/utils.py +101 -0
  40. oceanstream-0.0.0.dev0.dist-info/LICENSE +21 -0
  41. oceanstream-0.0.0.dev0.dist-info/METADATA +214 -0
  42. oceanstream-0.0.0.dev0.dist-info/RECORD +46 -0
  43. oceanstream-0.0.0.dev0.dist-info/WHEEL +5 -0
  44. oceanstream-0.0.0.dev0.dist-info/dependency_links.txt +1 -0
  45. oceanstream-0.0.0.dev0.dist-info/entry_points.txt +2 -0
  46. oceanstream-0.0.0.dev0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,135 @@
1
+ from pathlib import Path
2
+
3
+ import xarray as xr
4
+ from echopype.mask.api import apply_mask
5
+ from pandas import DataFrame
6
+
7
+ from oceanstream.exports.nasc_computation import compute_per_dataset_nasc
8
+
9
+ BASE_NASC_PARAMETERS = [
10
+ {"masks": {"mask_shoal": False}, "abbreviated": True, "root_name": "fish_NASC"}
11
+ ]
12
+
13
+
14
+ def base_nasc_data(Sv: xr.Dataset, abbreviated: bool = False, root_name: str = None):
15
+ """
16
+ Given a Sv dataset, returns a dataframe containing nasc data for it
17
+
18
+ Parameters:
19
+ - Sv: xr.Dataset - Sv dataset
20
+ - abbreviated: bool - do we keep all the info, or just the NASC
21
+ - root_name: str - name to rename NASC by, if needed
22
+
23
+ Returns:
24
+ - a dictionary of nasc data
25
+
26
+ Example:
27
+ >>> base_nasc_data(Sv)
28
+ """
29
+
30
+ nasc_list = compute_per_dataset_nasc(Sv)
31
+ nasc = nasc_list["NASC_dataset"]
32
+ maximum_distance = nasc_list["maximum_distance"]
33
+ maximum_depth = nasc_list["maximum_depth"]
34
+ samples = len(Sv.ping_time) * len(Sv.range_sample) # temp
35
+
36
+ metadata = {}
37
+ if abbreviated is False:
38
+ metadata["filename"] = Path(Sv.source_filenames.values.item()).stem
39
+ metadata["start_lat"] = nasc.attrs["geospatial_lat_min"]
40
+ metadata["end_lat"] = nasc.attrs["geospatial_lat_max"]
41
+ metadata["start_lon"] = nasc.attrs["geospatial_lon_min"]
42
+ metadata["end_lon"] = nasc.attrs["geospatial_lon_max"]
43
+ metadata["start_time"] = nasc.attrs["time_coverage_start"]
44
+ metadata["end_time"] = nasc.attrs["time_coverage_start"]
45
+ metadata["start_ping"] = (0,)
46
+ metadata["end_ping"] = len(Sv.ping_time)
47
+ metadata["NASC_st_range"] = 0
48
+ metadata["NASC_en_range"] = maximum_depth
49
+ metadata["maximum_distance"] = maximum_distance
50
+
51
+ nasc_frame = nasc[["frequency_nominal", "NASC"]].to_dataframe().reset_index(drop=True)
52
+ if root_name is not None:
53
+ nasc_frame.rename(columns={"NASC": root_name}, inplace=True)
54
+ if abbreviated is False:
55
+ nasc_frame["Observed_samples"] = samples
56
+ nasc_frame["Valid_samples"] = samples
57
+
58
+ nasc_melted = nasc_frame.melt(id_vars="frequency_nominal")
59
+ nasc_melted["name"] = (
60
+ nasc_melted["variable"] + "_" + nasc_melted["frequency_nominal"].astype(str)
61
+ )
62
+ nasc_data = {r["name"]: r["value"] for index, r in nasc_melted.iterrows()}
63
+ metadata.update(nasc_data)
64
+ return metadata
65
+
66
+
67
+ def mask_nasc_data(Sv: xr.Dataset, masks={}, abbreviated: bool = False, root_name: str = None):
68
+ """
69
+ Given a Sv dataset and a dictionary where the keys are mask names and the values are true/false
70
+ it applies those masks to it reverted or not, based on the value, and returns a dict of nasc data
71
+
72
+ Parameters:
73
+ - Sv: xr.Dataset - Sv dataset
74
+ - masks: {} - dictionary of mask names and True/False on whether we negate them
75
+ - abbreviated: bool - do we keep all the info, or just the NASC
76
+ - root_name: str - name to rename NASC by, if needed
77
+
78
+ Returns:
79
+ - a dictionary of nasc data
80
+
81
+ Example:
82
+ >>> base_nasc_data(Sv)
83
+ """
84
+ Sv = Sv.copy(deep=True)
85
+ for mask in masks.keys():
86
+ if mask not in Sv:
87
+ raise ValueError(f"Mask {mask} does not exist in the dataset")
88
+ else:
89
+ if masks[mask]:
90
+ Sv[mask] = ~Sv[mask]
91
+ Sv = apply_mask(Sv, Sv[mask])
92
+ return base_nasc_data(Sv, abbreviated, root_name)
93
+
94
+
95
+ def full_nasc_data(Sv: xr.Dataset, parameter_list=BASE_NASC_PARAMETERS):
96
+ """
97
+ Given a Sv dataset and a list of potential parameters for mask_nasc_data,
98
+ it returns a dictionary containing nasc data for all possibilities.
99
+ Useful if we want to specify whether we take fish nasc, krill nasc etc
100
+
101
+ Parameters:
102
+ - Sv: xr.Dataset - Sv dataset
103
+ - parameter_list: list of parameters to pass to mask_nasc_data
104
+
105
+ Returns:
106
+ - a dictionary of nasc data
107
+
108
+ Example:
109
+ >>> full_nasc_data(Sv)
110
+ """
111
+ base = base_nasc_data(Sv)
112
+ for parameters in parameter_list:
113
+ masks = parameters["masks"]
114
+ abbreviated = parameters["abbreviated"]
115
+ root_name = parameters["root_name"]
116
+ extra = mask_nasc_data(Sv, masks, abbreviated, root_name)
117
+ base.update(extra)
118
+ return base
119
+
120
+
121
+ def write_nasc_to_csv(nasc, filename):
122
+ """
123
+ Given a nasc dict and a filename, it exports it as csv to the filename
124
+
125
+ Parameters:
126
+ - nasc: {}
127
+ the dict containing nasc metadata
128
+ - filename: str
129
+ The file name to use.
130
+
131
+ Returns:
132
+ - None
133
+ """
134
+ df = DataFrame(nasc)
135
+ df.to_csv(filename, index=False)
@@ -0,0 +1,210 @@
1
+ """
2
+ frequency_differencing_handler.py
3
+ ---------------------------------
4
+ This module offers functionalities to identify species in echosounder data using frequency differencing techniques.
5
+
6
+ Functions:
7
+
8
+ - `find_mask_freq_diff`:
9
+ Generates a mask based on the differences in Sv values between two frequencies.
10
+ This method is commonly referred to as the “frequency-differencing” or “dB-differencing” method.
11
+ It leverages the `frequency_differencing` method from the `echopype` library.
12
+
13
+ - `attach_freq_diff_mask_to_ds`:
14
+ Attaches a frequency differencing mask to a given Sv DataArray.
15
+
16
+ - `identify_krill`:
17
+ Generates and attaches a mask tailored for krill identification.
18
+ Krill are typically identified by the difference in volume backscattering strength
19
+ between 120 kHz and 38 kHz, which ranges from 2 dB to 16 dB.
20
+
21
+ - `identify_gas_bearing_organisms`:
22
+ Generates and attaches a mask for identifying gas-bearing organisms.
23
+ These organisms exhibit an acoustic signature where the difference in volume backscattering strength
24
+ between 120 kHz and 38 kHz is less than -1 dB.
25
+
26
+ - `identify_fluid_like_organisms`:
27
+ Generates and attaches a mask for identifying fluid-like organisms.
28
+ These organisms are characterized by an acoustic signature
29
+ where the difference in volume backscattering strength between 120 kHz and 38 kHz is greater than 2 dB.
30
+
31
+ Usage:
32
+
33
+ To generate a frequency differencing mask for a given Sv DataArray, `ds`, use:
34
+ `find_mask_freq_diff(ds, chanA, chanB, single_operator, single_value)`
35
+ For interval-based masking, use:
36
+ `find_mask_freq_diff(ds, chanA, chanB, interval_start_operator, interval_start_value, interval_end_operator, interval_end_value)`
37
+
38
+ To identify and attach masks for specific organisms:
39
+ `identify_krill(ds, chan38, chan120)`
40
+ `identify_gas_bearing_organisms(ds, chan38, chan120)`
41
+ `identify_fluid_like_organisms(ds, chan38, chan120)`
42
+
43
+ Note:
44
+ - Ensure the echopype library is properly installed and imported when using this module.
45
+ - Sv represents the volume backscattering strength.
46
+
47
+ """
48
+
49
+ from typing import Optional
50
+
51
+ import echopype as ep
52
+ import xarray as xr
53
+
54
+ from oceanstream.utils import add_metadata_to_mask, attach_mask_to_dataset
55
+
56
+
57
+ def find_mask_freq_diff(
58
+ ds: xr.Dataset,
59
+ chanA: str,
60
+ chanB: str,
61
+ single_operator: Optional[str] = None,
62
+ single_value: Optional[str] = None,
63
+ interval_start_operator: Optional[str] = None,
64
+ interval_start_value: Optional[str] = None,
65
+ interval_end_operator: Optional[str] = None,
66
+ interval_end_value: Optional[str] = None,
67
+ ) -> xr.DataArray:
68
+ """
69
+ Create a mask based on the differences of Sv values using a pair of frequencies.
70
+ This method is often referred to as the “frequency-differencing” or “dB-differencing” method.
71
+ This function utilizes the `frequency_differencing` method from the `echopype` library.
72
+
73
+ Parameters:
74
+ - ds (xr.Dataset): The dataset containing the Sv data to create a mask for.
75
+ - chanA (str): Channel A name.
76
+ - chanB (str): Channel B name.
77
+ - single_operator (str, optional): Operator used for non-interval masking.
78
+ - single_value (str, optional): Value used for non-interval masking.
79
+ - interval_start_operator (str, optional): Operator defining the start of an interval.
80
+ - interval_start_value (str, optional): Value defining the start of an interval.
81
+ - interval_end_operator (str, optional): Operator defining the end of an interval.
82
+ - interval_end_value (str, optional): Value defining the end of an interval.
83
+
84
+ Returns:
85
+ - xr.DataArray: A DataArray containing the mask for the Sv data.
86
+
87
+ Notes:
88
+ For more information about the `frequency_differencing` function,
89
+ refer to the echopype documentation.
90
+
91
+ Raises:
92
+ - ValueError: If an invalid combination of parameters is provided.
93
+ """
94
+ # If only single_operator and single_value are provided
95
+ if single_operator is not None and single_value is not None:
96
+ chanABEq_mask = f'"{chanA}" - "{chanB}" {single_operator} {single_value}dB'
97
+ mask = ep.mask.frequency_differencing(source_Sv=ds, chanABEq=chanABEq_mask)
98
+ # If interval parameters are provided
99
+ elif (
100
+ interval_start_operator is not None
101
+ and interval_start_value is not None
102
+ and interval_end_operator is not None
103
+ and interval_end_value is not None
104
+ ):
105
+ chanABEq_low_mask = (
106
+ f'"{chanA}" - "{chanB}" {interval_start_operator} {interval_start_value}dB'
107
+ )
108
+ chanABEq_high_mask = f'"{chanA}" - "{chanB}" {interval_end_operator} {interval_end_value}dB'
109
+ low_mask = ep.mask.frequency_differencing(source_Sv=ds, chanABEq=chanABEq_low_mask)
110
+ high_mask = ep.mask.frequency_differencing(source_Sv=ds, chanABEq=chanABEq_high_mask)
111
+ mask = low_mask & high_mask
112
+ else:
113
+ raise ValueError("Invalid combination of parameters provided.")
114
+ return mask
115
+
116
+
117
+ def attach_freq_diff_mask_to_ds(Sv: xr.DataArray, mask: xr.DataArray) -> xr.DataArray:
118
+ """
119
+ Attach a frequency differencing mask to the given Sv DataArray.
120
+
121
+ Parameters:
122
+ - Sv (xr.DataArray): The DataArray containing the Sv data.
123
+ - mask (xr.DataArray): The mask to be attached.
124
+
125
+ Returns:
126
+ - xr.DataArray: A DataArray with the attached mask.
127
+ """
128
+ return attach_mask_to_dataset(Sv, mask)
129
+
130
+
131
+ def identify_gas_bearing_organisms(ds: xr.Dataset, chan38: str, chan120: str) -> xr.Dataset:
132
+ """
133
+ Identify gas-bearing organisms using frequency differencing.
134
+ Parameters:
135
+ - ds (xr.Dataset): The dataset containing the Sv data to create a mask for.
136
+ - chan38 (str): Channel name for 38 kHz.
137
+ - chan120 (str): Channel name for 120 kHz.
138
+ Returns:
139
+ - xr.Dataset: A DataArray with the mask for gas-bearing organisms identification attached.
140
+ Notes:
141
+ - Gas-bearing organisms are identified by an acoustic signature where the difference in volume
142
+ backscattering strength between 120 kHz and 38 kHz is less than -1 dB.
143
+ """
144
+ gas_bearing_mask = find_mask_freq_diff(
145
+ ds=ds,
146
+ chanA=chan38,
147
+ chanB=chan120,
148
+ single_operator=">",
149
+ single_value="1",
150
+ )
151
+ gas_bearing_mask = add_metadata_to_mask(
152
+ mask=gas_bearing_mask, metadata={"mask_type": "gas_bearing_organisms"}
153
+ )
154
+
155
+ return attach_freq_diff_mask_to_ds(ds, gas_bearing_mask)
156
+
157
+
158
+ def identify_fluid_like_organisms(ds: xr.Dataset, chan38: str, chan120: str) -> xr.Dataset:
159
+ """
160
+ Identify fluid-like organisms using frequency differencing.
161
+ Parameters:
162
+ - ds (xr.Dataset): The dataset containing the Sv data to create a mask for.
163
+ - chan38 (str): Channel name for 38 kHz.
164
+ - chan120 (str): Channel name for 120 kHz.
165
+ Returns:
166
+ - xr.Dataset: A DataArray with the mask for fluid-like organisms identification attached.
167
+ Notes:
168
+ Fluid-like organisms are identified by an acoustic signature where the difference in volume
169
+ backscattering strength between 120 kHz and 38 kHz is greater than 2 dB.
170
+ """
171
+ fluid_like_mask = find_mask_freq_diff(
172
+ ds=ds,
173
+ chanA=chan120,
174
+ chanB=chan38,
175
+ single_operator=">",
176
+ single_value="2.0",
177
+ )
178
+ fluid_like_mask = add_metadata_to_mask(
179
+ mask=fluid_like_mask, metadata={"mask_type": "fluid_like_organisms"}
180
+ )
181
+
182
+ return attach_freq_diff_mask_to_ds(ds, fluid_like_mask)
183
+
184
+
185
+ def identify_krill(ds: xr.Dataset, chan38: str, chan120: str) -> xr.Dataset:
186
+ """
187
+ Identify krill using frequency differencing intervals.
188
+ Parameters:
189
+ - ds (xr.Dataset): The dataset containing the Sv data to create a mask for.
190
+ - chan38 (str): Channel name for 38 kHz.
191
+ - chan120 (str): Channel name for 120 kHz.
192
+ Returns:
193
+ - xr.Dataset: A DataArray with mask for krill identification attached.
194
+ Notes:
195
+ The most prevalent frequency differencing interval for krill identification is given by:
196
+ the difference in volume backscattering strength between 120 kHz and 38 kHz
197
+ typically ranging from 2 dB to 16 dB.
198
+ """
199
+ krill_mask = find_mask_freq_diff(
200
+ ds=ds,
201
+ chanA=chan120,
202
+ chanB=chan38,
203
+ interval_start_operator=">=",
204
+ interval_start_value="2.0",
205
+ interval_end_operator="<=",
206
+ interval_end_value="16.0",
207
+ )
208
+ krill_mask = add_metadata_to_mask(mask=krill_mask, metadata={"mask_type": "krill"})
209
+
210
+ return attach_freq_diff_mask_to_ds(ds, krill_mask)
@@ -0,0 +1,23 @@
1
+ import os
2
+ from .csv import full_nasc_data, write_nasc_to_csv
3
+
4
+
5
+ def compute_and_write_nasc(shoal_dataset, config, profiling_info=None):
6
+ if not config["nasc"]["enabled"]:
7
+ return None
8
+
9
+ start_time = None
10
+ start_cpu = None
11
+ start_memory = None
12
+
13
+ if config["profile"]:
14
+ start_time, start_cpu, start_memory = start_profiling()
15
+
16
+ nasc = full_nasc_data(shoal_dataset)
17
+
18
+ if config["profile"]:
19
+ profiling_info["nasc"] = end_profiling(start_time, start_cpu, start_memory)
20
+
21
+ write_nasc_to_csv(
22
+ nasc, os.path.join(config["output_folder"], config["raw_path"].stem + "_NASC.csv")
23
+ )
@@ -0,0 +1,62 @@
1
+ from typing import Dict, Union
2
+
3
+ import dask.array as da
4
+ import echopype as ep
5
+ import numpy as np
6
+ import xarray as xr
7
+
8
+
9
+ def compute_per_dataset_nasc(Sv_ds: xr.Dataset) -> Dict[str, Union[xr.Dataset, str]]:
10
+ """
11
+ Compute NASC (Nautical Area Scattering Coefficient) for an entire Sv dataset using echopype.
12
+
13
+ This function determines the maximum depth and distance from the given Sv dataset
14
+ and computes NASC using these as bin sizes for echopype's `compute_NASC` function.
15
+ The binning process will produce one bin per channel in the dataset.
16
+
17
+ Parameters:
18
+
19
+ Sv_ds : xr.Dataset
20
+ A cleaned dataset containing Sv data that has been preprocessed to remove noise.
21
+ The dataset should have `latitude`, `longitude`, and `depth` data variables.
22
+
23
+ Returns:
24
+
25
+ Dict[str, Union[xr.Dataset, str]]
26
+ A dictionary containing:
27
+ - "NASC_dataset": the computed NASC values as an xarray dataset
28
+ - "maximum_depth": a string indicating the maximum depth used for binning
29
+ - "maximum_distance": a string indicating the maximum distance used for binning
30
+
31
+ Notes:
32
+
33
+ Ensure that the Sv dataset is free of noise before using this function.
34
+ The computation relies on the `compute_NASC` function from the `echopype` library,
35
+ which is based on the Echoview algorithm PRC_NASC.
36
+
37
+ See Also:
38
+
39
+ echopype.commongrid.api.compute_NASC: The echopype function used for the underlying NASC computation.
40
+ """
41
+
42
+ # Get the maximum distance from the Sv dataset
43
+ dist = ep.commongrid.utils.get_distance_from_latlon(Sv_ds)
44
+ max_dist = np.nanmax(dist)
45
+ # max_dist = dist.max()
46
+ max_dist_str = str(max_dist) + "nmi"
47
+
48
+ # Get the maximum depth from the Sv dataset
49
+ max_depth = np.nanmax(Sv_ds["depth"].values)
50
+ # max_depth = Sv_ds.depth.values.max()
51
+ max_depth_str = str(max_depth) + "m"
52
+
53
+ # Compute NASC using the determined max depth and max distance - one bin per channel
54
+ nasc_ep = ep.commongrid.api.compute_NASC(Sv_ds, range_bin=max_depth_str, dist_bin=max_dist_str)
55
+ if isinstance(nasc_ep["NASC"], da.Array):
56
+ nasc_ep["NASC"] = nasc_ep["NASC"].compute()
57
+
58
+ return {
59
+ "NASC_dataset": nasc_ep,
60
+ "maximum_depth": max_depth_str,
61
+ "maximum_distance": max_dist_str,
62
+ }
@@ -0,0 +1,109 @@
1
+ """
2
+ shoal_detection_handler.py
3
+ --------------------------
4
+ This module provides functionalities for shoal detection in echosounder data.
5
+
6
+ Functions:
7
+
8
+ - `create_shoal_mask_multichannel(Sv, parameters, method)`:
9
+ Generates two multichannel masks (`mask` and `mask_`) used for shoal detection based on the given Sv dataset.
10
+ - `combine_shoal_masks_multichannel(mask, mask_)`:
11
+ Combines the multichannel masks (`mask` and `mask_`) to produce a final mask.
12
+ The resulting mask contains `True` values only where both input masks are `True` for each channel.
13
+ - `attach_shoal_mask_to_ds(ds, parameters, method)`:
14
+ Attaches a shoal mask to the given dataset.
15
+
16
+ Usage:
17
+
18
+ To create the two necessary multichannel shoal masks for a given Sv dataset, ds:
19
+ >>> create_shoal_mask_multichannel(Sv, parameters, method)
20
+ To combine two multichannel masks, `mask` and `mask_`:
21
+ >>> combine_shoal_masks_multichannel(mask, mask_)
22
+ To attach a shoal mask to the given dataset, ds.:
23
+ >>> attach_shoal_mask_to_ds(ds, parameters, method)
24
+
25
+ Notes:
26
+
27
+ - Ensure the echopype library is properly installed and imported when using this module.
28
+ - Sv represents the volume backscattering strength.
29
+ """
30
+
31
+
32
+ from typing import Tuple
33
+
34
+ import xarray as xr
35
+ from echopype.mask.api import get_shoal_mask_multichannel
36
+ from oceanstream.utils import add_metadata_to_mask, attach_mask_to_dataset
37
+
38
+ WEILL_DEFAULT_PARAMETERS = {
39
+ "thr": -70,
40
+ "maxvgap": 5,
41
+ "maxhgap": 5,
42
+ "minvlen": 5,
43
+ "minhlen": 5,
44
+ "dask_chunking": {"ping_time": 1000, "range_sample": 1000},
45
+ }
46
+
47
+
48
+ def create_shoal_mask_multichannel(
49
+ Sv: xr.Dataset,
50
+ parameters: dict = WEILL_DEFAULT_PARAMETERS,
51
+ method: str = "will",
52
+ ) -> Tuple[xr.DataArray, xr.DataArray]:
53
+ """
54
+ Invokes echopype's `get_shoal_mask_multichannel` to create two multichannel masks used for shoal detection.
55
+
56
+ Parameters:
57
+
58
+ Sv : xr.Dataset
59
+ The dataset for which the shoal masks will be created. This dataset should have the
60
+ coordinate `channel` and variables `frequency_nominal` and `Sv`.
61
+ parameters: dict
62
+ Method parameters
63
+ method: str
64
+ Specifying the algorithm to use
65
+
66
+ Returns:
67
+
68
+ Tuple[xr.DataArray, xr.DataArray]
69
+ A tuple containing two DataArrays:
70
+ 1. A multichannel mask (`mask`) for the Sv data. Regions that meet the thresholding criteria
71
+ for shoal identification are marked as True.
72
+ 2. A mask (`mask_`) indicating the valid samples for the `mask`. Edge regions are filled
73
+ with 'False', whereas the portion in which shoals could be detected is 'True'.
74
+
75
+ Example:
76
+
77
+ >>> mask = create_shoal_mask_multichannel(Sv, parameters, method)
78
+ """
79
+ mask = get_shoal_mask_multichannel(Sv, parameters, method)
80
+ mask.attrs["shoal detection mask type"] = method
81
+ return mask
82
+
83
+
84
+ def attach_shoal_mask_to_ds(
85
+ ds: xr.Dataset, parameters: dict = WEILL_DEFAULT_PARAMETERS, method: str = "will"
86
+ ) -> xr.Dataset:
87
+ """
88
+ Attaches a shoal mask to the given dataset.
89
+
90
+ This function first creates two multichannel masks used for shoal detection
91
+ using the `create_shoal_mask_multichannel` function.
92
+ It then combines the masks using the `combine_shoal_masks_multichannel` function.
93
+ Metadata indicating the mask type is added to the combined mask before attaching it to the dataset.
94
+
95
+ Parameters:
96
+ - ds (xr.Dataset):
97
+ The dataset to which the shoal mask will be attached.
98
+ - parameters (dist) and method (str):
99
+ Arguments passed to the `create_shoal_mask_multichannel` function.
100
+
101
+ Returns:
102
+ - xr.Dataset: The dataset with the shoal mask attached.
103
+
104
+ Example:
105
+ >>> ds_with_shoal_mask = attach_shoal_mask_to_ds(ds, parameters, method)
106
+ """
107
+ shoal_mask = create_shoal_mask_multichannel(ds, parameters, method)
108
+ shoal_mask = add_metadata_to_mask(mask=shoal_mask, metadata={"mask_type": "shoal"})
109
+ return attach_mask_to_dataset(ds, shoal_mask)