ppcpy.retrievals

ppcpy.retrievals.collection

ppcpy.retrievals.collection.calc_snr(signal, bg)

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:

signalnumpy.ndarray

Signal strength.

bgnumpy.ndarray

Background noise.

Returns:

SNRnumpy.ndarray

Signal-to-noise ratio. For negative signal values, the SNR is set to 0.

Notes

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

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 retrievals, eg. ‘TCor’.

Notes

History

• xxxx-xx-xx: TODO: First edition by …

• 2026-02-09: Modified and cleaned by Buholdt

Todo

Should sigBGCor, sigTCor or RCS be used for the Klett retrievals?

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]

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

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 retrievals, eg. ‘TCor’.

Notes

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.

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 the s-shape) in the lower bins.

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]

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

History

• 2021-05-31: First edition by Zhenping

• 2025-01-05: AI supported translation

• 2026-02-04: Cleaned by Buholdt

Todo

• moving_smooth_varied_win function is not yet implemented.

• moving_linfit_varied_win function is not yet implemented.

• Investigate what smothing function is used, Savitzky-Golay or something else?

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]

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]

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.

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]

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

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, winWidth)

ppcpy.retrievals.ramanhelpers.moving_linfit_varied_win(height, signal, winWidth)

ppcpy.retrievals.ramanhelpers.movingslope(vec: ndarray, supportlength: int = 3, modelorder: int = 1, dt: float = 1) → ndarray

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

SIGGENWITHNOISE 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.ramanhelpers.savgol_filter(x: ndarray, window_length: int, polyorder: int = 2, deriv: int = 0, delta: float = 1.0, fill_val: float = nan) → ndarray

Savitzky-Golay filter

A Savitzky-Golay filter that works with NaN values.

Parameters:

xndarray

Signal to be smoothed

window_lengthint

Width of savgol filter

polyorderint, optional

The order of the polynomial used to make the filter. must be less than ‘window_length’. Default is 2.

derivint, optional

The order of the derivative to compute for the filter. Default is 0.

deltafloat, optional

The spacing of which the filter will be applied. This is only used if ‘deriv’ > 0. Defualt is 1.0.

fill_valfloat, optional

Value to be used for filling edges in order to recreate the input dimension. Default is np.nan.

Returns:

outndarray

Smoothed signal

Notes

This function is inspiered by scipy.signal’s Savitzky-Golay filter [1].

References

[1] Virtanen, et al., Scipy 1.0: Fundamental Algorithms for Scientific Computing in Python, Nature Methods, 2020, 17, 261-272, https://rdcu.be/b08Wh, 10.1038/s41592-019-0686-2 [2] A. Savitzky, M. J. E. Golay, Smoothing and Differentiation of Data by Simplified Least Squares Procedures. Analytical Chemistry, 1964, 36 (8), pp 1627-1639. [3] Jianwen Luo, Kui Ying, and Jing Bai. 2005. Savitzky-Golay smoothing and differentiation filter for even number data. Signal Process. 85, 7 (July 2005), 1429-1434.

ppcpy.retrievals.depolarization

ppcpy.retrievals.depolarization.smooth_signal(signal: ndarray, window_len: int) → ndarray

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.depolarization.voldepol_cldFreeGrps(data_cube, ret_prof_name)

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

ppcpy.retrievals.depolarization.calc_profile_vdr(sigt, sigc, Gt, Gr, Ht, Hr, eta, voldepol_error, window=1, flag_smooth_before=True)

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.

Gcfloat

G parameter in the cross channel.

Htfloat

H parameter in the total channel.

Hcfloat

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

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, vdrStd, refHInd)

get the vdr at reference height

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

ppcpy.retrievals.depolarization.pardepol_cldFreeGrps(data_cube, ret_prof_name)

ppcpy.retrievals.depolarization.calc_pdr(vol_depol, vol_depol_std, aer_bsc, aer_bsc_std, mol_bsc, mol_depol, mol_depol_std)

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

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

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

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

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 = pollyAE(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)

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.

ppcpy.retrievals.highres.voldepol_2d(data_cube)

Calculate the volume depolarisation ratio

Parameters:

data_cubeobject

Main PicassoProc object

ppcpy.retrievals.quasi

ppcpy.retrievals.quasi.quasi_pdr(data_cube, wvs=[532], version='V1')

ppcpy.retrievals.quasi.quasi_angstrom(data_cube, version='V1')

ppcpy.retrievals.quasi.target_cat(data_cube, version='V1')

ppcpy.retrievals.quasi.target_classify(height, attBeta532, quasiBsc1064, quasiBsc532, quasiPDR532, VDR532, quasiAE, **kwargs)

aerosol/cloud target classification.

