ppcpy.retrievals.raman#

Functions

calc_raman_bsc

Calculate the aerosol backscatter coefficient with the Raman method.

lidarratio

Calculate aerosol lidar ratio.

raman_bsc

Calculate uncertainty of aerosol backscatter coefficient with Monte-Carlo simulation.

raman_ext

Retrieve the aerosol extinction coefficient with the Raman method.

run_cldFreeGrps

Run raman retrieval for each cloud free region.

smoothWin

Smooth signal with a height-dependent window.
ppcpy.retrievals.raman.run_cldFreeGrps(data_cube, signal: str = 'TCor', heightFullOverlap: list = None, nr: bool = False, collect_debug: bool = True) → dict[source]#

Run raman retrieval for each cloud free region.

Parameters:

  • data_cube (object) – Main PicassoProc object.

  • signal (str, optional) – Name of the signal to be used for the Raman retrievals. Default is ‘TCor’.

  • heightFullOverlap (list, optional) – List with heights of full overlap per channel per cloud free region. Default is None.

  • nr (bool, optional) – If true, preform Raman retrieval for FR and NR channels. Otherwise only FR channels. Default is False.

  • collect_debug (bool, optional) – If true, collect debug information. Default is True.

Returns:

  • aerExt (ndarray) – Aerosol extinction coefficient [m^{-1}].

  • aerExtStd (ndarray) – Uncertainty of aerosol extinction coefficient [m^{-1}].

  • aerBsc (ndarray) – Aerosol backscatter coefficient [m^{-1}Sr^{-1}].

  • aerBscStd (ndarray) – Uncertainty of aerosol backscatter coefficient [m^{-1}Sr^{-1}].

  • LR (ndarray) – Aerosol Lidar ratio [sr].

  • effRes (ndarray) – Effective resolution of aerosol lidar ratio [m].

  • LRStd (ndarray) – Uncertainty of aerosol lidar ratio [sr].

  • retrieval (str) – Name of retrieval type eg. ‘raman’.

  • signal (str) – Name of the signal used for the retrievals, eg. ‘TCor’.

  • History

  • ——-

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

  • - 2026-02-04 (Modified and cleaned by Buholdt)

  • TODO’s

  • ——

  • - 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][source]#

Retrieve the aerosol extinction coefficient with the Raman method.

Parameters:

  • height (array_like) – Height [m].

  • sig (array_like) – Measured Raman signal. Unit: Photon Count.

  • lambda_emit (float) – Wavelength of the emitted laser beam [nm].

  • lambda_Raman (float) – Wavelength of Raman signal [nm].

  • alpha_molecular_elastic (array_like) – Molecular scattering coefficient at emitted wavelength [m^{-1} sr^{-1}].

  • alpha_molecular_Raman (array_like) – Molecular scattering coefficient at Raman wavelength [m^{-1} sr^{-1}].

  • number_density (array_like) – Molecular number density.

  • angstrom (float) – Angstrom exponent for aerosol extinction coefficient.

  • window_size (int) – Window size for smoothing the signal using Savitzky-Golay filter.

  • method (str, optional) – Method to calculate the slope of the signal. Choices: ‘movingslope’, ‘smoothing’, ‘chi2’. Default is ‘movingslope’.

  • MC_count (int, optional) – Number of Monte Carlo iterations. Default is 1.

  • bg (float, optional) – Background signal (Photon Count). Default is 0.

Returns:

  • ext_aer (ndarray) – Aerosol extinction coefficient [m^-1].

  • ext_error (ndarray) – Error in aerosol extinction coefficient [m^-1] (only calculated for MC_count > 1).

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

History#

  • 2021-05-31: First edition by Zhenping

  • 2025-01-05: AI supported translation

  • 2026-02-04: Cleaned by Buholdt

TODO’s#

  • moving_smooth_varied_win function is not yet implemented.

  • moving_linfit_varied_win function is not yet implemented.

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_inela: ndarray, HRef: list | tuple, betaRef: float, window_size: int = 40, flagSmoothBefore: bool = True, el_lambda: int = None, inel_lambda: int = None, 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 uncertainty of aerosol backscatter coefficient with Monte-Carlo simulation.

Parameters:

  • height (ndarray) – Heights in meters.

  • sigElastic (ndarray) – Elastic photon count signal.

  • sigVRN2 (ndarray) – N2 vibration rotational Raman photon count signal.

  • ext_aer (ndarray) – Aerosol extinction coefficient [m^{-1}].

  • angstroem (ndarray) – Aerosol Angstrom exponent.

  • ext_mol (ndarray) – Molecular extinction coefficient [m^{-1}].

  • beta_mol (ndarray) – Molecular backscatter coefficient [m^{-1}Sr^{-1}].

  • ext_mol_raman (ndarray) – Molecular extinction coefficient for Raman wavelength.

  • beta_mol_inela (ndarray) – Molecular backscatter coefficient for inelastic wavelength.

  • HRef (list or tuple) – Reference region [m].

  • betaRef (float) – Aerosol backscatter coefficient at the reference region.

  • window_size (int) – Number of bins for the sliding window for signal smoothing. Default is 40.

  • flagSmoothBefore (bool) – Flag to control the smoothing order. Default is True.

  • el_lambda (int) – Elastic wavelength [nm].

  • inel_lambda (int) – Inelastic wavelength [nm].

  • bgElastic (ndarray) – Background of elastic signal.

  • bgVRN2 (ndarray) – Background of N2 vibration rotational signal.

  • sigma_ext_aer (ndarray) – Uncertainty of aerosol extinction coefficient [m^{-1}].

  • sigma_angstroem (ndarray) – Uncertainty of Angstrom exponent.

  • MC_count (int or list) – Samples for each error source. Default is 3.

  • method (str) – Computational method (‘monte-carlo’ or ‘analytical’). Default is ‘monte-carlo’.

