Functions in the append module

(Content automatically geneated from the source code)

KOBBE.APPEND

Functions for appending and interpolating external datasets to an xarray Dataset containing Nortek Signature data.

kobbe.append.add_to_sigdata(ds: Dataset, data: ndarray | List[float], time: ndarray | List[str | datetime64 | float], name: str, attrs: Dict[str, Any] | None = None, time_mat: bool = False, extrapolate: bool = False, interpolate_input: bool = True) → Dataset

Adds a time series to the Signature dataset. Interpolates onto the “TIME” coordinate (one entry per ensemble).

This function can be used to append time series data, such as remote sensing data, to an existing xarray dataset for comparison or validation.

Parameters:

  • ds (xr.Dataset) – The xarray dataset with signature data.

  • data (Union[np.ndarray, List[float]]) – The time series data to be added.

  • time (Union[np.ndarray, List[Union[str, np.datetime64, float]]]) – The time grid of the data. This can be in datetime64 format, as strings (e.g., [‘2022-05-21’]), or as numeric values (e.g., Python epoch time or Matlab timestamp).

  • name (str) – The name of the new variable to be added to the dataset.

  • attrs (Optional[Dict[str, Any]], optional) – Attributes of the new variable, such as units and long_name, by default None.

  • time_mat (bool, optional) – Set to True if time is provided in MATLAB epoch format. If False (default), the time is assumed to be in Python default epoch or standard datetime format.

  • extrapolate (bool, optional) – If True, values will be extrapolated outside the range of the input data by simply extending the edge values. By default, extrapolate is set to False.

  • interpolate_input (If True, the function will interpolate over gaps in the) – input data.

Returns:

The xarray dataset including the new variable.

Return type:

xr.Dataset

kobbe.append.append_atm_pres(ds: Dataset, slp: ndarray, slptime: ndarray, attrs: Dict[str, Any] | None = None, time_mat: bool = False) → Dataset

Append sea level pressure from e.g. ERA-5. Note that the pressure units should be dbar.

Append external sea level atmospheric pressure data (from e.g. ERA5) to a Signature xarray Dataset.

Interpolates onto the TIME grid of the sig500 data and adds to the sig500 data as the variable SLP.

Inputs

ds: xarray dataset with signature data.

slp: Sea level atmospheric pressure [dbar]. slptime: Time stamp of slp. attrs: Attributes (dictionary). time_mat: Set to True if slptime is matlab epoch

(False/default: python default epoch or datetime64).

Outputs

ds: The xarray dataset including the SLP variable.

kobbe.append.append_atm_pres_auto(ds: Dataset) → Dataset

Automatically obtain atmospheric pressure from ERA-5 and append to the dataset.

Can take a while (expect a minute or so for most applications).

Hourly ERA-5 data are obtained over OpenDAP from the Asia-Pacific Data Research Center (APDRC): http://apdrc.soest.hawaii.edu/dods/ public_data/Reanalysis_Data/ERA5/hourly/Surface_pressure.info.

Inputs

ds: xarray dataset with signature data.

Outputs

ds: The xarray dataset including the SLP variable.

kobbe.append.append_ctd(ds: Dataset, temp: ndarray, sal: ndarray, pres: ndarray, CTDtime: ndarray, instr_SN: str | None = 'N/A', instr_desc: str | None = 'N/A', time_mat: bool = False, extrapolate: bool = True, other_attrs: dict = {}) → Dataset

Append moored CTD data to an xarray Signature Dataset, converting to TEOS-10 variables and computing sound speed using the GSW module. The CTD data is interpolated onto the time grid of the signature data in the provided dataset.

Parameters:

  • ds (xr.Dataset) – The xarray Dataset containing signature data to which CTD data will be added.

  • temp (np.ndarray) – In-situ temperature in degrees Celsius.

  • sal (np.ndarray) – Practical salinity (dimensionless).

  • pres (np.ndarray) – Ocean pressure in dbar.

  • CTDtime (np.ndarray) – Timestamps corresponding to the CTD measurements.

  • instr_SN (Optional[str], optional) – Instrument serial number, by default ‘N/A’.

  • instr_desc (Optional[str], optional) – Description of the instrument, by default None.

  • time_mat (bool, optional) – If True, time interpolation will use a MATLAB-compatible method, by default False.

  • extrapolate (bool, optional) – If True, allows extrapolation during interpolation, by default True.

  • other_attrs (dict, optional) – Dictonary of other attributes to include.

Returns:

The xarray Dataset with added variables for Absolute Salinity (SA), Conservative Temperature (CT), Pressure (pres_CTD), Sound Speed (sound_speed_CTD), and Ocean Density (rho_CTD), all interpolated onto the signature data time grid.

Return type:

xr.Dataset

kobbe.append.append_magdec(ds: Dataset, magdec: float | ndarray, magdectime: ndarray | None = None, attrs: Dict[str, Any] | None = None, time_mat: bool = False, extrapolate: bool = True) → Dataset

Append the magnetic declination angle to an xarray Dataset. This angle is used for correcting the heading of observed velocities. The magnetic declination can be provided as a fixed value or as a time-varying array.

If time-varying, the declination will be interpolated onto the time grid of the signature data in the provided dataset.

Appended to the sig500 data as the variable magdec - either as a single number or interpolated onto the TIME grid of the sig500 data.

Parameters:

  • ds (xr.Dataset) – The xarray Dataset containing signature data to which the magnetic declination will be added.

  • magdec (Union[float, np.ndarray]) – Magnetic declination angle in degrees. Can be a single float value or an array of time-varying declinations.

  • magdectime (Optional[np.ndarray], optional) – Timestamps corresponding to the time-varying magnetic declination. Required if magdec is an array, by default None.

  • attrs (Optional[Dict[str, Any]], optional) – Attributes to add to the magnetic declination variable, by default None. If provided, this dictionary will override the default attributes.

  • time_mat (bool, optional) – If True, indicates that magdectime is in MATLAB epoch format, by default False.

  • extrapolate (bool, optional) – If True, allows extrapolation during interpolation, by default True.

Returns:

The xarray Dataset with the added magnetic declination (magdec) variable.

Return type:

xr.Dataset

kobbe.append.append_magdec_auto(ds: Dataset, model: str = 'auto') → Dataset

Automatically obtain magnetic declination from the World Magnetic Model.

Wrapping the pygeomag module (https://pypi.org/project/pygeomag/) which obtains declination angle from the World Magnetic Model (WMM).

model: str

Which WMM version to use. Options: [‘2010’, ‘2015’, ‘2020’], otherwise determined based on the data. Note that auto detection can cause (small) discontinuities across 2014-2015 and 2019-2020.

kobbe.append.set_lat_lon(ds: Dataset, lat: float, lon: float) → Dataset

Append a single latitude value to a Signature xarray Dataset.

Parameters:

  • ds (xr.Dataset) – The xarray Dataset to which the latitude will be added.

  • lat (float) – Latitude in degrees north.

Returns:

The xarray Dataset with the added latitude variable (lat).

Return type:

xr.Dataset