pelagos_py.steps.quality_control.par_irregularity_qc#

pelagos_py.steps.quality_control.par_irregularity_qc.calculate_solar_elevation(latitude, longitude, datetime)[source]#

Calculate the solar elevation angle for given geographic coordinates and timestamps.

Parameters:

  • latitude (array-like or float) – Latitude(s) of the observation point(s) in decimal degrees. Positive north.

  • longitude (array-like or float) – Longitude(s) of the observation point(s) in decimal degrees. Positive east.

  • datetime (array-like or pandas.DatetimeIndex) – Datetime(s) of observation. Can be any format convertible by pandas.to_datetime.

Returns:

Solar elevation angle(s) in degrees, corresponding to each input coordinate/time.

Return type:

np.ndarray

Notes

  • The calculation uses pvlib.solarposition.get_solarposition with times localized to UTC.

  • Intended for use with xarray datasets where each profile has a single latitude, longitude, and datetime (e.g., one value per N_PROF).

pelagos_py.steps.quality_control.par_irregularity_qc.qc_par_flagging(pres, par, sun_elev, nei_par=0.03)[source]#

Real-time quality control (RT-QC) for PAR profiles following La Forgia & Organelli (2025, L&O Methods, 23:526–542).

The algorithm flags each PAR measurement according to the statistical shape of the irradiance profile and solar elevation. It is designed for irregularly spaced glider or float data.

Parameters:

  • pres (array-like) – Pressure or depth (dbar or m), increasing with depth.

  • par (array-like) – Downwelling PAR (µmol photons m⁻² s⁻¹).

  • sun_elev (float) – Solar elevation (degrees). >0 = day, ≤0 = night.

  • nei_par (float, optional) – Noise Equivalent Irradiance (µmol photons m⁻² s⁻¹). Default = 3×10⁻² (Jutard et al. 2021).

Returns:

  • flags (ndarray of int) – QC flags (1=good, 2=probably good, 3=probably bad, 4=bad, 9=missing) for each data point.

  • profile_flag (int) – Summary QC flag for the entire profile (1–4).

  • pa (float) – Critical pressure separating lit vs transition region. NaN if undefined.

Notes

Implements the steps in La Forgia & Organelli (2025):

Preliminary tests:

  • Missing data → 9

  • PAR < −NEI → 3

  • PAR < 0 or > 2500 → 4

  • Determine day/night from solar elevation

Daytime sequence:

  • Interpolate PAR on 0.1 dbar grid (only where finite)

  • Apply Shapiro–Wilk normality test on successive tail segments

  • Last null p-value → P_A (lit/transition boundary)

  • Fit 4th-order polynomial below P_A to locate P_C (transition → 2, deeper → 3)

Nighttime sequence:

  • If all p-values >0 → 2 (probably good)

  • Else compute P_A and compare mean PAR above/below it

class pelagos_py.steps.quality_control.par_irregularity_qc.par_irregularity_qc(data, **kwargs)[source]#

Bases: pelagos_py.steps.base_qc.BaseQC

Wrapper for qc_par_flagging, defining solar_elevation if it is not provided.

return_qc()[source]#

Representative of QC processing, to be overridden by subclasses.

Returns:

flags – Output QC flags for the data specific to the test.

Return type:

array-like

plot_diagnostics()[source]#

Representative of diagnostic plotting (optional).