Lines

class echoregions.lines.Lines(input_file: Union[str, DataFrame], nan_depth_value: float = None, input_type: str = 'EVL')

Bases: object

Class that contains and performs operations with Depth/Lines data from Echoview EVL files.

Methods

plot([fmt, start_time, end_time, ...])	Plot the points in the EVL file.
replace_nan_depth([inplace])	Replace -10000.99 depth values with user-specified _nan_depth_value
seafloor_mask(da_Sv[, operation])	Subsets a seafloor dataset to the range of an Sv dataset.
to_csv(save_path[, mode])	Save a Dataframe to a .csv file
to_evl(save_path[, mode])	Save a Dataframe to a .evl file
to_json([save_path, pretty])	Convert supported formats to .json file.

Methods Summary

plot([fmt, start_time, end_time, ...])	Plot the points in the EVL file.
replace_nan_depth([inplace])	Replace -10000.99 depth values with user-specified _nan_depth_value
seafloor_mask(da_Sv[, operation])	Subsets a seafloor dataset to the range of an Sv dataset.
to_csv(save_path[, mode])	Save a Dataframe to a .csv file
to_evl(save_path[, mode])	Save a Dataframe to a .evl file
to_json([save_path, pretty])	Convert supported formats to .json file.

Methods Documentation

plot(fmt: str = '', start_time: Timestamp = None, end_time: Timestamp = None, fill_between: bool = False, max_depth: Union[int, float] = 0, **kwargs) → None

Plot the points in the EVL file.

Parameters

fmtstr, optional

A format string such as ‘bo’ for blue circles. See matplotlib documentation for more information.

start_timedatetime64, default None

Lower time bound.

end_timedatetime64, default None

Upper time bound.

fill_betweenbool, default True

Use matplotlib fill_between to plot the line. The area between the EVL points and max_depth will be filled in.

max_depthfloat, default 0

The fill_between function will color in the area betwen the points and this depth value given in meters.

alphafloat, default 0.5

Opacity of the plot

kwargskeyword arguments

Additional arguments passed to matplotlib plot or fill_between. Useful arguments include color, lw, and marker.

replace_nan_depth(inplace: bool = False) → Optional[DataFrame]

Replace -10000.99 depth values with user-specified _nan_depth_value

Parameters

inplacebool

Modify the current data inplace

Returns

DataFrame with depth edges replaced by Lines._nan_depth_value

seafloor_mask(da_Sv: DataArray, operation: str = 'regionmask', **kwargs)

Subsets a seafloor dataset to the range of an Sv dataset. Create a mask of the same shape as data found in the Echogram object: seafloor: 1, Otherwise: 0.

Parameters

da_SvXarray DataArray

Matrix of coordinates (ping_time, depth) that contains Sv values.

operationstr

Whether to use regionmask or below/above logic to produce the seafloor mask.

**kwargsdict

Keyword arguments to be passed to pandas.DataFrame.interpolate.

Returns

seafloor_maskXarray DataArray

Matrix of coordinates (ping_time, depth) with values such that seafloor: 1, otherwise: 0.

seafloor_pointspd.DataFrame

DataFrame containing depth and time.

Notes

If operation == ‘regionmask’:

We create 4 additional seafloor points that further describe the boundary that we want regionmask to mask:

1) Point at the seafloor leftmost corner. The depth of this point is based on the maximum of the EVL seafloor point depth and the Echogram depth, plus an additional 1.0 float offset. 2) Point at the leftmost edge of the Echogram where depth is based on the closest EVL seafloor point to this leftmost edge. One can think of this as a left facing extension of the leftmost EVL seafloor point until the left edge of the Echogram. 3) Point at the rightmost edge of the Echogram where depth is based on the closest EVL seafloor point to this rightmost edge. One can think of this as a right facing extension of the rightmost EVL seafloor point until the right edge of the Echogram. 4) Point at the seafloor rightmost corner. The depth of this point is the same as 1.

The points are there to ensure that regionmask captures the appropriate area during masking. The offset in Point 1 and Point 4 is here to make sure that the line connecting the seafloor-most points are clear of any other points. This would be a problem in the case where there is a point in the middle that matches the maximum of the Sv and EVL point depth. This would lead to regionmask creating possibly 2+ regions, which is behavior that could lead to different outputs. The offset ensures that regionmask always creates just 1 region.

In the dataframe passed into regionmask, the following points are connected in the following order: [1, 2, seafloor points, 3, 4, 1].

For further information on how regionmask deals with edges: https://regionmask.readthedocs.io/en/stable/notebooks/method.html

If operation == ‘above_below’:

Prior to creating the mask, this method performs interpolation on the seafloor data points found in the lines.data dataframe. The nearest interpolation method from Pandas has a problem when points are far from each other.

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_evl(save_path: Union[str, Path], mode: str = 'w') → None

Save a Dataframe to a .evl file

Parameters

save_pathUnion[str, Path]

Path to save the evl file to.

modestr

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

to_json(save_path: str = None, pretty: bool = True, **kwargs) → None

Convert supported formats to .json file.

Parameters

save_pathstr

path to save the JSON file to

prettybool, default True

Output more human readable JSON

kwargs

keyword arguments passed into parse_file