Source code for ppcpy.calibration.lidarconstant

"""
Testtext for documentation


contains :py:func:`get_best_LC`
"""
import numpy as np
import logging
from collections import defaultdict
from ppcpy.misc.helper import mean_stable
from ppcpy.misc.helper import default_to_regular

elastic2raman:dict = {355: 387, 532: 607}


[docs] def loadDefaults(data_cube, **defaults) -> dict: """Prepare default Lidar calibration values. Parameters ---------- data_cube : object Main PicassoProc object. LC : list, optional Default Lidar constant value per channel. LCStd : list, optional Default Lidar constant error per channel. Returns ------- defaultDict : dict Default Lidar calibration result per channel. Each channel contains a list with one single sub-dict with entries: ``LC`` : float Default Lidar calibration constant. ``LCStd`` : float Default uncertainty of lidar calibration constant. ``method`` : str Name of retrieval method. Notes ----- Default values are by standard taken from their config variable but can be overwritten if passed as an input to this function. The order of ``LC`` and ``LCStd`` must match the channel order in ``data_cube.retrievals_highres['channel']``. .. TODO:: Consider allowing default values for a single channel to passed as input. **History** - 2026-08-07: First edition by Buholdt Example ------- >> loadDefaults(data_cube, LC=[1e13, 1, 1, 1, 4e14, 1, ...], LCStd=[1e-3, 1, 1, 1, 2e-2, 1, ...] ) """ default_values = data_cube.polly_config_dict | defaults default_LC = np.asarray(default_values['LC']) default_LCStd = np.asarray(default_values['LCStd']) defaultDict = {} channels = [ (355, 'FR'), (532, 'FR'), (1064, 'FR'), (387, 'FR'), (607, 'FR'), (355, 'NR'), (532, 'NR'), (387, 'NR'), (607, 'NR'), ] for (wv, tel) in channels: defaultDict[f"{wv}_total_{tel}"] = [{ 'LC': float(np.squeeze(default_LC[data_cube.gf(wv, 'total', tel)])), 'LCStd': float(np.squeeze(default_LCStd[data_cube.gf(wv, 'total', tel)])), 'method': 'default' }] return defaultDict
[docs] def lc_for_cldFreeGrps(data_cube, retrieval:str, collect_debug:bool=False) -> dict: """Estimate lidar calibration constant from the optical profiles. Parameters ---------- data_cube : object Main PicassoProc object. retrieval : str Retrieval type. 'klett' or 'raman'. collect_debug : bool, optional If true, collects debug information. Default is False Returns ------- LCs : dict Lidar calibration results for ``retrieval`` retrieved optical profiles per channel. Each channel contains a list of sub-dicts with entries: ``LC`` : float Lidar calibration constant. ``LCStd`` : float Uncertainty of lidar calibration constant. ``time_start``, ``time_end`` : int Start and stop times for successful calibration. ``method`` : str Name of retrieval method. The number of elements in each list depends on the number of successful retrievals. Notes ----- For NR channels, the LC is calculated directly form the optical profiles, whereas in the matlab version, it is estimated by multiplying the respective FR LC with ``olAttri387.sigRatio``. The function uses the following configuration flags: - ``flagUseRetrievedExt4LCCalc``: If enabled the retrieved extinction when calculating the LCs. If disabled the extinction will be estimated by the retrieved backscatter times the assumed LR. The options for Rotational Raman and Aeronet LC retrievals are currently missing. .. TODO:: Check if LC's are normalized with respect to the mean of the profiles. .. TODO:: Add option for Aeronet and rotational Raman retrieved LC. **History** xxxx-xx-xx: First edition by ... 2026-03-18: Changed beta_mol for inelastic wavelengths and added the 'flagUseRetrievedExt4LCCalc' variable. """ logging.info(f'LC retrieval: {retrieval} method') height = data_cube.retrievals_highres['range'] hres = data_cube.rawdata_dict['measurement_height_resolution']['var_data'] config_dict = data_cube.polly_config_dict heightFullOverlap = [np.array(config_dict['heightFullOverlap']) for i in data_cube.clFreeGrps] LCs = defaultdict(list) for i, cldFree in enumerate(data_cube.clFreeGrps): cldFreeTime = np.array(data_cube.retrievals_highres['time'])[cldFree] cldFree = cldFree[0], cldFree[1] + 1 profiles = data_cube.retrievals_profile[retrieval][i] for channel in profiles: wv, t, tel = channel.split('_') ## Telescope type dependent configurations if tel == 'NR': key_smooth = f'smoothWin_{retrieval}_NR_' key_LR = 'LR_NR_' else: key_smooth = f'smoothWin_{retrieval}_' key_LR = 'LR' hFullOverlap = heightFullOverlap[i][data_cube.gf(wv, t, tel)][0] hBaseInd = np.argmax( height >= (hFullOverlap + config_dict[f'{key_smooth}{wv}'] / 2 * hres)) ## Elastic signal sig = profiles[channel]['signal'] signal = np.nanmean(np.squeeze( # TODO: try to use PCR --> normalized data_cube.retrievals_highres[f'sig{sig}'][slice(*cldFree), :, data_cube.gf(wv, t, tel)]), axis=0) molBsc = data_cube.mol_profiles[f'mBsc_{wv}'][i, :].copy() molExt = data_cube.mol_profiles[f'mExt_{wv}'][i, :].copy() ## Check for available retrievals if not ('aerExt' in profiles[channel] and 'aerBsc' in profiles[channel]): logging.warning(f'No available retrievals, skipping {channel} {cldFree}') continue ## Backscatter and extinction retrievals aerBsc = profiles[channel]['aerBsc'].copy() if config_dict['flagUseRetrievedExt4LCCalc'] & ~config_dict['flagPicassoComparison']: logging.info("Using Retrieved Extinction") aerExt = profiles[channel]['aerExt'].copy() else: logging.info("Using approximated Extinction") aerBsc[aerBsc <= 0] = np.nan aerExt = aerBsc * config_dict[f'{key_LR}{wv}'] ## Interpolate extinction to ground aerExt[:hBaseInd + 1] = aerExt[hBaseInd] ## Optical depth (OD) aerOD = np.nancumsum(aerExt * np.concatenate(([height[0]], np.diff(height)))) molOD = np.nancumsum(molExt * np.concatenate(([height[0]], np.diff(height)))) ## Round trip transmission trans = np.exp(-2 * (aerOD + molOD)) bsc = molBsc + aerBsc ## Lidar calibration constant LC = (signal * height**2) / (bsc * trans) LC[LC <= 0] = np.nan LC_stable, _, LCStd = mean_stable( x=LC, win=config_dict['LCMeanWindow'], minBin=config_dict['LCMeanMinIndx'], maxBin=config_dict['LCMeanMaxIndx'] ) logging.info(f"cldFreGrp {i}, Channel {wv} {t} {tel}, LC_stable {LC_stable}, LCStd {LCStd}") if LC_stable is None: logging.warning(f"Can not find a stable LC value, skipping {wv} nm {t} {tel} channel for cloud free period {cldFree}") continue ## save LC result LCs[channel].append({ 'LC': LC_stable, 'LCStd': LC_stable * LCStd, 'time_start': int(cldFreeTime[0]), 'time_end': int(cldFreeTime[1]), 'method': retrieval }) ## Collect debug info if collect_debug: LCs[channel][-1]['LC_profile'] = LC # ----------------------------------------------------------------------------------- # LC for raman / inelastic channels # ----------------------------------------------------------------------------------- if retrieval == 'raman' and int(wv) in elastic2raman.keys(): wv_r = elastic2raman[int(wv)] ## Inelastic signal, backscatter and extinction: signal_r = np.nanmean(np.squeeze( # TODO: try to use PCR --> normalized data_cube.retrievals_highres[f'sig{sig}'][slice(*cldFree), :, data_cube.gf(wv_r, t, tel)]), axis=0) molBsc_r = data_cube.mol_profiles[f'mBsc_{wv_r}'][i, :].copy() molExt_r = data_cube.mol_profiles[f'mExt_{wv_r}'][i, :].copy() aerExt_r = aerExt * (int(wv)/int(wv_r))**config_dict['angstrexp'] ## Optical depth (OD) aerOD_r = np.nancumsum(aerExt_r * np.concatenate(([height[0]], np.diff(height)))) molOD_r = np.nancumsum(molExt_r * np.concatenate(([height[0]], np.diff(height)))) ## Round-trip transmission trans_r = np.exp(- (aerOD + molOD + aerOD_r + molOD_r)) bsc_r = molBsc_r if config_dict['flagPicassoComparison']: bsc_r = molBsc ## Lidar calibration constant LC_r = (signal_r * height**2) / (bsc_r * trans_r) LC_r[LC_r <= 0] = np.nan LC_r_stable, _, LCStd_r = mean_stable( x=LC_r, win=config_dict['LCMeanWindow'], minBin=config_dict['LCMeanMinIndx'], maxBin=config_dict['LCMeanMaxIndx'] ) logging.info(f"cldFreGrp {i}, Channel {wv_r} {t} {tel}, LC_stable {LC_r_stable}, LCStd {LCStd_r}") if LC_r_stable is None: logging.warning(f"Can not find a stable LC value, skipping {wv_r} nm {t} {tel} channel for cloud free period {cldFree}") continue ## Save LC result LCs[f"{wv_r}_{t}_{tel}"].append({ 'LC': LC_r_stable, 'LCStd': LC_r_stable * LCStd_r, 'time_start': int(cldFreeTime[0]), 'time_end': int(cldFreeTime[1]), 'method': retrieval }) ## Collect debug info if collect_debug: LCs[f"{wv_r}_{t}_{tel}"][-1]['LC_profile'] = LC_r return default_to_regular(LCs)