ppcpy.retrievals#
ppcpy.retrievals.collection#
- ppcpy.retrievals.collection.calc_snr(signal: ndarray, bg: ndarray) ndarray[source]#
Calculate signal-to-noise ratio (SNR).
Todo
could have also been in helpers, but that seems more on organizing stuff… while this is an calculation, in the matlab version this function is used more than 20 times
- Parameters:
- signalndarray
Signal strength.
- bgndarray
Background noise.
- Returns:
- SNRndarray
Signal-to-noise ratio. For negative signal values the SNR is set to 0.
Notes
signal and background must be in Photon counts!
History
2021-04-21: First edition by Zhenping
2024-12-10: Translated with AI, moved to own function
References
Heese, B., Flentje, H., Althausen, D., Ansmann, A., and Frey, S.: Ceilometer lidar comparison: backscatter coefficient retrieval and signal-to-noise ratio determination, Atmospheric Measurement Techniques, 3, 1763-1770, 2010.
ppcpy.retrievals.klettfernald#
- ppcpy.retrievals.klettfernald.run_cldFreeGrps(data_cube, signal: str = 'TCor', nr: bool = False, collect_debug: bool = False) dict[source]#
Run klett retrieval for each cloud free region.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- signalstr, optional
Name of the signal to be used for the Klett retrievals. Default is ‘TCor’.
- nrbool, optional
If true, preform Klett retrieval for FR and NR channels. Otherwise only FR channels. Default is False.
- collect_debugbool, optional
If true, collect debug information. Default is True.
- Returns:
- aerExtndarray
Aerosol extinction coefficient [m^{-1}].
- aerExtStdndarray
Uncertainty of aerosol extinction coefficient [m^{-1}].
- aerBscndarray
Aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- aerBscStdndarray
Uncertainty of aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- aerBRndarray
Aerosol backscatter ratio.
- aerBRStdndarray
Statistical uncertainty of aerosol backscatter ratio.
- retrievalstr
Name of retrieval type, eg. ‘klett’.
- signalstr
Name of the signal used for the retrieval, eg. ‘TCor’.
- refBetafloat
Reference value used for the retrieval [m^{-1}Sr^{-1}].
Notes
Todo
Should sigBGCor, sigTCor or RCS be used for the Klett retrievals?
History
xxxx-xx-xx: TODO: First edition by …
2026-02-09: Modified and cleaned by Buholdt
- ppcpy.retrievals.klettfernald.fernald(height: ndarray, signal: ndarray, bg: ndarray, LR_aer: float | ndarray, refHInd: list, refBeta: float, molBsc: ndarray, window_size: int = 40, collect_debug: bool = False) dict[str, ndarray][source]#
Retrieve aerosol backscatter coefficient using the Fernald method.
- Parameters:
- heightarray_like
Height in meters.
- signalarray_like
Elastic signal without background (Photon Count).
- bgarray_like
Background signal (Photon Count).
- LR_aerfloat or array_like
Aerosol lidar ratio [sr].
- refHIndarray_like
Reference height index [start, end].
- refBetafloat
Aerosol backscatter coefficient at the reference region [m^-1 sr^-1].
- molBscarray_like
Molecular backscatter coefficient [m^-1 sr^-1].
- window_sizeint, optional
Bins of the smoothing window for the signal. Default is 40 bins.
- Returns:
- aerBscndarray
Aerosol backscatter coefficient [m^-1 sr^-1].
- aerBscStdndarray
Statistical uncertainty of aerosol backscatter [m^-1 sr^-1].
- aerBRndarray
Aerosol backscatter ratio.
- aerBRStdndarray
Statistical uncertainty of aerosol backscatter ratio.
Notes
Temporarily using scipy.ndimage.uniform_filter1d for the smoothing of the RCS instead of ppcpy.misc.helper.uniform_filter due to some rear but strange issue with propagating NaN-values in the backwards and forwards retrieval methods. This issue has so far only been observed at the 355 total NR channel at certain cloud free periods. ppcpy.misc.helper.uniform_filter is generally preferred over scipy.ndimage.uniform_filter1d when some few NaN-values at the edges do not cause issues, as should be the case here. Further investigation into this issue is needed to understand what is causing the NaN-values.
Todo
Define m (Unsure if this m addition is needed).
History
2021-05-30: First edition by Zhenping.
2025-01-03: AI Translation
2026-02-04: Changed from scipy.ndimage.uniform_filter1d to ppcpy.misc.helper.uniform_filter
- 2026-02-10: Reverted to using scipy.ndimage.uniform_filter1d due to occational issue with
propagating NaN-values in the backward and farward retrievals.
References
Fernald, F. G.: Analysis of atmospheric lidar observations: some comments, Appl. Opt., 23, 652-653, 10.1364/AO.23.000652, 1984.
ppcpy.retrievals.raman#
- ppcpy.retrievals.raman.run_cldFreeGrps(data_cube, signal: str = 'TCor', heightFullOverlap: list = None, nr: bool = False, collect_debug: bool = False) dict[source]#
Run raman retrieval for each cloud free region.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- signalstr, optional
Name of the signal to be used for the Raman retrievals. Default is ‘TCor’.
- heightFullOverlaplist, optional
List with heights of full overlap per channel per cloud free region. Default is None.
- nrbool, optional
If true, preform Raman retrieval for FR and NR channels. Otherwise only FR channels. Default is False.
- collect_debugbool, optional
If true, collect debug information. Default is True.
- Returns:
- aerExtndarray
Aerosol extinction coefficient [m^{-1}].
- aerExtStdndarray
Uncertainty of aerosol extinction coefficient [m^{-1}].
- aerBscndarray
Aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- aerBscStdndarray
Uncertainty of aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- LRndarray
Aerosol Lidar ratio [sr].
- effResndarray
Effective resolution of aerosol lidar ratio [m].
- LRStdndarray
Uncertainty of aerosol lidar ratio [sr].
- retrievalstr
Name of retrieval type eg. ‘raman’.
- signalstr
Name of the signal used for the retrieval eg. ‘TCor’.
- refBetafloat
Reference value used for the retrieval.
Notes
Todo
sigma_angstroem and MC_count are hardcoded. Can this be automated?
in raman_ext calulations we use a different hard coded MC_count than the global parameter.
Should sigBGCor, sigTCor or RCS be used for the Raman retrievals? RCS dampens the effect form the wrong first bin and makes the profile more straight, insted of s-shaped, in the lower bins.
use flag367Off and flag607Off to give warnings or error if the channels are on less then X%of the time during a cloud free segment.
Add flag for nighttime measurements.
History
xxxx-xx-xx: TODO: First edition by …
2026-02-04: Modified and cleaned by Buholdt
2026-02-27: Added ext_aer_mod and ext_mol_mod to backscatter calculations.
- ppcpy.retrievals.raman.raman_ext(height: ndarray, sig: ndarray, lambda_emit: float, lambda_Raman: float, alpha_molecular_elastic: ndarray | list, alpha_molecular_Raman: ndarray | list, number_density: ndarray, angstrom: float, window_size: int, method: str = 'movingslope', MC_count: int = 1, bg: float = 0) dict[str, ndarray][source]#
Retrieve the aerosol extinction coefficient with the Raman method.
- Parameters:
- heightarray_like
Height [m].
- sigarray_like
Measured Raman signal [Photon Count].
- lambda_emitfloat
Wavelength of the emitted laser beam [nm].
- lambda_Ramanfloat
Wavelength of Raman signal [nm].
- alpha_molecular_elasticarray_like
Molecular scattering coefficient at emitted wavelength [m^{-1} sr^{-1}].
- alpha_molecular_Ramanarray_like
Molecular scattering coefficient at Raman wavelength [m^{-1} sr^{-1}].
- number_densityarray_like
Molecular number density.
- angstromfloat
Angstrom exponent for aerosol extinction coefficient.
- window_sizeint
Window size for smoothing the signal using Savitzky-Golay filter.
- methodstr, optional
Method to calculate the slope of the signal. Choices: ‘movingslope’, ‘smoothing’, ‘chi2’. Default is ‘movingslope’.
- MC_countint, optional
Number of Monte Carlo iterations. Default is 1.
- bgfloat, optional
Background signal [Photon Count]. Default is 0.
- Returns:
- ext_aerndarray
Aerosol extinction coefficient [m^-1].
- ext_errorndarray
Error in aerosol extinction coefficient [m^-1] (only calculated for MC_count > 1).
Notes
Todo
moving_smooth_varied_win and moving_linfit_varied_win functions are not yet implemented. Investigate what smothing function is used, Savitzky-Golay or something else?
History
2021-05-31: First edition by Zhenping
2025-01-05: AI supported translation
2026-02-04: Cleaned by Buholdt
2026-08-25: Added devision by height resolution in error calculations
References
Ansmann, A. et al. Independent measurement of extinction and backscatter profiles in cirrus clouds by using a combined Raman elastic-backscatter lidar. Applied Optics Vol. 31, Issue 33, pp. 7113-7131 (1992).
- ppcpy.retrievals.raman.raman_bsc(height: ndarray, sigElastic: ndarray, sigVRN2: ndarray, ext_aer: ndarray, angstroem: ndarray, ext_mol: ndarray, beta_mol: ndarray, ext_mol_raman: ndarray, beta_mol_raman: ndarray, HRefInd: list | tuple, betaRef: float, el_lambda: float, inel_lambda: float, ext_aer_el_raman: ndarray = None, ext_mol_el_raman: ndarray = None, window_size: int = 40, flagSmoothBefore: bool = True, bgElastic: ndarray = None, bgVRN2: ndarray = None, sigma_ext_aer: ndarray = None, sigma_angstroem: ndarray = None, MC_count: int | list = 3, method: str = 'monte-carlo', collect_debug: bool = False) dict[str, ndarray][source]#
Calculate aerosol backscatter coefficient and its uncertainty.
- Parameters:
- heightndarray
Height [m].
- sigElasticndarray
Elastic signal [photon count].
- sigVRN2ndarray
N2 vibration rotational Raman signal [photon count].
- ext_aerndarray
Aerosol extinction coefficient for elastic wavelength [m^{-1}].
- angstroemndarray
Aerosol Angstrom exponent.
- ext_molndarray
Molecular extinction coefficient for elastic wavelength [m^{-1}].
- beta_molndarray
Molecular backscatter coefficient for elastic wavelength [m^{-1}Sr^{-1}].
- ext_mol_ramanndarray
Molecular extinction coefficient for inelastic Raman wavelength [m^{-1}].
- beta_mol_raman :ndarray
Molecular backscatter coefficient for inelastic Raman wavelength [m^{-1}Sr^{-1}].
- HRefIndlist or tuple
Reference region indices of height array [start, end].
- betaReffloat
Aerosol backscatter coefficient for elastic wavelength at the reference region [m^{-1}Sr^{-1}].
- el_lambdafloat
Elastic wavelength [nm].
- inel_lambdafloat
Inelastic wavelength [nm].
- ext_aer_el_ramanndarray, optional
Aerosol extinction coefficient for elastic wavelength that initializes the Raman retrieval [m^{-1}]. Default is None.
- ext_mol_el_ramanndarray, optional
Molecular extinction coefficient for elastic wavelength that initializes the Raman retrieval [m^{-1}]. Default is None.
- window_sizeint, optional
Number of smoothing bins to be used. Default is 40.
- flagSmoothBeforebool, optional
Flag to control the smoothing order. Default is True.
- bgElasticndarray, optional
Background of elastic signal [photon count].
- bgVRN2ndarray, optional
Background of N2 vibration rotational signal [photon count].
- sigma_ext_aerndarray, optional
Uncertainty of aerosol extinction coefficient for elastic wavelength [m^{-1}].
- sigma_angstroemndarray, optional
Uncertainty of Angstrom exponent.
- MC_countint or list, optional
Samples for each error source. Default is 3.
- methodstr, optional
Computational method (‘monte-carlo’ or ‘analytical’). Default is ‘monte-carlo’.
- collect_debugbool, optional
If True, collectes debug information. Default is False.
- Returns:
- beta_aerndarray
Aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- aerBscStdndarray
Uncertainty of aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- LRndarray
Aerosol Lidar ratio [sr].
Notes
History
xxxx-xx-xx: First edition by …
2026-02-04: Cleaned by Buholdt.
2026-02-27: Added ext_aer_mod and ext_mol_mod for better consistancy with the 1064nm channel.
- ppcpy.retrievals.raman.calc_raman_bsc(height: ndarray, sigElastic: ndarray, sigVRN2: ndarray, ext_aer: ndarray, angstroem: ndarray, ext_mol: ndarray, beta_mol: ndarray, ext_mol_raman: ndarray, beta_mol_raman: ndarray, HRefInd: list, betaRef: float, el_lambda: float, inel_lambda: float, ext_mol_el_raman: ndarray = None, ext_aer_el_raman: ndarray = None, window_size: int = 40, flagSmoothBefore: bool = True) tuple[ndarray, ndarray, list, ndarray][source]#
Calculate the aerosol backscatter coefficient with the Raman method.
- Parameters:
- heightarray
Height [m].
- sigElasticarray
Elastic signal [photon count].
- sigVRN2array
N2 vibration rotational Raman signal [photon count].
- ext_aerarray
Aerosol extinction coefficient for elastic wavelength [m^{-1}].
- angstroemarray
Aerosol Angstrom exponent.
- ext_molarray
Molecular extinction coefficient for elastic wavelength [m^{-1}].
- beta_molarray
Molecular backscatter coefficient for elastic wavelength [m^{-1}Sr^{-1}].
- ext_mol_ramanarray
Molecular extinction coefficient for inelastic Raman wavelength [m^{-1}].
- beta_mol_ramanarray
Molecular backscatter coefficient for inelastic Raman wavelength [m^{-1}Sr^{-1}].
- HRefIndlist
Reference region indices of height array [start, end].
- betaReffloat
Aerosol backscatter coefficient for elastic wavelength at the reference region [m^{-1}Sr^{-1}].
- el_lambdafloat
Elastic wavelength [nm].
- inel_lambdafloat
Inelastic Raman wavelength [nm].
- ext_aer_el_ramanarray, optional
Aerosol extinction coefficient for elastic wavelength that initializes the Raman retrieval [m^{-1}]. Default is None.
- ext_mol_el_ramanarray, optional
Molecular extinction coefficient for elastic wavelength that initializes the Raman retrieval [m^{-1}]. Default is None.
- window_sizeint, optional
Number of smoothing bins to be used. Default is 40.
- flagSmoothBeforebool, optional
Whether to smooth the signal before or after calculating the signal ratio. Default is True.
- Returns:
- beta_aerarray
Aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- LRarray
Aerosol lidar ratio [sr].
Notes
Todo
Angstroem is an float in beta_aer calculations and an array of shape (1, ) in beta_aer_std claculations.
History
2018-01-02: First edition by Zhenping.
2018-07-24: Added ext_mol_factor and ext_aer_factor for wavelength of 1064nm.
2018-09-04: Changed smoothing order for signal ridge stability.
2024-11-12: Modified by HB for consistency in 2024.
2026-02-04: Cleaned by Buholdt
2026-02-27: Added ext_aer_el_raman and ext_mol_el_raman for better consistancy with the 1064nm channel.
2026-07-28: Added dependencies on mask387Off and mask607Off.
References
Ansmann, A., et al. (1992). “Independent measurement of extinction and backscatter profiles in cirrus clouds by using a combined Raman elastic-backscatter lidar.” Applied optics 31(33): 7113-7131.
- ppcpy.retrievals.raman.lidarratio(aerExt: ndarray, aerBsc: ndarray, hRes: float = 7.5, aerExtStd: ndarray = None, aerBscStd: ndarray = None, smoothWinExt: int = 1, smoothWinBsc: int = 1) dict[ndarray, float][source]#
Calculate aerosol lidar ratio.
- Parameters:
- aerExtndarray
Aerosol extinction coefficient [m^{-1}].
- aerBscndarray
Aerosol backscatter coefficient [m^{-1}sr^{-1}].
- hResfloat, optional
Vertical resolution of each height bin [m]. Default is 7.5.
- aerExtStdndarray, optional
Uncertainty of aerosol extinction coefficient [m^{-1}].
- aerBscStdndarray, optional
Uncertainty of aerosol backscatter coefficient [m^{-1}sr^{-1}].
- smoothWinExtint, optional
Applied smooth window length for calculating aerosol extinction coefficient. Default is 1.
- smoothWinBscint, optional
Applied smooth window length for calculating aerosol backscatter coefficient. Default is 1.
- Returns:
- aerLRndarray
Aerosol lidar ratio [sr].
- effResfloat
Effective resolution of lidar ratio [m].
- aerLRStdndarray
Uncertainty of aerosol lidar ratio [sr].
Notes
Though savgol_filter with mode ‘interp’ do not apply padding on the edges while smoothing it does preform an interpolation to add in the edges removed by the smoothing/convolution operation.
History
2021-07-20: First edition by Zhenping (translated to Python)
2026-02-04: Changed from scipy.signal.savgol_filter to ppcpy.retrievals.ramanhelpers.savgol_filter
References
Mattis, I., D’Amico, G., Baars, H., Amodeo, A., Madonna, F., and Iarlori, M.: EARLINET Single Calculus Chain–technical–Part 2: Calculation of optical products, Atmospheric Measurement Techniques, 9, 3009-3029, 2016.
ppcpy.retrievals.ramanhelpers#
- ppcpy.retrievals.ramanhelpers.movingslope_variedWin(signal: ndarray, winWidth: int | ndarray) ndarray[source]#
Calculates the slope of the signal with a moving slope.
This is a wrapper for the movingslope function to make it compatible with height-independent smoothing windows.
- Parameters:
- signalarray_like
Signal for each bin.
- winWidthint or ndarray
If winWidth is an integer, the width of the window will be fixed. If winWidth is a k x 3 matrix, the width of the window will vary with height, like [[1, 20, 3], [18, 30, 5], [25, 40, 7]], which means: - The width will be 3 between indices 1 and 20, - 5 between indices 18 and 30, - and 7 between indices 25 and 40.
- Returns:
- slopendarray
Slope at each bin.
Notes
History
2018-08-03: First edition by Zhenping.
- ppcpy.retrievals.ramanhelpers.moving_smooth_varied_win(signal: ndarray, winWidth: int | ndarray) ndarray[source]#
Todo
Implement function!
- ppcpy.retrievals.ramanhelpers.moving_linfit_varied_win(height: ndarray, signal: ndarray, winWidth: int | ndarray) ndarray[source]#
Todo
Implement function!
- ppcpy.retrievals.ramanhelpers.movingslope(vec: ndarray, supportlength: int = 3, modelorder: int = 1, dt: float = 1) ndarray[source]#
Estimates the local slope of a sequence of points using a sliding window.
- Parameters:
- vecarray_like
Row or column vector to be differentiated. Must have at least 2 elements.
- supportlengthint, optional
Number of points used for the moving window. Default is 3.
- modelorderint, optional
Defines the order of the windowed model used to estimate the slope. Default is 1 (linear model).
- dtfloat, optional
Spacing for sequences that do not have unit spacing. Default is 1.
- Returns:
- Dvecndarray
Derivative estimates, same size and shape as vec.
Notes
History
Original MATLAB implementation by John D’Errico (woodchips@rochester.rr.com)
- ppcpy.retrievals.ramanhelpers.sigGenWithNoise(signal: ndarray, noise: ndarray = None, nProfile: int = 1, method: str = 'norm') ndarray[source]#
Generate noise-containing signal with a certain noise-adding algorithm.
- Parameters:
- signalarray
Signal strength.
- noisearray, optional
Noise. Unit should be the same as signal. Default is sqrt(signal).
- nProfileint, optional
Number of signal profiles to generate. Default is 1.
- methodstr, optional
‘norm’: Normally distributed noise -> signalGen = signal + norm * noise. ‘poisson’: Poisson distributed noise -> signalGen = poisson(signal, nProfile). Default is ‘norm’.
- Returns:
- signalGenarray
Noise-containing signal. Shape is (len(signal), nProfile).
Notes
History
2021-06-13: First edition by Zhenping.
2026-02-04: Modifications to reduce computational time, Buholdt
ppcpy.retrievals.depolarization#
- ppcpy.retrievals.depolarization.smooth_signal(signal: ndarray, window_len: int) ndarray[source]#
Uniformly smooth the input signal
- Parameters:
- singalndarray
Signal to be smooth
- window_lenint
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
- ppcpy.retrievals.depolarization.voldepol_cldFreeGrps(data_cube, ret_prof_name: str) dict[source]#
…
- Parameters:
- ret_prof_namestr
…
- Returns:
- opt_profilesdict
…
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??
- ppcpy.retrievals.depolarization.calc_profile_vdr(sigt: ndarray, sigc: ndarray, Gt: float, Gr: float, Ht: float, Hr: float, eta: float, voldepol_error: float, window: int = 1, flag_smooth_before: bool = True) tuple[source]#
Calculate volume depolarization ratio using GHK parameters.
- Parameters:
- sigtndarray
Signal strength of the total channel [photon count].
- sigcndarray
Signal strength of the cross channel [photon count].
- Gtfloat
G parameter in the total channel.
- Grfloat
G parameter in the cross channel.
- Htfloat
H parameter in the total channel.
- Hrfloat
H parameter in the cross channel.
- etafloat
Depolarization calibration constant.
- voldepol_errorfloat
Systematic uncertainty coefficient (constant term). Systematic uncertainty coefficient (linear term). Systematic uncertainty coefficient (quadratic term).
- smooth_windowint, optional
The width of the sliding smoothing window for the signal. Default is 1.
- flag_smooth_beforebool, optional
Flag to control whether smoothing is applied before or after the signal ratio. Default is True.
- Returns:
- vol_depolndarray
Volume depolarization ratio.
- vol_depol_stdndarray
Uncertainty of the volume depolarization ratio.
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.
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).
- ppcpy.retrievals.depolarization.get_MDR(vdr: ndarray, vdrStd: ndarray, refHInd: list) float[source]#
Get the vdr at reference height.
- Parameters:
- vdrndarray
Volume depolarization ratio.
- vdrStdndarray
Uncertainty of the volume depolarization ratio.
- refHIndlist
Reference height indcies [bottum, top].
- Returns:
- mdrndarray
Mean volume depolarization ratio at reference height.
- mdrStdndarray
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 **
- ppcpy.retrievals.depolarization.pardepol_cldFreeGrps(data_cube, ret_prof_name: str) dict[source]#
…
- Parameters:
- data_cubeobject
Main PicassoProc object.
- ret_prof_namestr
…
- Returns:
- opt_porfilesdict
…
Notes
Todo
Finish docsting.
Is the return here necessary?
Cleare unused variables.
- ppcpy.retrievals.depolarization.calc_pdr(vol_depol: ndarray, vol_depol_std: ndarray, aer_bsc: ndarray, aer_bsc_std: ndarray, mol_bsc: ndarray, mol_depol: float, mol_depol_std: float) tuple[source]#
Calculate the particle depolarization ratio and estimate its standard deviation.
- Parameters:
- vol_depolndarray
Volume depolarization ratio.
- vol_depol_stdndarray
Standard deviation of volume depolarization ratio.
- aer_bscndarray
Aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- aer_bsc_stdndarray
Standard deviation of aerosol backscatter coefficient [m^{-1}Sr^{-1}].
- mol_bscndarray
Molecule backscatter coefficient [m^{-1}Sr^{-1}].
- mol_depolfloat
Molecule depolarization ratio, dependent on central wavelength and IF bandwidth.
- mol_depol_stdfloat
Standard deviation of molecule depolarization ratio.
- Returns:
- par_depolndarray
Particle depolarization ratio.
- par_depol_stdndarray
Standard deviation of particle depolarization ratio.
Notes
History
2021-05-31: First edition by Zhenping
2025-02-27: Translation to python
References
Freudenthaler, V., et al., Depolarization ratio profiling at several wavelengths in pure Saharan dust during SAMUM 2006, Tellus B, 61, 165-179, 2009.
ppcpy.retrievals.angstroem#
- ppcpy.retrievals.angstroem.smooth_signal(signal: ndarray, window_len: int) ndarray[source]#
Uniformly smooth the input signal.
- Parameters:
- singalndarray
Signal to be smooth.
- window_lenint
Width of the applied uniform filter.
- Returns:
- ndarray
Smoothed signal.
Notes
History
2026-02-04: Changed from scipy.ndimage.uniform_filter1d to ppcpy.misc.helper.uniform_filter.
- ppcpy.retrievals.angstroem.ae_cldFreeGrps(data_cube, ret_prof_name: str, collect_debug: bool = False) dict[source]#
Run Angstroem retrieval for each cloud free region.
Convention for now to store the AE in the channel of the lower of the two wavelengths
- Parameters:
- data_cubeobject
Main PicassoProc object.
- ret_prof_namestr
Name of optical retrieval profile.
- collect_debugbool, optional
If true, collects debug information. Default is False.
- Returns:
- angexparray
Ångström exponent based on param1 and param2.
- angexpStdarray
Uncertainty of Ångström exponent.
Notes
History
xxxx-xx-xx: TODO: First edition by …
- 2026-02-20: Smoothing window changes. Now determines the smoothing window based on
the higher of the two wavelengths, and discriminates between FR and NR.
- ppcpy.retrievals.angstroem.calc_ae(param1: ndarray, param1_std: ndarray, param2: ndarray, param2_std: ndarray, wavelength1: float, wavelength2: float, smooth_window: int = 17) tuple[source]#
Calculates the Ångström exponent and its uncertainty.
- Parameters:
- param1array
Extinction or backscatter coefficient at wavelength1.
- param1_stdarray
Uncertainty of param1.
- param2array
Extinction or backscatter coefficient at wavelength2.
- param2_stdarray
Uncertainty of param2.
- wavelength1float
The wavelength for the input parameter 1 [nm].
- wavelength2float
The wavelength for the input parameter 2 [nm].
- smooth_windowint, optional
The width of the smoothing window. Default is 17.
- Returns:
- angexparray
Ångström exponent based on param1 and param2.
- angexpStdarray
Uncertainty of Ångström exponent.
Notes
Todo
Should the ratio be smoothed or not?? If we do not smooth the ratio then why are we
considering the smoothing window in the error calculations??
History
2021-05-31: first edition by Zhenping
Examples
angexp, angexpStd = calc_ae(param1, param1_std, param2, param2_std, wavelength1, wavelength2)
ppcpy.retrievals.highres#
- ppcpy.retrievals.highres.attbsc_2d(data_cube, nr: bool = True, collect_debug: bool = False)[source]#
Attenuated Backscatter.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- nrbool, optional
If Ture, calculate the attbsc for FR and NR channels. Default is True.
- collect_debugbool, optional
If True, collects debug information. Default is False.
- Attributes:
- data_cube.retrievals_highres[f”attBsc_{channel}”]ndarray
Time-height attenuated backscatter per channel.
Notes
If ´nr=True´ also yeild the attenuated backscatter of the near-range channels.
In addition to the standard far-range channels the function also yeilds the attenuated backscatter of the overlap corrected far-range channels.
- ..TODO:: is it correct to transmission correct the overlap corrected signals
before calculating their attenuated backscatter? Are not the OL signals already transmission corrected?
- ppcpy.retrievals.highres.voldepol_2d(data_cube)[source]#
Calculate the volume depolarisation ratio.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- Attributes:
- data_cube.retrievals_highres[f”voldepol_{wv}_total_{tel}”]ndarray
Time-hight volume depolarization ratio at wavelengths 353 nm, 532 nm, 1064 nm, and 532 nm DFOV.
- ppcpy.retrievals.highres.wvmr_2d(data_cube)[source]#
Water Vapor Mixing Ratio.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- Attributes:
- data_cube.retrievals_highres[f”wvmr_407_FR”]ndarray
Time-height water vapor mixing ratio at 407 nm FR.
Notes
Todo
Save highres wvmr data to .nc file
History
2026-09-11: First edition by Jakob
ppcpy.retrievals.quasi#
- ppcpy.retrievals.quasi.quasi_pdr(data_cube, wvs: list = [532], version: str = 'V1')[source]#
High resolution particle and volume depolarization ratio.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- wvslist, optional
Wavelengths to do the retrieval for. Default is [521].
- versionstr, optional
Name of qusi version (‘V1’ or ‘V2’). Default is ‘V1’.
Notes
** History **
xxxx-xx-xx: First edition by …
xxxx-xx-xx: AI based translation to python
2026-05-27: Added flag to use only valid data
- ppcpy.retrievals.quasi.quasi_angstrom(data_cube, version: str = 'V1')[source]#
High resolution Ångström ratios.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- versionstr, optional
Name of qusi version (‘V1’ or ‘V2’). Default is ‘V1’.
Notes
** History **
xxxx-xx-xx: First edition by …
xxxx-xx-xx: AI based translation to python
2026-05-21: Fixed calculation
- ppcpy.retrievals.quasi.target_cat(data_cube, version: str = 'V1')[source]#
Run target categorization.
- Parameters:
- data_cubeobject
Main PicassoProc object.
- versionstr, optional
Name of qusi version (‘V1’ or ‘V2’). Default is ‘V1’.
Notes
** History **
xxxx-xx-xx: First edition by …
xxxx-xx-xx: AI based translation to python
2026-05-21: Added dependency on Quality mask
- ppcpy.retrievals.quasi.target_classify(height: ndarray, attBeta532: ndarray, quasiBsc1064: ndarray, quasiBsc532: ndarray, quasiPDR532: ndarray, VDR532: ndarray, quasiAE: ndarray, **kwargs: dict) ndarray[source]#
Aerosol & cloud target classification.
- Parameters:
- heightndarray
Height array [m].
- attBeta532ndarray
Attenuated backscatter at 532 nm (time x height).
- quasiBsc1064ndarray
Quasi particle backscatter at 1064 nm (time x height) [m^{-1}sr^{-1}].
- quasiBsc532ndarray
Quasi particle backscatter at 532 nm (time x height) [m^{-1}sr^{-1}].
- quasiPDR532ndarray
Quasi particle depolarization ratio at 532 nm (time x height).
- VDR532ndarray
Volume depolarization ratio at 532 nm (time x height).
- quasiAEndarray
Quasi Ångström exponents 532nm-1064nm (time x height).
- kwargsdict, optional
- clearThresBsc1064float
Threshold for discriminating clear atmosphere based on particle backscatter at 1064nm [m^{-1}]. Default 1e-8.
- turbidThresBsc1064float
Threshold for discriminating turbid atmosphere based on particle backscatter at 1064nm [m^{-1}]. Default 2e-7.
- turbidThresBsc532float
Threshold for discriminating turbid atmosphere based on particle backscatter at 532nm [m^{-1}]. Default 2e-7.
- dropletThresPDRfloat
Threshold for discriminating cloud droplets based on particle depolarization ratio at 532nm. Default 0.05.
- spheriodThresPDRfloat
Threshold for discriminating spheriod paricles based on particle depolarization ratio at 532nm. Default 0.07.
- unspheroidThresPDRfloat
Threshold for discriminating unspheriod paricles based on particle depolarization ratio at 532nm. Default 0.2.
- iceThresVDRfloat
Threshold for discriminating ice crystals based on volume depolarization ratio at 532nm. Default 0.3.
- iceThresPDRfloat
Threshold for discriminating ice crystals based on particle depolarization ratio at 532nm. Default 0.35.
- largeThresAEfloat
Threshold for discriminating large particles based on angstroem exponent. Default 0.75.
- smallThresAEfloat
Threshold for discriminating small particles based on angstroem exponent. Default 0.5.
- cloudThresBsc1064float
Threshold for discriminating cloud layers based on quasi particle backscatter at 1064nm [m^{-1}]. Default 2e-5.
- minAttnRatioBsc1064float
Mminimum attenuation factor which could be expected at the first 250m penatration depth. Default 10.
- searchCloudAbovefloat
Parameter used in cloud top detection. The cloud top will be searched between the first bin with quasi particle backscatter at 1064nm larger than cloud_thres_par_beta_1064 and + search_height_above [m]. Default 300.
- searchCloudBelowfloat
Parameter used in cloud base detection. The cloud base will be searched between the first bin with quasi particle backscatter at 1064nm larger than cloud_thres_par_beta_1064 and - search_height_below [m]. Default 100.
- hFullOLfloat
Height full overlap [m] Default 600.
- Returns:
- tc_maskndarray
- Classification mask (time x height).
0: No signal 1: Clean atmosphere 2: Non-typed particles/low conc. 3: Aerosol: small 4: Aerosol: large, spherical 5: Aerosol: mixture, partly non-spherical 6: Aerosol: large, non-spherical 7: Cloud: non-typed 8: Cloud: water droplets 9: Cloud: likely water droplets 10: Cloud: ice crystals 11: Cloud: likely ice crystal
Notes
History
2021-06-05: First edition by Zhenping
2025-03-25: AI based translation to python
2026-05-21: Fixed dimension issue
References
Baars, H. et al. 2017 doi:10.5194/amt-10-3175-2017
- ppcpy.retrievals.quasi.detect_liquid_bits(height: ndarray, bsc1064: ndarray, cloudThresBsc1064: float = 2e-05, minAttnRatioBsc1064: float = 10, searchCloudAbove: float = 300, searchCloudBelow: float = 100) ndarray[source]#
Detect liquid cloud bits.
- Parameters:
- heightndarray
Height array [m].
- bsc1064ndarray
Particle backscatter at 1064 nm (time x height).
- cloudThresBsc1064float, optional
Threshold of cloud backscatter at 1064 nm. Default is 2e-5.
- minAttnRatioBsc1064float, optional
Minimum attenuation required to detect liquid cloud. Default is 10.
- searchCloudAbovefloat, optional
Cloud search window above current bit [m]. Default is 300.
- searchCloudBelowfloat, optional
Cloud search window below current bit [m]. Default is 100.
- Returns:
- falgLiquidndarray
Boolean mask (time x height) for detected liquid cloud regions.
Notes
Warning: Still under testing!
Todo
Are the indices correctlly translated from matlab?
History
2021-06-05: First edition by Zhenping
2025-03-25: AI based translation to python
2026-05-21: Fixed dimension issue
ppcpy.retrievals.quasiV1#
- ppcpy.retrievals.quasiV1.quasi_bsc(data_cube)[source]#
Run Quasi Backscatter retrieval Version 1.
- Parameters:
- data_cubeobject
Main PicassoProc object.
Notes
** History **
xxxx-xx-xx: First edition by …
xxxx-xx-xx: AI based translation to python
- ppcpy.retrievals.quasiV1.quasi_retrieval(height: ndarray, att_beta: ndarray, molExt: ndarray, molBsc: ndarray, LRaer: float, nIters: int = 2) tuple[source]#
Retrieve aerosol optical properties using the quasi-retrieving method.
- Parameters:
- heightndarray
Height [m].
- att_betandarray
Attenuated backscatter [m^{-1}Sr^{-1}].
- molExtndarray
Molecular extinction coefficient [m^{-1}].
- molBscndarray
Molecular backscatter coefficient [m^{-1}Sr^{-1}].
- LRaerfloat
Aerosol lidar ratio [Sr].
- nItersint, optional
Number of iterations. Default is 2.
- Returns:
- quasi_par_bscndarray
Quasi particle backscatter coefficient [m^{-1}Sr^{-1}].
- quasi_par_extndarray
Quasi particle extinction coefficient [m^{-1}].
Notes
History
2018-12-25: First edition by Zhenping
2019-03-31: Added the keyword ‘nIters’ to control iteration times.
2025-03-21: AI based translation to python and debugging
References
Baars, H. et al. 2017 doi:10.5194/amt-10-3175-2017
ppcpy.retrievals.quasiV2#
- ppcpy.retrievals.quasiV2.quasi_bsc(data_cube)[source]#
Run Quasi Backscatter retrieval Version 2.
- Parameters:
- data_cubeobject
Main PicassoProc object.
Notes
** History **
xxxx-xx-xx: First edition by …
xxxx-xx-xx: AI based translation to python
- ppcpy.retrievals.quasiV2.quasi_retrieval2(height: ndarray, att_beta_el: ndarray, att_beta_ra: ndarray, wv: float, wv_r: float, molExtEl: ndarray, molBscEl: ndarray, molExtRa: ndarray, AE: float, LR: float, nIters: int = 1) tuple[source]#
Retrieve aerosol optical properties using quasi retrieval method (V2), improved by utilizing Raman signals.
- Parameters:
- heightndarray
Height array [m].
- att_beta_elndarray
Attenuated backscatter at elastic wavelength [m^{-1}sr^{-1}].
- att_beta_randarray
Attenuated backscatter at Raman wavelength [m^{-1}sr^{-1}].
- wvfloat
Elastic backscatter wavelength [nm].
- wv_rfloat
Raman backscatter wavelength [nm].
- molExtElndarray
Molecular extinction coefficient at elastic wavelength [m^{-1}].
- molBscElndarray
Molecular backscatter coefficient at elastic wavelength [m^{-1}sr^{-1}].
- molExtRandarray
Molecular extinction coefficient at Raman wavelength [m^{-1}].
- AEfloat
Extinction-related Ångström exponent.
- LRfloat
Aerosol lidar ratio [sr].
- nItersint, optional
Number of iterations. Default is 1.
- Returns:
- quasi_par_bscndarray
Quasi particle backscatter coefficient [m^{-1}sr^{-1}].
- quasi_par_extndarray
Quasi particle extinction coefficient [m^{-1}].
Notes
History
2021-06-07: first edition by Zhenping
2025-03-30: AI translation to python
References
Baars et al., 2017 doi:10.5194/amt-10-3175-2017