src.toolbox.steps.custom.qc.par_irregularity_qc

QC tests to identify irregularities in PAR profiles based on La Forgia & Organelli (2025). * Shapiro–Wilk test * Day and night sequences

Classes

par_irregularity_qc

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

Functions

calculate_solar_elevation(latitude, longitude, datetime)	Calculate the solar elevation angle for given geographic coordinates and timestamps.
qc_par_flagging(pres, par, sun_elev[, nei_par])	Real-time quality control (RT-QC) for PAR profiles

Module Contents

src.toolbox.steps.custom.qc.par_irregularity_qc.calculate_solar_elevation(latitude, longitude, datetime)

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).

src.toolbox.steps.custom.qc.par_irregularity_qc.qc_par_flagging(pres, par, sun_elev, nei_par=0.03)

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 src.toolbox.steps.custom.qc.par_irregularity_qc.par_irregularity_qc

Bases: toolbox.steps.base_qc.BaseQC

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

qc_name = 'PAR irregularity qc'

expected_parameters

required_variables = ['LATITUDE', 'LONGITUDE', 'TIME', 'PRES', 'DOWNWELLING_PAR', 'PROFILE_NUMBER']

qc_outputs = ['DOWNWELLING_PAR_QC']

return_qc()

plot_diagnostics()