Metadata-Version: 2.4
Name: boreal_LOA
Version: 0.5.0
Summary: Python package of the Basic algOrithm for REtrieval of Aerosol with Lidar - an algorithm to retrieve aerosol optical and microphysical properties from lidar measurements
Author-email: Yuyang Chang <yuyang.chang@univ-lille.fr>
License-Expression: LicenseRef-BSD-3-Clause-with-Citation-Requirement
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy==1.23.5
Requires-Dist: scipy==1.13.1
Requires-Dist: pandas==2.3.3
Requires-Dist: matplotlib==3.6.2
Dynamic: license-file

# BOREAL package to be integrated into AUSTRAL or used independently.
## General description 
The **BOREAL** (**B**asic alg**O**rithm for **RE**trieval of **A**erosol with **L**idar) algorithm is developed by 
the Laboratoire d'Optique Atmospherique, a joint research unit of the University of Lille and CNRS.
This package retrieves particle volume size distribution (VSD) and complex refractive index (CRI = mR -imI) from 
lidar-derived extinction + backscattering (or + depolarisation) properties. Total volume concentration (Vt), 
effective radius (reff) and single-scattering albedo (SSA) are then calculated from the retrieved VSD and CRI.

## Data policy
If you utilize the BOREAL retrieval products for publication purposes, we kindly request you to cite the paper listed 
in **References** and acknowledge the contribution of "University of Lille/CNRS/Laboratoire d'Optique Atmospherique".
Additionally, we encourage you to consider offering co-authorship to the scientists who contributed to the development 
of BOREAL, if their involvement is relevant to your work. Your recognition and collaboration contribute to the 
advancement of scientific research and the acknowledgment of the efforts invested in the development of these 
resources for the community.

## Structure of the package
Scripts and datasets are contained in **./boreal**, where the folder **forward_module** includes the implementations of the sphere, spheroid and ih models. **BOREAL.py** and **BOREAL_PC.py** call the forward models
and realize the inverse process.

## Installation
You can clone the source coed from the repository by

Alternatively, you can install the package through PyPI. To do so, set up a Python 3.9+ environment with 'pip' available, then

## BOREAL.py
The python script implementing the BOREAL method. To run the retrieval, in a python script or an interactive shell, type the following commands:  
1. `from boreal import BOREAL` to import BOREAL
2. `retrieval, fit = BOREAL.inversion(...)` to perform the retrieval
3. `filepath_fit = BOREAL.plot_fit(...)`, `filepath_rtv = BOREAL.plot_rtv(...)`, or `filepath_txt = BOREAL.export_txt(...)` to visualize the results

Mandatory arguments in `BOREAL.inversion()`:
* *ext*: dict, spectral extinction coefficient, the keys (str) are wavelength in nm, the values are corresponding measurements (float) in 1/Mm
* *bac*: dict, spectral bac. coef., the keys (str) are wavelength in nm, the values are corresponding measurements (float) in (Mm*sr)^(-1)
* *aero_type*: str, 'dust', 'bba', 'urban' or 'ss' (sea salt), a priori knowledge of aerosol type
* *model*: str, 'sphere', 'spheroid' or 'ih', forward model (scattering model) used in the inversion

Optional arguments:
* *depol*: None or dict (default=None), particle spectral depolarization ratio, the keys (str) are wavelength in nm, the values are corresponding measurements (float) (unit of 1)
* *ext_err*: None or dict (default=None), maximum measurement error in ext (three times of measurement std). None for default values.
* *bac_err*: None or dict (default=None), maximum measurement error in bac (three times of measurement std). None for default values.
* *depol_err*: None or dict (default=None), maximum measurement error in depol (three times of measurement std). None for default values.
* *config*: None or dict (default=None), customized configuration for implementing the retrieval

## BOREAL_PC.py
The python script implementing the BOREAL-PC method which retrieves parameterized VSD and CRI with the aid of a priori constraints from historical in situ measurements. To run the retrieval, in a python script or an interactive shell, type the following commands: 
```
from boreal import BOREAL_PC

# organise the input optical data
opt_harmonized = BOREAL_PC.harmonize_opt_format(ext, bac, depol)   # ext, bac, depol are dictionaries with keys=wavelength and values=values. e.g., ext={'355': value_355, '532': value_532}

# perform a retrieval
boreal_pc_instance = BOREAL_PC.Retrieval_bimodal(opt_harmonized)
boreal_pc_rtv = boreal_pc_instance.do_retrieval()

# output results in txt format
BOREAL_PC.export_txt(...)
``` 

Input arguments for `BOREAL_PC.harmonize_opt_format()`:
* *ext*: dict, same as that input to `BOREAL.inversion()`, but the wavelengths have to be '355' and '532'
* *bac*: dict, same as that input to `BOREAL.inversion()`, but the wavelengths have to be '355', '532' and '1064'
* *depol*: dict,same as that input to `BOREAL.inversion()`, but is mandatory and the wavelengths have to be '355', '532' and '1064'  

Note: 
1. Since BOREAL-PC is specially designed for dust retrieval, the argument *aero_type* makes no sense
2. Only the IH model is available.
3. To ensure acceptable retrieval accuracy, the complete optical dataset (i.e., 2a+3b+3d) is required. The accuracy of inverting deficient dataset needs further evaluation.

## References
- Chang, Y., Hu, Q., Goloub, P., Veselovskii, I., and Podvin, T.: Retrieval of Aerosol Microphysical Properties from Multi-Wavelength Mie–Raman Lidar Using Maximum Likelihood Estimation: Algorithm, Performance, and Application, Remote Sens., 14, 6208, https://doi.org/10.3390/rs14246208, 2022.
- Chang, Y., Hu, Q., Goloub, P., Podvin, T., Veselovskii, I., Ducos, F., Dubois, G., Saito, M., Lopatin, A., Dubovik, O., and Chen, C.: Retrieval of microphysical properties of dust aerosols from extinction, backscattering and depolarization lidar measurements using various particle scattering models, Atmos. Chem. Phys., 25, 6787–6821, https://doi.org/10.5194/acp-25-6787-2025, 2025.
