API components that most users will interact with.
In echopype versions prior to 0.5.0, the API in this page focused
on the convert
and process
subpackages. See the
0.4.1 API page
if you’re using a previous release. That workflow is now removed.
Content
EchoData is an object that handles interfacing raw converted data. It is used for calibration and other processing.
| Echo data model class for handling raw converted data, including multiple files associated with the same data set. |
open_raw
(raw_file: PathHint, sonar_model: SonarModelsHint, xml_path: OptionalCreate an EchoData object containing parsed data from a single raw data file.
The EchoData object can be used for adding metadata and ancillary data as well as to serialize the parsed data to zarr or netcdf.
path to raw data file
model of the sonar instrument
EK60
: Kongsberg Simrad EK60 echosounder
ES70
: Kongsberg Simrad ES70 echosounder
EK80
: Kongsberg Simrad EK80 echosounder
EA640
: Kongsberg EA640 echosounder
AZFP
: ASL Environmental Sciences AZFP echosounder
AD2CP
: Nortek Signature series ADCP
(tested with Signature 500 and Signature 1000)
path to XML config file used by AZFP
parameters (metadata) that may not exist in the raw file and need to be added to the converted file
options for cloud storage
Flag to use disk swap in case of a large memory footprint.
When set to True
(or when set to “auto” and large memory footprint is needed,
this function will create a temporary zarr store at the operating system’s
temporary directory.
The maximum data chunk size in Megabytes (MB), when offloading variables with a large memory footprint to a temporary zarr store
If sonar_model
is None
or sonar_model
given is unsupported.
If raw_file
is None
.
If raw_file
input is neither str
or
pathlib.Path
type.
In case of a large memory footprint, the program will determine if using a temporary swap space is needed. If so, it will use that space during conversion to prevent out of memory errors.
Users can override this behaviour by either passing
use_swap=True
or use_swap=False
. If a keyword “auto” is
used for the use_swap
parameter, echopype will determine the usage of
swap space automatically.
This feature is only available for the following echosounders: EK60, ES70, EK80, ES80, EA640.
echopype.open_converted
(converted_raw_path: PathHint, storage_options: DictCreate an EchoData object from a single converted netcdf or zarr file.
path to converted data file
options for cloud storage
optional keyword arguments to be passed into xr.open_dataset
combine_echodata
(echodata_list: ListCombines multiple EchoData
objects into a single EchoData
object.
The list of EchoData
objects to be combined
Specifies what channels should be selected for an EchoData
group
with a channel
dimension (before combination).
if a list is provided, then each EchoData
group with a channel
dimension
will only contain the channels in the provided list
- if a dictionary is provided, the dictionary should have keys specifying only beam
groups (e.g. “Sonar/Beam_group1”) and values as a list of channel names to select
within that beam group. The rest of the EchoData
groups with a channel
dimension
will have their selected channels chosen automatically.
A lazy loaded EchoData
object,
with all data from the input EchoData
objects combined.
If the provided zarr path does not point to a zarr file
If a list of EchoData
objects are not provided
If any EchoData
object’s sonar_model
is None
If any EchoData
object does not have a file path
If the provided EchoData
objects have the same filenames
If the first time value of each EchoData
group is not less
than the first time value of the subsequent corresponding
EchoData
group, with respect to the order in echodata_list
If the same EchoData
groups in echodata_list
do not
have the same number of channels and the same name for each
of these channels.
If any of the following attribute checks are not met
amongst the combined EchoData
groups:
the keys are not the same
the values are not identical
the keys date_created
or conversion_time
do not have the same types
If any EchoData
group has a channel
dimension value
with a duplicate value.
If channel_selection=None
and the channel
dimensions are not the
same across the same group under each object in echodata_list
.
If channel_selection
is a list and the listed channels are not contained
in the EchoData
group across all objects in echodata_list
.
EchoData
objects are combined by appending their groups individually.
All attributes (besides attributes whose values are arrays) from all groups before the
combination will be stored in the Provenance
group.
Combine lazy loaded EchoData
objects:
>>> ed1 = echopype.open_converted("file1.zarr")
>>> ed2 = echopype.open_converted("file2.zarr")
>>> combined = echopype.combine_echodata(echodata_list=[ed1, ed2])
Combine in-memory EchoData
objects:
>>> ed1 = echopype.open_raw(raw_file="EK60_file1.raw", sonar_model="EK60")
>>> ed2 = echopype.open_raw(raw_file="EK60_file2.raw", sonar_model="EK60")
>>> combined = echopype.combine_echodata(echodata_list=[ed1, ed2])
| Compute volume backscattering strength (Sv) from raw data. |
| Compute target strength (TS) from raw data. |
| Estimate background noise by computing mean calibrated power of a collection of pings. |
| Remove noise by using estimates of background noise from mean calibrated power of a collection of pings. |
| Compute Mean Volume Backscattering Strength (MVBS) based on intervals of range ( |
| Compute Nautical Areal Scattering Coefficient (NASC) from an Sv dataset. |
| Compute Mean Volume Backscattering Strength (MVBS) based on intervals of |
Use frequency_nominal in place of channel to be dataset dimension and coorindate. | |
| Create a depth data variable based on data in Sv dataset. |
| Add geographical location (latitude/longitude) to the Sv dataset. |
| Add split-beam (alongship/athwartship) angles into the Sv dataset. |
| Coerce a time coordinate so that it always flows forward. |
| Test for occurrence of time reversal in specified datetime coordinate variable. |
| Create a mask based on the differences of Sv values using a pair of frequencies. |
| Applies the provided mask(s) to the Sv variable |
Functions to compute summary statistics from echo data.
| Calculates the area-backscattering strength (Sa) [unit: dB re 1 m^2 m^-2]. |
| Calculated the index of aggregation (IA) [unit: m^-1]. |
| Calculates the mean backscatter location [unit: m]. |
| Calculates the inertia (I) [unit: m^-2]. |
| Calculates the equivalent area (EA) [unit: m]. |
Utilities for calculating seawater acoustic properties.
| Calculate sea water absorption in units [dB/m]. |
| Calculate sound speed in [m/s]. |
Visualization module to quickly plot raw, Sv, and MVBS dataset.
NOTE: To use this subpackage. `Matplotlib` and `cmocean` package must be installed.
echopype.visualize.create_echogram
(data: UnionCreate an Echogram from an EchoData object or Sv and MVBS Dataset.
Echodata or Xarray Dataset to be plotted
The channel to be plotted. Otherwise all channels will be plotted.
The frequency to be plotted. If not specified, all frequency will be plotted.
Flag as to whether range (echo_range
) should be computed or not,
by default it will just plot range_sample` as the yaxis.
Note that for data that is “Sv” xarray dataset, get_range defaults to True.
Keyword arguments dictionary for computing range (echo_range
).
Keys are env_params, waveform_mode, and encode_mode.
Water level data array for platform water level correction. Note that auto addition of water level can be performed when data is an EchoData object by setting this argument to True. Currently because the water level information is not available as part of the Sv dataset, a warning is issued when vertical_offset=True in this case and no correction is performed. This behavior will change in the future when the default content of Sv dataset is updated to include this information.
Additional keyword arguments for xarray plot pcolormesh.
The EK80 echosounder can be configured to transmit
either broadband (waveform_mode="BB"
)
or narrowband (waveform_mode="CW"
) signals.
When transmitting in broadband mode, the returned echoes are
encoded as complex samples (encode_mode="complex"
).
When transmitting in narrowband mode, the returned echoes can be encoded
either as complex samples (encode_mode="complex"
)
or as power/angle combinations (encode_mode="power"
) in a format
similar to those recorded by EK60 echosounders.