Regions2D

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

Bases: object

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

Methods

close_region([region_id, region_class])	Close a region by appending the first point to end of the list of points.
plot([region_id, region_class, close_regions])	Plot a region from data.
region_mask(da_Sv[, region_id, ...])	Mask data from Data Array containing Sv data based off of a Regions2D object and its regions ids.
replace_nan_depth([inplace])	Replace 9999.99 or -9999.99 depth values with user-specified min_depth and max_depth
select_region([region_id, region_class, ...])	Selects a subset of this Region2D object's dataframe.
select_sonar_file(Sv_list[, time_variable, ...])	Selects Echopype processed Sv files (xarray datasets) based on variable start and end time.
to_csv(save_path[, mode])	Save a Dataframe to a .csv file
to_evr(save_path[, mode])	Save a Dataframe to a .evr file
to_json([save_path])	Convert EVR to a JSON file.
transect_mask(da_Sv[, ...])	Mask data from Data Array containing Sv data based off of a Regions2D object and its transect_values.

Methods Summary

close_region([region_id, region_class])	Close a region by appending the first point to end of the list of points.
plot([region_id, region_class, close_regions])	Plot a region from data.
region_mask(da_Sv[, region_id, ...])	Mask data from Data Array containing Sv data based off of a Regions2D object and its regions ids.
replace_nan_depth([inplace])	Replace 9999.99 or -9999.99 depth values with user-specified min_depth and max_depth
select_region([region_id, region_class, ...])	Selects a subset of this Region2D object's dataframe.
select_sonar_file(Sv_list[, time_variable, ...])	Selects Echopype processed Sv files (xarray datasets) based on variable start and end time.
to_csv(save_path[, mode])	Save a Dataframe to a .csv file
to_evr(save_path[, mode])	Save a Dataframe to a .evr file
to_json([save_path])	Convert EVR to a JSON file.
transect_mask(da_Sv[, ...])	Mask data from Data Array containing Sv data based off of a Regions2D object and its transect_values.

Methods Documentation

close_region(region_id: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None, region_class: Optional[Union[str, List[str]]] = None) → DataFrame

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

Parameters

region_idUnion[float, int, str, List[Union[float, int, str]]], None

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

region_classUnion[str, List[str]], None

A region class or a list of region classes.

Returns

DataFrame

Returns a new DataFrame with closed regions

plot(region_id: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None, region_class: Optional[Union[str, List[str]]] = None, close_regions: bool = False, **kwargs) → None

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

Parameters

region_idUnion[float, int, str, List[Union[float, int, str]]], None

Region ID(s) to select raw files with

region_classUnion[str, List[str]], None

A region class or a list of region classes.

close_regionbool

Plot the region as a closed polygon. Defaults to False

kwargskeyword arguments

Additional arguments passed to matplotlib plot

region_mask(da_Sv: DataArray, region_id: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None, region_class: Optional[Union[str, List[str]]] = None, mask_name: str = 'mask', mask_labels: Optional[dict] = None, collapse_to_2d: bool = False) → Optional[Dataset]

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_idList[Union[float, int, str]]], None

list IDs of regions to create mask for.

region_classUnion[str, List[str]], None

A region class or a list of region classes.

mask_namestr

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

mask_labelsdict

If provided, used to label the region_id dimension of the output mask.

collapse_to_2dbool

If true, then converts 3d mask to 2d mask. If not, keeps output as 3d mask.

Returns

mask_dsDataset

Either a 3D mask or a 2D mask based on the conditions below. If collapse_to_2d is False:

A 3D mask where each layer of the mask will contain a 1s/0s mask for each unique label in the 2D mask. The layers will be labeled via region_id values. The slices of the 3D array will be in the form of 1s/0s: masked areas, and non-masked areas.

If collapse_to_2d is True:

A 2D mask where each individual data points will be in the form of integers, demarking region_id of masked regions, and nan values, demarking non-masked areas.

Also contains a data variable (mask_labels) with mask labels corresponding to region_id values.

region_pointspd.DataFrame

DataFrame containing region_id, depth, and time.

replace_nan_depth(inplace: bool = False) → 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, region_class: Optional[Union[str, List[str]]] = None, time_range: Optional[List[Timestamp]] = None, depth_range: Optional[List[Union[float, int]]] = None, copy=True) → DataFrame

Selects a subset of this Region2D object’s dataframe.

Parameters

region_idUnion[float, int, str, List[Union[float, int, str]]], None

A region id provided as a number, a string, or a list of these. Only one of region_id or region_class should be given.

region_classUnion[str, List[str]], None

A region class or a list of region classes. Only one of region_id or region_class should be given.

time_rangeList of 2 Pandas Timestamps.

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

depth_rangeList of 2 floats.

Depth range for the 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

The filtered Region2D dataframe (Region2D.data) that either contains rows of the specified region_id, or rows of the specified region_class. The Region2D dataframe is also filtered to be within the boundaries specified by the input time_range, and depth_range values.

select_sonar_file(Sv_list: Union[DataArray, Dataset, List[Union[DataArray, Dataset]]], time_variable: str = 'ping_time', region_id: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None, region_class: Optional[Union[str, List[str]]] = None) → List

Selects Echopype processed Sv files (xarray datasets) based on variable start and end time.

Parameters

Sv_listUnion[xr.DataArray, xr.Dataset, List[xr.DataArray, xr.Dataset]]

Echopype processed Sv files.

time_variablestr

Time variable for Sv files. Defaults to ‘ping_time’.

region_idUnion[float, int, str, List[Union[float, int, str]]], None

Region IDs to select sonar files with. If None, select all regions. Defaults to None

region_classUnion[str, List[str]], None

A region class or a list of region classes.

Returns

selected_Svlist[Union[xr.DataArray, xr.Dataset]]

list of Sv data spanning the encompassing region or list of regions.

to_csv(save_path: Union[str, Path], mode: str = 'w', **kwaargs) → None

Save a Dataframe to a .csv file

Parameters

save_pathUnion[str, Path]

Path to save the CSV file to.

modestr

Write mode arg for to_csv. Defaults to ‘w’.

to_evr(save_path: Union[str, Path], mode: str = 'w') → None

Save a Dataframe to a .evr file

Parameters

save_pathUnion[str, Path]

Path to save the evr file to.

modestr

Write mode arg for IO open. Defaults to ‘w’.

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: DataArray, transect_sequence_type_dict: dict = {'break': 'BT', 'end': 'ET', 'resume': 'RT', 'start': 'ST'}, transect_sequence_type_next_allowable_dict: dict = {'BT': ['RT'], 'ET': ['ET', ''], 'RT': ['BT', 'ET'], 'ST': ['BT', 'ET']}, bbox_distance_threshold: float = 1.0, must_pass_check: bool = False) → 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_sequence_type_dictdict

Dictionary for transect sequence type values. The values denote where in the context of the transect each region lays in, i.e. whether we are at the beginning of the transect, a break in the transect, a resumption of the transect, or at the end of the transect.

transect_sequence_type_next_allowable_dictdict

Dictionary for the allowable transect sequence type value(s) that can follow a transect sequence type value.

bbox_distance_threshold: float

Maximum allowable value between the left and right bounding box timestamps for each region that is marked as a transect log. Default is set to 1 minute.

must_pass_checkbool

True: Will check transect strings to enforce sequence rules. If this check encounters any incorrect transect type sequence orders or wider than bbox distance threshold regions, it will raise an exception. False: Will still check transect strings but will instead just print out warnings for violations of the above mentioned sequence rules.

Returns

MData Array

A binary DataArray with dimensions (ping_time, depth) where 1s are within transect and 0s are outside transect.