FqprSubset

class HSTB.kluster.modules.subset.FqprSubset(fqpr)

Bases: object

Tools for building a subset, or a smaller piece of the larger Fqpr instance.

fqpr = fully qualified ping record, the term for the datastore in kluster

Processed fqpr_generation.Fqpr instance is passed in as argument

Attributes Summary

is_subset

Methods Summary

get_variable_by_filter(variable_name[, ...])

ping_filter is set upon selecting points in 2d/3d in Kluster.

redo_subset()

Subset by the existing subset times, used after reload to get the subset back

restore_subset()

Restores the original data if subset_by_time has been run.

return_soundings_in_polygon(polygon[, ...])

Using provided coordinates (in either horizontal_crs projected or geographic coordinates), return the soundings and sounding attributes for all soundings within the coordinates.

set_filter_by_polygon(polygon[, geographic])

Using this method sets the ping_filter attribute so that you can now use the set_variable_by_filter and get_variable_by_filter methods to get other variables or set data within the polygon selection.

set_variable_by_filter(variable_name, new_data)

ping_filter is set upon selecting points in 2d/3d in Kluster.

subset_by_lines(line_names)

Use the logged start time, end time of the multibeam files to exclude data from all other lines.

subset_by_time([mintime, maxtime])

We save the line start/end time as an attribute within each raw_ping record.

subset_by_time_and_beam(subset_time, subset_beam)

Subset an Fqpr instance according to the provided pairs of time,beam.

subset_by_times(time_segments)

Only retain the portions of this Fqpr object that are within the time segments given in the list provided.

subset_variables(variable_selection[, ...])

Take specific variable names and return just those variables in a new xarray dataset.

subset_variables_by_line(variable_selection)

Apply subset_variables to get the data split up into lines for the variable_selection provided

Attributes Documentation

is_subset

Methods Documentation

get_variable_by_filter(variable_name, selected_index=None, by_sonar_head=False)

ping_filter is set upon selecting points in 2d/3d in Kluster. See return_soundings_in_polygon. Here we can take those points and set one of the variables with new data. Optionally, you can include a selected_index that is a list of flattened indices to points in the ping_filter that you want to super-select. See kluster_main.set_pointsview_points_status

new data are set in memory and saved to disk

Parameters

  • variable_name (str) – name of the variable to set, i.e. ‘detectioninfo’

  • selected_index (Optional[list]) – super_selection of the ping_filter selection, done in points_view currently when selecting with the mouse

  • by_sonar_head (bool) – if True, will return a list of arrays, one array for each sonar head.

redo_subset()

Subset by the existing subset times, used after reload to get the subset back

restore_subset()

Restores the original data if subset_by_time has been run.

return_soundings_in_polygon(polygon, geographic=True, variable_selection=('head', 'x', 'y', 'z', 'tvu', 'detectioninfo', 'time', 'beam'), isolate_head=None)

Using provided coordinates (in either horizontal_crs projected or geographic coordinates), return the soundings and sounding attributes for all soundings within the coordinates.

Using this method sets the ping_filter attribute so that you can now use the set_variable_by_filter and get_variable_by_filter methods to get other variables or set data within the polygon selection.

Parameters

  • polygon (ndarray) – (N, 2) array of points that make up the selection polygon

  • geographic (bool) – If True, the coordinates provided are geographic (latitude/longitude)

  • variable_selection (tuple) – list of the variables that you want to return for the soundings in the polygon

  • isolate_head (Optional[int]) – only used with return_soundings, if provided will only return soundings corresponding to this head index, 0 = port, 1 = starboard

Returns

list of numpy arrays for each variable in variable selection

Return type

list

set_filter_by_polygon(polygon, geographic=True)

Using this method sets the ping_filter attribute so that you can now use the set_variable_by_filter and get_variable_by_filter methods to get other variables or set data within the polygon selection.

This is an alternative to return_soundings_in_polygon that you can use if you want to set the filter without loading/returning a lot of data.

Parameters

  • polygon (ndarray) – (N, 2) array of points that make up the selection polygon

  • geographic (bool) – If True, the coordinates provided are geographic (latitude/longitude)

set_variable_by_filter(variable_name, new_data, selected_index=None)

