EchoData
EchoData#
- class echopype.echodata.EchoData(converted_raw_path: Optional[PathHint] = None, storage_options: Optional[Dict[str, Any]] = None, source_file: Optional[PathHint] = None, xml_path: Optional[PathHint] = None, sonar_model: Optional[SonarModelsHint] = None, open_kwargs: Optional[Dict[str, Any]] = None)#
Bases:
object
Echo data model class for handling raw converted data, including multiple files associated with the same data set.
- Attributes
- group_paths
- nc_path
- version_info
- zarr_path
Methods
compute_range
([env_params, azfp_cal_type, ...])Computes the range (
echo_range
) of the data contained in thisEchoData
object, in meters.to_netcdf
([save_path])Save content of EchoData to netCDF.
to_zarr
([save_path])Save content of EchoData to zarr.
update_platform
(extra_platform_data[, ...])Updates the EchoData.platform group with additional external platform data.
from_file
Attributes Summary
Methods Summary
compute_range
([env_params, azfp_cal_type, ...])Computes the range (
echo_range
) of the data contained in thisEchoData
object, in meters.from_file
(converted_raw_path[, ...])to_netcdf
([save_path])Save content of EchoData to netCDF.
to_zarr
([save_path])Save content of EchoData to zarr.
update_platform
(extra_platform_data[, ...])Updates the EchoData.platform group with additional external platform data.
Attributes Documentation
- group_map: Dict[str, Any] = {'beam': {'description': 'contains backscatter data (either complex samples or uncalibrated power samples) and other beam or channel-specific data, including split-beam angle data when they exist.', 'ep_group': 'Sonar/Beam_group1', 'name': 'Beam_group1'}, 'beam_group3': {'description': '', 'ep_group': 'Sonar/Beam_group3', 'name': 'Beam_group3'}, 'beam_group4': {'description': '', 'ep_group': 'Sonar/Beam_group4', 'name': 'Beam_group4'}, 'beam_power': {'description': 'contains backscatter power (uncalibrated) and other beam or channel-specific data, including split-beam angle data when they exist. Only exists if complex backscatter data are already in Sonar/Beam_group1', 'ep_group': 'Sonar/Beam_group2', 'name': 'Beam_group2'}, 'environment': {'description': 'contains information relevant to acoustic propagation through water.', 'ep_group': 'Environment', 'name': 'Environment'}, 'nmea': {'description': 'contains information specific to the NMEA protocol.', 'ep_group': 'Platform/NMEA', 'name': 'NMEA'}, 'platform': {'description': 'contains information about the platform on which the sonar is installed.', 'ep_group': 'Platform', 'name': 'Platform'}, 'provenance': {'description': 'contains metadata about how the SONAR-netCDF4 version of the data were obtained.', 'ep_group': 'Provenance', 'name': 'Provenance'}, 'sonar': {'description': 'contains sonar system metadata and sonar beam groups.', 'ep_group': 'Sonar', 'name': 'Sonar'}, 'top': {'description': 'contains metadata about the SONAR-netCDF4 file format.', 'ep_group': None, 'name': 'Top-level'}, 'vendor': {'description': 'contains vendor-specific information about the sonar and the data.', 'ep_group': 'Vendor_specific', 'name': 'Vendor_specific'}}#
- group_paths#
- nc_path#
- version_info#
- zarr_path#
Methods Documentation
- compute_range(env_params=None, azfp_cal_type=None, ek_waveform_mode=None, ek_encode_mode='complex')#
Computes the range (
echo_range
) of the data contained in thisEchoData
object, in meters.Currently this operation is supported for the following
sonar_model
: EK60, AZFP, EK80 (see Notes below for detail).- Parameters
- env_paramsdict
Environmental parameters needed for computing range (
echo_range
). Users can supply “sound speed” directly, or specify other variables that can be used to compute them, including “temperature”, “salinity”, and “pressure”.For EK60 and EK80 echosounders, by default echopype uses environmental variables stored in the data files. For AZFP echosounder, all environmental parameters need to be supplied. AZFP echosounders typically are equipped with an internal temperature sensor, and some are equipped with a pressure sensor, but automatically using these pressure data is not currently supported.
- azfp_cal_type{“Sv”, “TS”}, optional
“Sv” for calculating volume backscattering strength
“TS” for calculating target strength.
This parameter needs to be specified for data from the AZFP echosounder, due to a difference in computing range (
echo_range
) for Sv and TS.- ek_waveform_mode{“CW”, “BB”}, optional
Type of transmit waveform. Required only for data from the EK80 echosounder.
“CW” for narrowband transmission, returned echoes recorded either as complex or power/angle samples
“BB” for broadband transmission, returned echoes recorded as complex samples
- ek_encode_mode{“complex”, “power”}, optional
Type of encoded return echo data. Required only for data from the EK80 echosounder.
“complex” for complex samples
“power” for power/angle samples, only allowed when the echosounder is configured for narrowband transmission
- Returns
- xr.DataArray
The range (
echo_range
) of the data in meters.
- Raises
- ValueError
When sonar_model is “AZFP” but azfp_cal_type is not specified or is None.
When sonar_model is “EK80” but ek_waveform_mode is not specified or is None.
When sonar_model is “EK60” but waveform_mode is “BB”
When sonar_model is “AZFP” and env_params does not contain either “sound_speed” or all of “temperature”, “salinity”, and “pressure”.
When sonar_model is “EK60” or “EK80”, EchoData.environment.sound_speed_indicative does not exist, and env_params does not contain either “sound_speed” or all of “temperature”, “salinity”, and “pressure”.
When sonar_model is not “AZFP”, “EK60”, or “EK80”.
Notes
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.For AZFP echosounder, the returned
echo_range
is duplicated alongping_time
to conform with outputs from other echosounders, even though within each data file the range is held constant.
- classmethod from_file(converted_raw_path: str, storage_options: Optional[Dict[str, Any]] = None, open_kwargs: Dict[str, Any] = {}) echopype.echodata.echodata.EchoData #
- to_netcdf(save_path: Optional[PathHint] = None, **kwargs)#
Save content of EchoData to netCDF.
- Parameters
- save_pathstr
path that converted .nc file will be saved
- compressbool
whether or not to perform compression on data variables Defaults to
True
- overwritebool
whether or not to overwrite existing files Defaults to
False
- parallelbool
whether or not to use parallel processing. (Not yet implemented)
- output_storage_optionsdict
Additional keywords to pass to the filesystem class.
- to_zarr(save_path: Optional[PathHint] = None, **kwargs)#
Save content of EchoData to zarr.
- Parameters
- save_pathstr
path that converted .nc file will be saved
- compressbool
whether or not to perform compression on data variables Defaults to
True
- overwritebool
whether or not to overwrite existing files Defaults to
False
- parallelbool
whether or not to use parallel processing. (Not yet implemented)
- output_storage_optionsdict
Additional keywords to pass to the filesystem class.
- update_platform(extra_platform_data: xarray.core.dataset.Dataset, time_dim='time', extra_platform_data_file_name=None)#
Updates the EchoData.platform group with additional external platform data.
extra_platform_data must be an xarray Dataset. The name of the time dimension in extra_platform_data is specified by the time_dim parameter. Data is extracted from extra_platform_data by variable name; only the data in extra_platform_data with the following variable names will be used:
“pitch”
“roll”
“vertical_offset”
“latitude”
“longitude”
“water_level”
The data inserted into the Platform group will be indexed by a dimension named “time1”.
- Parameters
- extra_platform_dataxr.Dataset
An xr.Dataset containing the additional platform data to be added to the EchoData.platform group.
- time_dim: str, default=”time”
The name of the time dimension in extra_platform_data; used for extracting data from extra_platform_data.
- extra_platform_data_file_name: str, default=None
File name for source of extra platform data, if read from a file
Examples
>>> ed = echopype.open_raw(raw_file, "EK60") >>> extra_platform_data = xr.open_dataset(extra_platform_data_file) >>> ed.update_platform(extra_platform_data, >>> extra_platform_data_file_name=extra_platform_data_file)