Lines

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

Bases: object

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

Methods

bottom_mask(da_Sv[, operation])	Subsets a bottom dataset to the range of an Sv dataset.
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
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

bottom_mask(da_Sv[, operation])	Subsets a bottom dataset to the range of an Sv dataset.
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
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

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

Subsets a bottom dataset to the range of an Sv dataset. Create a mask of the same shape as data found in the Echogram object: Bottom: 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 bottom mask.

**kwargsdict

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

Returns

bottom_maskXarray DataArray

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

bottom_pointspd.DataFrame

DataFrame containing depth and time.

Notes

If operation == ‘regionmask’:

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

1) Point at the bottom leftmost corner. The depth of this point is based on the maximum of the EVL bottom 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 bottom point to this leftmost edge. One can think of this as a left facing extension of the leftmost EVL bottom 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 bottom point to this rightmost edge. One can think of this as a right facing extension of the rightmost EVL bottom point until the right edge of the Echogram. 4) Point at the bottom 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 bottom-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, bottom 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 bottom data points found in the lines.data dataframe. The nearest interpolation method from Pandas has a problem when points are far from each other.

plot(fmt: str = '', start_time: Optional[Timestamp] = None, end_time: Optional[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

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: Optional[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