Regions2D

class echoregions.regions2d.Regions2D(input_file: str, min_depth: Optional[Union[int, float]] = None, max_depth: Optional[Union[int, float]] = None)

Bases: object

Class that contains and performs operations with Regions2D data from Echoview EVR files.

Methods

close_region([region])	Close a region by appending the first point to end of the list of points.
mask(da_Sv, region_ids[, mask_var, mask_labels])	Mask data from Data Array containing Sv data based off of a Regions2D object and its regions ids.
plot([region, close_region])	Plot a region from data.
replace_nan_depth([inplace])	Replace 9999.99 or -9999.99 depth values with user-specified min_depth and max_depth
select_region([region_id, time_range, ...])	Selects a subset of this Region2D object's dataframe.
select_sonar_file(sonar_file_names[, region])	Finds SIMRAD sonar files in the time domain that encompasses region or list of regions.
to_csv([save_path])	Save a Dataframe to a .csv file
to_json([save_path])	Convert EVR to a JSON file.
transect_mask(da_Sv[, transect_dict, ...])	Mask data from Data Array containing Sv data based off of a Regions2D object and its transect_values.

Methods Summary

close_region([region])	Close a region by appending the first point to end of the list of points.
mask(da_Sv, region_ids[, mask_var, mask_labels])	Mask data from Data Array containing Sv data based off of a Regions2D object and its regions ids.
plot([region, close_region])	Plot a region from data.
replace_nan_depth([inplace])	Replace 9999.99 or -9999.99 depth values with user-specified min_depth and max_depth
select_region([region_id, time_range, ...])	Selects a subset of this Region2D object's dataframe.
select_sonar_file(sonar_file_names[, region])	Finds SIMRAD sonar files in the time domain that encompasses region or list of regions.
to_csv([save_path])	Save a Dataframe to a .csv file
to_json([save_path])	Convert EVR to a JSON file.
transect_mask(da_Sv[, transect_dict, ...])	Mask data from Data Array containing Sv data based off of a Regions2D object and its transect_values.

Methods Documentation

close_region(region: Optional[Union[float, str, List, pandas.core.series.Series, pandas.core.frame.DataFrame]] = None) → pandas.core.frame.DataFrame

Close a region by appending the first point to end of the list of points.

Parameters

regionfloat, str, list, Series, DataFrame, None

region(s) to select raw files with If None, select all regions. Defaults to None

Returns

DataFrame

Returns a new DataFrame with closed regions

mask(da_Sv: xarray.core.dataarray.DataArray, region_ids: List, mask_var: Optional[str] = None, mask_labels=None) → xarray.core.dataarray.DataArray

Mask data from Data Array containing Sv data based off of a Regions2D object and its regions ids.

Parameters

da_SvData Array

DataArray of shape (ping_time, depth) containing Sv data.

region_idslist

list IDs of regions to create mask for

mask_varstr

If provided, used to name the output mask array, otherwise mask

mask_labels:

None: assigns labels automatically 0,1,2,… “from_ids”: uses the region ids list: uses a list of integers as labels

Returns

A DataArray with the data_var masked by the specified region.

plot(region: Optional[Union[str, List, pandas.core.frame.DataFrame]] = None, close_region: bool = False, **kwargs) → None

Plot a region from data. Automatically convert time and range_edges.

regionfloat, str, list, Series, DataFrame, None

Region(s) to select raw files with If None, select all regions. Defaults to None

close_regionbool

Plot the region as a closed polygon. Defaults to False

kwargskeyword arguments

Additional arguments passed to matplotlib plot

replace_nan_depth(inplace: bool = False) → pandas.core.frame.DataFrame

Replace 9999.99 or -9999.99 depth values with user-specified min_depth and max_depth

Parameters

inplacebool

Modify the current data inplace

Returns

DataFrame with depth edges replaced by Regions2D.min_depth and Regions2D.max_depth

select_region(region_id: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None, time_range: Optional[List[pandas._libs.tslibs.timestamps.Timestamp]] = None, depth_range: Optional[List[Union[float, int]]] = None, copy=True) → pandas.core.frame.DataFrame

Selects a subset of this Region2D object’s dataframe.

Parameters

region_idfloat, int, str, list, None

A region id provided as a number, a string, or list of these.

time_range: List of 2 Pandas Timestamps.

Datetime range for expected output of subselected DataFrame. 1st index value must be later than 0th index value.

depth_range: List of 2 floats.

Depth range for expected output of subselected DataFrame. 1st index value must be larger than 0th index value.

copybool

Return a copy of the data DataFrame

Returns

DataFrame

There is a row for each region id provided by the region_id parameter, and each row has time and depth within or on the boundaries passed in by the time_range and depth_range values.

select_sonar_file(sonar_file_names: List[str], region: Optional[Union[float, str, list, pandas.core.series.Series, pandas.core.frame.DataFrame]] = None) → List

Finds SIMRAD sonar files in the time domain that encompasses region or list of regions.

SIMRAD Format Explained with the example Summer2017-D20170625-T205018.nc:

The letter “D” is a prefix indicating the date in the format following it. In this case, “20170625” represents the date June 25, 2017. The letter “T” is a prefix indicating the time in the format following it. In this case, “205018” represents the time 20:50:18 (8:50:18 PM) in 24-hour format. The .nc is a file extension that denotes a NetCDF (Network Common Data Form) file.

Parameters

fileslist

Raw filenames in SIMRAD format.

regionfloat, str, list, Series, DataFrame, None

Region(s) to select sonar files with. If None, select all regions. Defaults to None

Returns

files: list

list of raw file(s) spanning the encompassing region or list of regions.

to_csv(save_path: Optional[bool] = None) → None

Save a Dataframe to a .csv file

Parameters

save_pathstr

path to save the CSV file to

to_json(save_path: Optional[str] = None) → None

Convert EVR to a JSON file. Currently Deprecated.

Parameters

save_pathstr

Path to save csv file to

prettybool, default False

Output more human readable JSON

transect_mask(da_Sv: xarray.core.dataarray.DataArray, transect_dict: dict = {'break': 'BT', 'end': 'ET', 'resume': 'RT', 'start': 'ST'}, bbox_distance_threshold: float = 1.0) → xarray.core.dataarray.DataArray

Mask data from Data Array containing Sv data based off of a Regions2D object and its transect_values.

We should note that this convention for start, break, resume, end transect is very specific to the convention used for the NOAA Hake Survey. If you would like to add your own schema for transect logging, please create an issue in the following link: OSOceanAcoustics/echoregions#issues.

Parameters

da_SvData Array

DataArray of shape (ping_time, depth) containing Sv data.

transect_dictdict

Dictionary for transect values. Values must be unique.

bbox_distance_threshold: float

The maximum value for how far apart the left and right bounding box for each transect value region. Default is set to 1 minute.

Returns

——-

MData Array

A DataArray masked by the transect values from the Regions2d.data dataframe with dimensions (ping_time, depth).