Functions in the calc module

(Content automatically geneated from the source code)

KOBBE.CALC

Various calculations done on a xarray Dataset with Signature data.

kobbe.calc.clean_nanmedian(a: ndarray, **kwargs: Any) → ndarray

Compute the median of an array while ignoring NaNs, suppressing warnings for all-NaN slices.

This function is a wrapper around np.nanmedian that suppresses the RuntimeWarning triggered when computing the median of an all-NaN slice. The default behavior of returning NaN for such slices is preserved.

Parameters:

a (np.ndarray) – Input array containing numerical data, possibly with NaNs. **kwargs (Any): Additional keyword arguments to pass to np.nanmedian.

Returns:

The median of the array along the specified axis, with NaNs

ignored.

Return type:

np.ndarray

kobbe.calc.daily_average(A: ndarray, t: ndarray, td: ndarray | None = None, min_frac: float = 0.0, function: str = 'median') → Tuple[ndarray, ndarray]

Compute daily averages of a time series A on a time grid t.

This function computes daily averages or medians of the time series data A, based on the time grid t. If the day index td is not specified, it will be computed automatically. The function supports both 1D and 2D arrays, with the time axis being the last axis.

Parameters:

  • A (np.ndarray) – Input array containing the time series data, which can be 1D or 2D.

  • t (np.ndarray) – Time grid corresponding to the data in A.

  • td (Optional[np.ndarray], optional) – Day index. If not provided, it will be computed from t.

  • axis (int, optional) – Axis along which the computation is performed. Defaults to -1.

  • min_frac (float, optional) – Minimum required non-masked fraction of data to compute the statistic. If the valid data fraction is less than min_frac, NaN is returned. Defaults to 0.0.

  • function (str, optional) – Function to use for daily aggregation. Can be “median” or “mean”. Defaults to “median”.

Returns:

  • Ad (np.ndarray): Daily averaged data.

  • td (np.ndarray): Corresponding day indices.

Return type:

Tuple[np.ndarray, np.ndarray]

kobbe.calc.dep_from_p(ds: Dataset, method: str = 'hs', corr_atmo: bool = True, corr_CTD_density: bool = True) → Dataset

Calculate depth from absolute pressure in a Signature xarray Dataset.

Basing on Average_AltimeterPressure if available, else Average_Pressure.

Using either of the followign based on method

  1. The function gsw.z_from_p, or

  2. Hydrostatic pressure, where

  • Absolute pressure measured by the instrument (from Average_AltimeterPressure if available, else Average_AltimeterPressure plus the fixed atmospheric offset which is automaically subtracted from this field).

  • Atmospheric pressure (from p_atmo field, if available).

  • Gravitational acceleration (calculated from latitude).

  • Ocean density (from rho_CTD field, if available, or default to 1027 kg/m³).

Parameters:

  • ds (xr.Dataset) – xarray Dataset containing Signature data.

  • corr_atmo (bool, optional) – If True, correct for atmospheric pressure using the p_atmo field. Defaults to True.

  • corr_CTD_density (bool, optional) – If True, use CTD-derived density from the rho_CTD field. Defaults to True.

Returns:

The input Dataset with the “instr_depth” field (TIME, SAMPLE)

added.

Return type:

xr.Dataset

kobbe.calc.footprint(signature: Dataset | str, depth: float | None = None, verbose: bool = True) → float

Calculate the approximate footprint width of the vertical beam for an acoustic instrument based on the mean depth of the instrument.

Parameters:

  • signature (xr.Dataset, str) – Either: xarray Dataset containing the Signature instrument data. Or: a string ‘Signature250’ or ‘Signature500’.

  • depth (Union[float, None], optional) – The depth at which to calculate the footprint width. If not provided, the mean depth from the dataset (ds.instr_depth.mean()) will be used. The depth value is rounded to one decimal place.

  • verbose (bool, optional) – If True, prints the calculated footprint width along with the depth and beam width angle. Default is True.

Returns:

The calculated footprint width at the specified depth, rounded to one decimal place.

Return type:

float

Raises:

ValueError – If the instrument attribute in the dataset is not “Signature500” or “Signature250”.

Notes

The footprint width is calculated using the following formula:

footprint_width = 2 * depth * tan(beam_width_angle_rad / 2)

where beam_width_angle_rad is the beam width angle in radians, which is derived from the instrument type.

Examples

>>> ds = xr.Dataset(attrs={"instrument": "Signature500",
                    "instr_depth": (["time"], [50, 60, 55])})
>>> footprint(ds)
Beam width at surface: 2.5 m.
For depth 55.0 m and beam width angle 2.9 degrees (Signature500).
2.5
kobbe.calc.runningstat(A: ndarray, window_size: int) → Dict[str, ndarray]

Calculate running statistics (mean, median, standard deviation) for a time series.

This function computes running statistics (mean, median, and standard deviation) for an equally spaced time series using a sliding window approach. The window size must be odd, and the boundaries are handled by reflecting the data at the ends.

Note: Reflects at the ends - may have to modify the fringes of the time series for some applications..

Based on script by Maksym Ganenko on this thread: https://stackoverflow.com/questions/33585578/ running-or-sliding-median-mean-and-standard-deviation

Parameters:

A (np.ndarray) – Equally spaced time series data. window_size (int): Size of the sliding window (must be odd).

Returns:

A dictionary containing the running ‘mean’,

’median’, and ‘std’ (standard deviation) of the input time series.

Return type:

Dict[str, np.ndarray]

Raises:

AssertionError – If window_size is not odd or greater than the length of A.