Returns:

  • beta_aer (ndarray) – Aerosol backscatter coefficient [m^{-1}Sr^{-1}].

  • aerBscStd (ndarray) – Uncertainty of aerosol backscatter coefficient [m^{-1}Sr^{-1}].

  • LR (ndarray) – Aerosol Lidar ratio [sr].

  • History

  • ——-

  • - xxxx-xx-xx …

  • - 2026-02-04 (Cleaned by Buholdt)

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_inela: ndarray, HRef: list, betaRef: float, window_size: int = 40, flagSmoothBefore: bool = True, el_lambda: int = None, inel_lambda: int = None) → tuple[ndarray, ndarray, list, ndarray][source]#

Calculate the aerosol backscatter coefficient with the Raman method.

Parameters:

  • height (array) – Height in meters.

  • sigElastic (array) – Elastic photon count signal.

  • sigVRN2 (array) – N2 vibration rotational Raman photon count signal.

  • ext_aer (array) – Aerosol extinction coefficient [m^{-1}].

  • angstroem (array) – Aerosol Angstrom exponent.

  • ext_mol (array) – Molecular extinction coefficient [m^{-1}].

  • beta_mol (array) – Molecular backscatter coefficient [m^{-1}Sr^{-1}].

  • ext_mol_raman (array) – Molecular extinction coefficient for Raman wavelength [m^{-1}].

  • beta_mol_inela (array) – Molecular inelastic backscatter coefficient [m^{-1}Sr^{-1}].

  • HRef (list) – Reference region in meters [start, end].

  • betaRef (float) – Aerosol backscatter coefficient at the reference region [m^{-1}Sr^{-1}].

  • window_size (int, optional) – Number of bins for the sliding window for signal smoothing. Default is 40.

  • flagSmoothBefore (bool, optional) – Whether to smooth the signal before or after calculating the signal ratio. Default is True.

  • el_lambda (int, optional) – Elastic wavelength [nm].

  • inel_lambda (int, optional) – Inelastic wavelength [nm].

Returns:

  • beta_aer (array) – Aerosol backscatter coefficient [m^{-1}Sr^{-1}].

  • LR (array) – Aerosol lidar ratio [sr].

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.

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

TODO:#

  • el_lambda & inel_lambda are not optional arguments as it currently stands. Either change the deafult value in the function init and doc-string or add a detection and replace by a config parameter in the code.

  • angstroem is an float in beta_aer calculations and an array of shape (1, ) in beta_aer_std claculations.

  • Find a way of sending both HRef and HRefIndx through the functions to avoid recalculating the indices over and over again

ppcpy.retrievals.raman.smoothWin(signal: ndarray, win: int | ndarray, method: str = 'moving', filter: str = 'uniform') → ndarray[source]#

Smooth signal with a height-dependent window.

Parameters:

  • signal (array) – Input signal array.

  • win (int or array) – Window size. Can be a fixed scalar or a variable-length array.

  • method (str, optional) – Smoothing method. Default is ‘moving’.

Returns:

signalSM – Smoothed signal.

Return type:

array

Notes

  • TODO: Support for smoothing wiht variable window size is not yet implemented.

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:

  • aerExt (ndarray) – Aerosol extinction coefficient [m^{-1}].

  • aerBsc (ndarray) – Aerosol backscatter coefficient [m^{-1}sr^{-1}].

  • hRes (float, optional) – Vertical resolution of each height bin [m]. Default is 7.5.

  • aerExtStd (ndarray, optional) – Uncertainty of aerosol extinction coefficient [m^{-1}].

  • aerBscStd (ndarray, optional) – Uncertainty of aerosol backscatter coefficient [m^{-1}sr^{-1}].

  • smoothWinExt (int, optional) – Applied smooth window length for calculating aerosol extinction coefficient. Default is 1.

  • smoothWinBsc (int, optional) – Applied smooth window length for calculating aerosol backscatter coefficient. Default is 1.

Returns:

  • aerLR (ndarray) – Aerosol lidar ratio [sr].

  • effRes (float) – Effective resolution of lidar ratio [m].

  • aerLRStd (ndarray) – Uncertainty of aerosol lidar ratio [sr].

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.

History#

2021-07-20: First edition by Zhenping (translated to Python)

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.