Source code for ppcpy.retrievals.depolarization

import logging
import numpy as np

from ppcpy.misc.helper import uniform_filter


[docs] def smooth_signal(signal:np.ndarray, window_len:int) -> np.ndarray: """Uniformly smooth the input signal Parameters ---------- singal : ndarray Signal to be smooth window_len : int Width of the applied uniform filter Returns ------- ndarray Smoothed signal Notes ----- .. TODO:: Check which smoothing shoule be used here! **History** - 2026-02-04: Changed from scipy.ndimage.uniform_filter1d to ppcpy.misc.helper.uniform_filter """ return uniform_filter(signal, window_len)
[docs] def voldepol_cldFreeGrps(data_cube, ret_prof_name:str) -> dict: """... Parameters ---------- ret_prof_name : str ... Returns ------- opt_profiles : dict ... Notes ----- .. TODO:: Finish the docstring. .. TODO:: Should the GHK-Transmission corrected (TCor) or the Background corrected (BGCor) signal be used for calculating the volume depolarisation ratio? - With the GHK formula the BGCor signal has to be used (in the current implementation, the voldepol is even needed to perform the polarization-transmission-correction. .. TODO:: Is the return in this function actually needed?? """ config_dict = data_cube.polly_config_dict.copy() opt_profiles = data_cube.retrievals_profile[ret_prof_name].copy() logging.debug(f"no_profiles: {len(opt_profiles)}") logging.debug(f"{opt_profiles[0].keys()}") # signal = 'TCor' signal = 'BGCor' for i, cldFree in enumerate(data_cube.clFreeGrps): cldFree = cldFree[0], cldFree[1] + 1 for channel in opt_profiles[i]: wv, t, tel = channel.split('_') flagt = data_cube.gf(wv, 'total', tel) flagc = data_cube.gf(wv, 'cross', tel) # indxt = np.where(flagt)[0] retrieval = opt_profiles[i][channel]['retrieval'] if np.any(flagt) and np.any(flagc): logging.info(f'voldepol at channel {wv} cldFree {i} {cldFree}') sigt = np.squeeze(data_cube.retrievals_profile[f'sig{signal}'][i, :, flagt]) # bgt = np.nansum(np.squeeze( # data_cube.retrievals_highres[f'BG{signal}'][slice(*cldFree),data_cube.gf(wv, 'total', tel)]), axis=0) sigc = np.squeeze(data_cube.retrievals_profile[f'sig{signal}'][i, :, flagc]) logging.debug(f"{channel} {data_cube.etaused[f'{wv}_{tel}']}") vdr, vdrStd = calc_profile_vdr( sigt=sigt, sigc=sigc, Gt=config_dict['G'][flagt], Gr=config_dict['G'][flagc], Ht=config_dict['H'][flagt], Hr=config_dict['H'][flagc], eta=data_cube.etaused[f'{wv}_{tel}']['eta'], voldepol_error=config_dict[f'voldepol_error_{wv}'], window=config_dict[f'smoothWin_{retrieval}_{wv}'] ) opt_profiles[i][channel]['vdr'] = vdr opt_profiles[i][channel]['vdrStd'] = vdrStd if np.isnan(data_cube.retrievals_profile['refH'][i][f"{wv}_{t}_{tel}"]['refInd']).any(): logging.warning("No valid refHInd found, skipping retrieval for this channel.") continue mdr, mdrStd, flgaDeftMdr = get_MDR( vdr=vdr, vdrStd=vdrStd, refHInd=data_cube.retrievals_profile['refH'][i][f"{wv}_{t}_{tel}"]['refInd'] ) if config_dict["flagUseTheoreticalMDR"]: logging.info("Use the theoretical MDR value.") mdr = data_cube.polly_config_dict[f"molDepol{wv}"] logging.debug(f"est. mdr {channel} {mdr} {mdrStd}") opt_profiles[i][channel]['mdr'] = mdr opt_profiles[i][channel]['mdrStd'] = mdrStd # experimental code to calculate the mdr without smoothing(?) vdr, vdrStd = calc_profile_vdr( sigt=sigt, sigc=sigc, Gt=config_dict['G'][flagt], Gr=config_dict['G'][flagc], Ht=config_dict['H'][flagt], Hr=config_dict['H'][flagc], eta=data_cube.etaused[f'{wv}_{tel}']['eta'], voldepol_error=config_dict[f'voldepol_error_{wv}'], window=1 ) mdr, mdrStd, flgaDeftMdr = get_MDR( vdr=vdr, vdrStd=vdrStd, refHInd=data_cube.retrievals_profile['refH'][i][f"{wv}_{t}_{tel}"]['refInd'] ) logging.debug(f"est. mdr {channel} {mdr} {mdrStd} (smooth1)") logging.debug(f"{opt_profiles[i][channel].keys()}") return opt_profiles
[docs] def calc_profile_vdr(sigt:np.ndarray, sigc:np.ndarray, Gt:float, Gr:float, Ht:float, Hr:float, eta:float, voldepol_error:float, window:int=1, flag_smooth_before:bool=True) -> tuple: """Calculate volume depolarization ratio using GHK parameters. Parameters ---------- sigt : ndarray Signal strength of the total channel [photon count]. sigc : ndarray Signal strength of the cross channel [photon count]. Gt : float G parameter in the total channel. Gr : float G parameter in the cross channel. Ht : float H parameter in the total channel. Hr : float H parameter in the cross channel. eta : float Depolarization calibration constant. voldepol_error : float Systematic uncertainty coefficient (constant term). Systematic uncertainty coefficient (linear term). Systematic uncertainty coefficient (quadratic term). smooth_window : int, optional The width of the sliding smoothing window for the signal. Default is 1. flag_smooth_before : bool, optional Flag to control whether smoothing is applied before or after the signal ratio. Default is True. Returns ------- vol_depol : ndarray Volume depolarization ratio. vol_depol_std : ndarray Uncertainty of the volume depolarization ratio. References ---------- - Engelmann, R. et al. The automated multiwavelength Raman polarization and water-vapor lidar Polly XT: the neXT generation. Atmospheric Measurement Techniques 9, 1767-1784 (2016). - Freudenthaler, V. et al. Depolarization ratio profiling at several wavelengths in pure Saharan dust during SAMUM 2006. Tellus B 61, 165-179 (2009). - Freudenthaler, V. About the effects of polarising optics on lidar signals and the Delta90 calibration. Atmos. Meas. Tech., 9, 4181–4255 (2016). Notes ----- - Be awere: `sigT = 0` will cause `vol_depol` and `vol_depol_std` to be NaN! .. TODO:: Should consider implementing something to avoid NaN values in this function, as these will also harm the qulity of the retrievals that depend on the transmission corrected signal (ei. introduce more NaN's). **History** - 2018-09-02: First edition by Zhenping - 2018-09-04: Change the smoothing order. Smoothing the signal ratio instead of smoothing the signal. - 2019-05-24: Add 'flag_smooth_before' to control the smoothing order. - 2024-08-13: MH: Change calculation to GHK parameters and eta as depolarization constant. """ logging.info(f"G {Gt} {Gr} H {Ht} {Hr} Eta {eta} error {voldepol_error} Window {window} ") # Smooth signals before or after ratio calculation sig_ratio = sigc / sigt if window > 1: # smoothing with a window size of 1 equals no smoothing if flag_smooth_before: sig_ratio = smooth_signal(sigc, window) / smooth_signal(sigt, window) else: sig_ratio = smooth_signal(sigc / sigt, window) elif window < 1: raise ValueError("Unsupported smoothing window size") # Calculate volume depolarization ratio using GHK parameters vol_depol = (sig_ratio / eta * (Gt + Ht) - (Gr + Hr)) / ((Gr - Hr) - sig_ratio / eta * (Gt - Ht)) # Calculate systematic uncertainty vol_depol_std = (voldepol_error[0] + voldepol_error[1] * vol_depol + voldepol_error[1] * vol_depol**2) return vol_depol, vol_depol_std
[docs] def get_MDR(vdr:np.ndarray, vdrStd:np.ndarray, refHInd:list) -> float: """Get the vdr at reference height. Parameters ---------- vdr : ndarray Volume depolarization ratio. vdrStd : ndarray Uncertainty of the volume depolarization ratio. refHInd : list Reference height indcies [bottum, top]. Returns ------- mdr : ndarray Mean volume depolarization ratio at reference height. mdrStd : ndarray Mean uncertainty of the volume depolarization ratio at reference height. bool False. Notes ----- - in the matlab pollynet processing chain this is done by recalculating vdr for the reference height chunk (Pollynet_Processing_Chain/lib/calibration/pollyMDRGHK.m) - Assuming that it is more efficient to use the precalculated vdr - The snr criterion is missing for this very first version. ** History ** """ mdr = np.mean(vdr[slice(*refHInd)]) mdrStd = np.mean(vdrStd[slice(*refHInd)]) return mdr, mdrStd, False
[docs] def pardepol_cldFreeGrps(data_cube, ret_prof_name:str) -> dict: """... Parameters ---------- data_cube : object Main PicassoProc object. ret_prof_name : str ... Returns ------- opt_porfiles : dict ... Notes ----- .. TODO:: - Finish docsting. - Is the return here necessary? - Cleare unused variables. """ # config_dict = data_cube.polly_config_dict # <-- Not used! opt_profiles = data_cube.retrievals_profile[ret_prof_name].copy() logging.debug(f"no_profiles {len(opt_profiles)}") logging.debug(f"{opt_profiles[0].keys()}") # signal = 'BGCor' # <-- Not used! for i, cldFree in enumerate(data_cube.clFreeGrps): cldFree = cldFree[0], cldFree[1] + 1 for channel in opt_profiles[i]: wv, t, tel = channel.split('_') logging.info(f"Channel: {channel}.") flagt = data_cube.gf(wv, 'total', tel) flagc = data_cube.gf(wv, 'cross', tel) # indxt = np.where(flagt)[0] # <-- Not used! # retrieval = opt_profiles[i][channel]['retrieval'] # <-- Not used! if np.any(flagt) and np.any(flagc) and 'aerBsc' in opt_profiles[i][channel]: logging.info(f"pardepol at channel {wv} cldFree {i} {cldFree}") pdr, pdrStd = calc_pdr( vol_depol=opt_profiles[i][channel]['vdr'], vol_depol_std=opt_profiles[i][channel]['vdrStd'], aer_bsc=opt_profiles[i][channel]['aerBsc'], aer_bsc_std=np.ones_like(opt_profiles[i][channel]['aerBscStd'])*1e-7, # TODO: Hard coded! mol_bsc=data_cube.mol_profiles[f'mBsc_{wv}'][i, :], mol_depol=opt_profiles[i][channel]['mdr'], mol_depol_std=opt_profiles[i][channel]['mdrStd'] ) opt_profiles[i][channel]['pdr'] = pdr opt_profiles[i][channel]['pdrStd'] = pdrStd # print('after ', opt_profiles[i][channel].keys()) return opt_profiles
[docs] def calc_pdr(vol_depol:np.ndarray, vol_depol_std:np.ndarray, aer_bsc:np.ndarray, aer_bsc_std:np.ndarray, mol_bsc:np.ndarray, mol_depol:float, mol_depol_std:float) -> tuple: """Calculate the particle depolarization ratio and estimate its standard deviation. Parameters ---------- vol_depol : ndarray Volume depolarization ratio. vol_depol_std : ndarray Standard deviation of volume depolarization ratio. aer_bsc : ndarray Aerosol backscatter coefficient [m^{-1}Sr^{-1}]. aer_bsc_std : ndarray Standard deviation of aerosol backscatter coefficient [m^{-1}Sr^{-1}]. mol_bsc : ndarray Molecule backscatter coefficient [m^{-1}Sr^{-1}]. mol_depol : float Molecule depolarization ratio, dependent on central wavelength and IF bandwidth. mol_depol_std : float Standard deviation of molecule depolarization ratio. Returns ------- par_depol : ndarray Particle depolarization ratio. par_depol_std : ndarray Standard deviation of particle depolarization ratio. References ---------- - Freudenthaler, V., et al., Depolarization ratio profiling at several wavelengths in pure Saharan dust during SAMUM 2006, Tellus B, 61, 165-179, 2009. Notes ----- **History** - 2021-05-31: First edition by Zhenping - 2025-02-27: Translation to python """ # Compute particle depolarization ratio par_depol = (vol_depol + 1) / (mol_bsc * (mol_depol - vol_depol) / aer_bsc / (1 + mol_depol) + 1) - 1 # Compute partial derivatives using finite differences delta_vol_depol = 0.005 delta_mol_depol = 0.0005 delta_aer_bsc = 5e-8 par_depol_vol_depol_func = lambda x: (x + 1) / (mol_bsc * (mol_depol - x) / aer_bsc / (1 + mol_depol) + 1) - 1 deriv_par_depol_vol_depol = (par_depol_vol_depol_func(vol_depol + delta_vol_depol) - par_depol_vol_depol_func(vol_depol)) / delta_vol_depol par_depol_mol_depol_func = lambda x: (vol_depol + 1) / (mol_bsc * (x - vol_depol) / aer_bsc / (1 + x) + 1) - 1 deriv_par_depol_mol_depol = (par_depol_mol_depol_func(mol_depol + delta_mol_depol) - par_depol_mol_depol_func(mol_depol)) / delta_mol_depol par_depol_aer_bsc_func = lambda x: (vol_depol + 1) / (mol_bsc * (mol_depol - vol_depol) / x / (1 + mol_depol) + 1) - 1 deriv_par_depol_aer_bsc = (par_depol_aer_bsc_func(aer_bsc + delta_aer_bsc) - par_depol_aer_bsc_func(aer_bsc)) / delta_aer_bsc # Compute standard deviation par_depol_std = np.sqrt(deriv_par_depol_vol_depol**2 * vol_depol_std**2 + deriv_par_depol_mol_depol**2 * mol_depol_std**2 + deriv_par_depol_aer_bsc**2 * aer_bsc_std**2) return par_depol, par_depol_std