## ============================Introduction============================

-> "CNN_AllClearSkyAerosolRetrival": a new all-clear-sky (including near-cloud regions) aerosol retrieval method for passive satellite observation.
   
-> Please read Yang et al. (2022) "Near-Cloud Aerosol Retrieval Using Machine Learning Techniques, and Implied Direct Radiative Effects" for more information.

## ========================Citation & Contacts=========================

1. Data citation: Yang, C. K., et al. 2022. Dataset associated with "Near-Cloud Aerosol Retrieval Using Machine Learning Techniques, and Implied Direct Radiative Effects." Colorado State University. Libraries. http://dx.doi.org/10.25675/10217/235755
2. Citation: Yang, C. K., et al. Near-Cloud Aerosol Retrieval Using Machine Learning Techniques, and Implied Direct Radiative Effects. Geophysical Research Letters, 49, e2022GL098274. https://doi.org/10.1029/2022GL098274

3. PI: Dr. Christine Chiu (Christine.Chiu@colostate.edu)
4. Co-I: Dr. C.Kevin Yang (yang0920@rams.colostate.edu)

## ===============License Information==============

1. Data license: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
2. Python module license: MIT License (see LICENSE.txt)

Those interested in using these data are encouraged to contact the PI or Co-I (see above) for more information.

## ===============Descriptions of Machine-Learning models==============

1. INPUT variables:
		1) reflectance
			 - wavelength: 870-nm
			 - viewing geometry: nadir at the top of the atmosphere
			 - solar geometry: SZA=50 deg. and SAZ=210 clockwise from north
			 - horizontal resolution: 100-m
			 - dimension: a 2D map, 45-by-45 (pixel)
		2) cloud_mask
			 - horizontal resolution: 100-m
			 - dimension: a 2D map, 25-by-25 (pixel)

2. Output variable:
		1) aerosol_optical_depth
		     - wavelength: 870-nm
			 - horizontal resolution: 100-m 
			 - dimension: a 2D map, 25-by-25 (pixel)
			 - additional info.: the aerosol_optical_depth in cloudy regions 
			                     will be turned into "NaN"
								 
## =========================About this package=========================

1. "CNN_AllClearSkyAerosolRetrieval_module.py": PLEASE DO NOT MODIFY THE CONTENT
   - This is a python module that contains the all-clear-sky aerosol retrieval method
   - The module will perform the following tasks:
	 1) load in the trained convolutional neural network (CNN) from
     	"CNN_AllClearSkyAerosolRetrieval_model.hdf5"
	 2) Scale the "Input" variable
	 3) Make predictions
	 4) Transform the "Output variable back to the original scale
	 5) Apply cloud_mask to the retrieved aerosol optical depth field
   - There will be warning messages when using this module. Users can safely ignore them.
	 
2. "CNN_AllClearSkyAerosolRetrieval_model.hdf5":
   - a trained convolutional neural network (CNN) contains weights and biases
   
3. "reflectance.mat": an example 2D reflectance field

4. "cloud_mask.mat": an example 2D cloud_mask 

5. run_example.py: use the example "2D reflectance field" and "2D cloud_mask field"
                   to demonstrate how to use CNN_AllClearSkyAerosolRetrieval_module.py
                   to retrieve aerosol_optical_depth for all-clear-sky regions
				   
## =====================Installation (from scratch)====================

-> Step 0: this package can run on Windows, macOS, and Linux with an appropriate 
           python package manager installed in the operating system.
		   
-> Step 1: make sure that the following packages are installed in your Python3 environment
   - Numpy
   - Scipy
   - Tensorflow
   - Keras
   
-> Step 2: put all the necessary files (2 in total) in the working directory; you should have:
   - CNN_AllClearSkyAerosolRetrieval_module.py
   - CNN_AllClearSkyAerosolRetrieval_model.hdf5
   
!!!YOU ARE ALL SET FOR RUNNING THIS MODULE!!!

-> Additional information:
   - You do not need to have CUDA installed in your operating system to use the package