Functions in the load module

(Content automatically geneated from the source code)

KOBBE.LOAD

Various functions for loading and concatenating Nortek Signature matfiles produced by Nortek SignatureDeployment.

kobbe.load.chop(ds: Dataset, indices: Tuple[int, int] | None = None, auto_accept: bool = False) → Dataset

Chop an xarray Dataset by removing data outside of a specified range or based on a pressure-based algorithm.

Default behaviour is to display a plot showing the suggested chop. The user can then accept or decline.

If indices is not provided, the function will use a pressure-based algorithm to suggest a range for chopping.

Parameters:

  • ds (xr.Dataset) – The xarray Dataset containing the data to be chopped. The dataset should include the field Average_Pressure.

  • indices (Optional[Tuple[int, int]]) – Tuple of indices (start, stop) for slicing the dataset along the TIME dimension. If not provided, a pressure-based algorithm is used.

  • auto_accept (bool) – If True, automatically accepts the suggested chop based on the pressure record. If False, prompts the user for confirmation.

Returns:

The chopped xarray Dataset.

Return type:

xr.Dataset

kobbe.load.load_nc(nc_file: str) → Dataset

Open an existing Signature dataset that was previously saved in NetCDF format and loads it as an xarray Dataset. The dataset is opened without applying CF (Climate and Forecast) metadata decoding.

Parameters:

nc_filestr

The path to the NetCDF file that contains the saved dataset.

Returns:

xr.Dataset

An xarray Dataset containing the data from the specified NetCDF file.

kobbe.load.matfiles_to_dataset(file_input: List[str] | str, reshape: bool = True, lat: float | None = None, lon: float | None = None, orientation: str = 'up', include_raw_altimeter: bool = False, FOM_ice_threshold: float = 10000.0, time_threshold_min: bool | float = None, time_range: Tuple[str | None, str | None] | None = None) → Dataset

Read, convert, and concatenate .mat files exported from SignatureDeployment.

Parameters:

  • file_input (Union[List[str], str]) – List of file paths to .mat files, or a directory containing .mat files.

  • reshape (bool, optional) – If True, reshape all time series from a single ‘time_average’ dimension to 2D (‘TIME’, ‘SAMPLE’) where TIME is the mean time of each ensemble and SAMPLE is each sample in the ensemble. Default is True.

  • lat (Optional[float], optional) – Latitude of deployment. If None, this information is not included. Default is None.

  • lon (Optional[float], optional) – Longitude of deployment. If None, this information is not included. Default is None.

  • orientation (str ('up', 'down')) – Vertical orientation of the acoustic beam. Default is ‘up’.

  • include_raw_altimeter (bool, optional) – Include raw altimeter signal if available (typically on a single time grid). Default is False.

  • FOM_ice_threshold (float, optional) – Threshold for “Figure of Merit” in the ice ADCP pings used to separate measurements in ice from measurements of water. Default is 1e4.

  • time_threshold_min (Union[bool, float]) – Time difference (minutes) between samples used to identify individual ensembles when reshaping. If manually specifying this parameter, set it somewhere between the sampling frequency within an enseble (e.g. 1/60 minutes) and the time between ensebles (e.g. 15 minutes). If None (default), the parameter will be automatically deduced.

  • time_range (Optional[Tuple[Optional[str], Optional[str]]], optional) – Only accept data within this date range. Provide a tuple of date trings in ‘DD.MM.YYYY’ format. Default is None, which includes all data.

Returns:

Xarray Dataset containing the concatenated data.

Return type:

xr.Dataset

Raises:

ValueError – If file_input is empty or if there’s a problem during concatenation.

Notes

The function assumes that the provided .mat files are structured in a way that can be handled by the internal _matfile_to_dataset, _add_tilt, _reshape_ensembles, set_lat_lon, and _add_SIC_FOM functions.

kobbe.load.overview(ds: Dataset) → None

Prints basic information about the given Signature xarray Dataset, including time range, pressure statistics, and dataset size.

Parameters:

ds (xr.Dataset) – The xarray Dataset containing the data to be summarized. The dataset should be generated using the kobbe.load.module.

Return type:

None