ping_filter is set upon selecting points in 2d/3d in Kluster. See return_soundings_in_polygon. Here we can take those points and set one of the variables with new data. Optionally, you can include a selected_index that is a list of flattened indices to points in the ping_filter that you want to super-select. See kluster_main.set_pointsview_points_status

new data are set in memory and saved to disk

Parameters

  • variable_name (str) – name of the variable to set, i.e. ‘detectioninfo’

  • new_data (Union[array, list, float, int, str]) – new data to set to the soundings selected by ping_filter for this variable. Generally used for setting a new sounding flag in detectioninfo, where all selected soundings would have new_data = 1 or 2

  • selected_index (Optional[list]) – super_selection of the ping_filter selection, done in points_view currently when selecting with the mouse

subset_by_lines(line_names)

Use the logged start time, end time of the multibeam files to exclude data from all other lines. The result is the data only for the lines provided, concatenated into a single dataset.

To return to the full original dataset, use restore_subset

Parameters

line_names (Union[str, list]) – multibeam file names that you want to include in the subset datasets, all other lines are excluded

subset_by_time(mintime=None, maxtime=None)

We save the line start/end time as an attribute within each raw_ping record. Use this method to pull out just the data that is within the mintime/maxtime range (inclusive mintime, exclusive maxtime). The class will then only have access to data within that time period.

To return to the full original dataset, use restore_subset

Parameters

  • mintime (Optional[float]) – minimum time of the subset, if not provided and maxtime is, use the minimum time of the datasets

  • maxtime (Optional[float]) – maximum time of the subset, if not provided and mintime is, use the maximum time of the datasets

Returns

Error if True

Return type

bool

subset_by_time_and_beam(subset_time, subset_beam)

Subset an Fqpr instance according to the provided pairs of time,beam. In order to keep the fqpr in 2d space, we subset the datasets to the unique times and then provide a boolean mask of those values that match the provided time,beam combinations.

Note that the provided time,beam arrays must be the same shape, as they are treated as pairs of values

Parameters

  • subset_time (ndarray) – 1d array of utc timestamps, used to match the xarray dataset time coordinate

  • subset_beam (ndarray) – 1d array of beam number, used to match the xarray dataset beam coordinate

Returns

list of 1d boolean mask arrays, that can be used to get the exact values of those points that match in time,beam. length of this list is equal to the number of sonar heads, i.e. len(fqpr.multibeam.raw_ping)

Return type

list

subset_by_times(time_segments)

Only retain the portions of this Fqpr object that are within the time segments given in the list provided. The resultant datasets will be the portions of the datasets that lie within the list of time segments concatenated together.

To return to the full original dataset, use restore_subset

Parameters

time_segments (list) – list of lists, where each sub list is the [start time of the segment in utc seconds, endtime of the segment in utc seconds]

subset_variables(variable_selection, ping_times=None, skip_subset_by_time=False, filter_by_detection=False)

Take specific variable names and return just those variables in a new xarray dataset. If you provide ping_times, either as the minmax of a range or individual times, it will return the variables just within those times.

Parameters

  • variable_selection (list) – variable names you want from the fqpr dataset

  • ping_times (Union[array, float, tuple, None]) – time to select the dataset by, can either be an array of times (will use the min/max of the array to subset), a float for a single time, or a tuple of (min time, max time). If None, will use the min/max of the dataset

  • skip_subset_by_time (bool) – if True, will not run the subset by time method

  • filter_by_detection (bool) – if True, will filter the dataset by the detection info flag = 2 (rejected by multibeam system)

Returns

Dataset with just the variable_selection variables, optionally trimmed to times provided

Return type

xr.Dataset

subset_variables_by_line(variable_selection, line_names=None, ping_times=None, filter_by_detection=False)

Apply subset_variables to get the data split up into lines for the variable_selection provided

Parameters

  • variable_selection (list) – variable names you want from the fqpr dataset

  • line_names (Union[str, list, None]) – if provided, only returns data for the line(s), otherwise, returns data for all lines

  • ping_times (Optional[tuple]) – time to select the dataset by, must be a tuple of (min time, max time) in utc seconds. If None, will use the full min/max time of the dataset

  • filter_by_detection (bool) – if True, will filter the dataset by the detection info flag = 2 (rejected by multibeam system)

Returns

dict of {linename: xr.Dataset} for each line name in the dataset (or just for the line names provided if you provide line names)

Return type

dict