API reference¶
API components that most users will interact with.
Attention
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 being deprecated.
Content
- EchoData class
- Open raw and converted files
- Combine EchoData objects
- Data processing subpackages
- Utilities
EchoData class¶
EchoData is an object that handles interfacing raw converted data. It is used for calibration and other processing.
Open raw and converted files¶
-
echopype.
open_raw
(raw_file: Optional[PathHint] = None, sonar_model: Optional[SonarModelsHint] = None, xml_path: Optional[PathHint] = None, convert_params: Optional[Dict[str, str]] = None, storage_options: Optional[Dict[str, str]] = None) → Optional[echopype.echodata.echodata.EchoData]¶ Create 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.
Parameters: - raw_file : str
path to raw data file
- sonar_model : str
model of the sonar instrument
- xml_path : str
path to XML config file used by AZFP
- convert_params : dict
parameters (metadata) that may not exist in the raw file and need to be added to the converted file
- storage_options : dict
options for cloud storage
Returns: - EchoData object
-
echopype.
open_converted
(converted_raw_path: PathHint, storage_options: Dict[str, str] = None)¶ Create an EchoData object from a single converted netcdf or zarr file.
Parameters: - converted_raw_path : str
path to converted data file
- storage_options : dict
options for cloud storage
Returns: - EchoData object
Combine EchoData objects¶
-
echopype.
combine_echodata
(echodatas: List[echopype.echodata.echodata.EchoData], combine_attrs='override') → echopype.echodata.echodata.EchoData¶ Combines multiple EchoData objects into a single EchoData object.
Parameters: - echodatas: List[EchoData]
The list of EchoData objects to be combined.
- combine_attrs: { “override”, “drop”, “identical”, “no_conflicts”, “overwrite_conflicts” }
String indicating how to combine attrs of the EchoData objects being merged. This parameter matches the identically named xarray parameter (see https://xarray.pydata.org/en/latest/generated/xarray.combine_nested.html) with the exception of the “overwrite_conflicts” value.
- “override”: Default. skip comparing and copy attrs from the first EchoData object to the result.
- “drop”: empty attrs on returned EchoData object.
- “identical”: all attrs must be the same on every object.
- “no_conflicts”: attrs from all objects are combined, any that have the same name must also have the same value.
- “overwrite_conflicts”: attrs from all EchoData objects are combined, attrs with conflicting keys will be overwritten by later EchoData objects.
Returns: - EchoData
An EchoData object with all of the data from the input EchoData objects combined.
Raises: - ValueError
If echodatas contains EchoData objects with different or None sonar_model values (i.e., all EchoData objects must have the same non-None sonar_model value).
- ValueError
If EchoData objects have conflicting source file names.
Warns: - UserWarning
If the sonar_model of the input EchoData objects is “EK60” and any EchoData objects have non-monotonically increasing ping_time, location_time or mru_time values, the corresponding values in the output EchoData object will be increased starting at the timestamp where the reversal occurs such that all values in the output are monotonically increasing. Additionally, the original ping_time, location_time or mru_time values will be stored in the Provenance group, although this behavior may change in future versions.
Warning
Changes in parameters between EchoData objects are not currently checked; however, they may raise an error in future versions.
Notes
- EchoData objects are combined by combining their groups individually.
- Attributes from all groups before the combination will be stored in the provenance group, although this behavior may change in future versions.
- The source_file and converted_raw_path attributes will be copied from the first EchoData object in the given list, but this may change in future versions.
Examples
>>> ed1 = echopype.open_converted("file1.nc") >>> ed2 = echopype.open_converted("file2.zarr") >>> combined = echopype.combine_echodata([ed1, ed2])
Data processing subpackages¶
calibrate¶
Functions¶
compute_Sv (echodata, **kwargs) |
Compute volume backscattering strength (Sv) from raw data. |
compute_Sp (echodata, **kwargs) |
Compute point backscattering strength (Sp) from raw data. |
preprocess¶
Functions¶
compute_MVBS (ds_Sv[, range_meter_bin, …]) |
Compute Mean Volume Backscattering Strength (MVBS) based on intervals of range and ping_time specified in physical units. |
compute_MVBS_index_binning (ds_Sv[, …]) |
Compute Mean Volume Backscattering Strength (MVBS) based on intervals of range_bin and ping number specified in index number. |
remove_noise (ds_Sv, ping_num, range_bin_num) |
Remove noise by using estimates of background noise from mean calibrated power of a collection of pings. |
qc¶
Functions¶
coerce_increasing_time (ds[, time_name, …]) |
Coerce a time coordinate to always flow forward. |
exist_reversed_time (ds, time_name) |
Test for occurrence of time reversal in specified datetime coordinate variable. |
Utilities¶
Utilities for calculating seawater acoustic properties.
Functions¶
calc_absorption (frequency[, distance, …]) |
Calculate sea absorption in dB/m |
calc_sound_speed ([temperature, salinity, …]) |
Calculate sound speed in meters per second. |