Parameters:

height (ndarray): Height array (m).

attBeta532 (ndarray): Attenuated backscatter at 532 nm.

quasiBsc1064 (ndarray): Quasi particle backscatter at 1064 nm. (m^{-1}sr^{-1})

quasiBsc532 (ndarray): Quasi particle backscatter at 532 nm. (m^{-1}sr^{-1})

quasiPDR532 (ndarray): Quasi particle depolarization ratio at 532 nm.

VDR532 (ndarray): Volume depolarization ratio at 532 nm.

quasiAE (ndarray): Quasi Ångström exponents.

clearThresBsc1064 (float): Default 1e-8.

turbidThresBsc1064 (float): Default 2e-7.

turbidThresBsc532 (float): Default 2e-7.

dropletThresPDR (float): Default 0.05.

spheriodThresPDR (float): Default 0.07.

unspheroidThresPDR (float): Default 0.2.

iceThresVDR (float): Default 0.3.

iceThresPDR (float): Default 0.35.

largeThresAE (float): Default 0.75.

smallThresAE (float): Default 0.5.

cloudThresBsc1064 (float): Default 2e-5.

minAttnRatioBsc1064 (float): Default 10.

searchCloudAbove (float): Default 300.

searchCloudBelow (float): Default 100.

hFullOL (float): Default 600.

Returns:

ndarray: Classification mask.

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

References

Baars, H. et al. 2017 doi:10.5194/amt-10-3175-2017

ppcpy.retrievals.quasi.detect_liquid_bits(height, bsc1064, cloudThresBsc1064=2e-05, minAttnRatioBsc1064=10, searchCloudAbove=300, searchCloudBelow=100, **kwargs)

detect liquid cloud bits.

Parameters:

height (ndarray): Height array (m).

bsc1064 (ndarray): Particle backscatter at 1064 nm (height x time).

cloudThresBsc1064 (float, optional): Threshold of cloud backscatter at 1064 nm. Default is 2e-5.

minAttnRatioBsc1064 (float, optional): Minimum attenuation required to detect liquid cloud. Default is 10.

searchCloudAbove (float, optional): Cloud search window above current bit (m). Default is 300.

searchCloudBelow (float, optional): Cloud search window below current bit (m). Default is 100.

Returns:

ndarray: Logical mask (height x time) for detected liquid cloud regions.

Notes

History

• 2021-06-05: First edition by Zhenping

• 2025-03-25: AI based translation to python

ppcpy.retrievals.quasiV1

ppcpy.retrievals.quasiV1.quasi_bsc(data_cube)

calculate the quasi backscatter for a datacube

ppcpy.retrievals.quasiV1.quasi_retrieval(height, att_beta, molExt, molBsc, LRaer, nIters=2)

Retrieve aerosol optical properties using the quasi-retrieving method.

Parameters:

height (array):

Height in meters [m].

att_beta (ndarray):

Attenuated backscatter [m^{-1}Sr^{-1}].

molExt (ndarray):

Molecular extinction coefficient [m^{-1}].

molBsc (ndarray):

Molecular backscatter coefficient [m^{-1}Sr^{-1}].

LRaer (float):

Aerosol lidar ratio [Sr].

nIters (int, optional):

Number of iterations (default is 2).

Returns:

quasi_par_bsc (ndarray):

Quasi particle backscatter coefficient [m^{-1}Sr^{-1}].

quasi_par_ext (ndarray):

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)

ppcpy.retrievals.quasiV2.quasi_retrieval2(height, att_beta_el, att_beta_ra, wv, wv_r, molExtEl, molBscEl, molExtRa, AE, LR, nIters=1)

Retrieve aerosol optical properties using quasi retrieval method (V2), improved by utilizing Raman signals.

Parameters:

height (ndarray): Height array [m].

att_beta_el (ndarray): Attenuated backscatter at elastic wavelength [m^{-1}sr^{-1}].

att_beta_ra (ndarray): Attenuated backscatter at Raman wavelength [m^{-1}sr^{-1}].

wavelength (int): Elastic backscatter wavelength [nm].

molExtEl (ndarray): Molecular extinction coefficient at elastic wavelength [m^{-1}].

molBscEl (ndarray): Molecular backscatter coefficient at elastic wavelength [m^{-1}sr^{-1}].

molExtRa (ndarray): Molecular extinction coefficient at Raman wavelength [m^{-1}].

AE (float): Extinction-related Ångström exponent.

LR (float): Aerosol lidar ratio [sr].

nIters (int, optional): Number of iterations. Default is 1.

Returns:

quasi_par_bsc (ndarray): Quasi particle backscatter coefficient [m^{-1}sr^{-1}].

quasi_par_ext (ndarray): 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