solrad.atmosphere package#

Submodules#

solrad.atmosphere.aerosol_asymmetry_factor module#

This module contains all functions, methods and classes related to the computation and manipulation of the aerosol asymmetry factor of a site.

solrad.atmosphere.aerosol_asymmetry_factor.compute_aerosol_asymmetry_factor_using_SF(RH, wavelength, model, interp_method='linear')#

Compute the aerosol asymmetry factor using the Shettel and Fenn (SF) model as described in [1].

Parameters:
  • RH (float or array_like of floats) – Relative Humidity of the air in %. Must be a non-negative number or array of numbers between 0 and 100.

  • wavelength (float or array_like of floats) – Wavelength in nanometers for which the aerosol asymmetry factor is to be computed. Must be a number or array of numbers between 200 and 4500.

  • model ({“Rural”, “Urban” and "Maritime"}) – Model to be used in the computation of the Aerosol Asymmetry Factor.

  • interp_method ({"linear", "nearest", "cubic"}, optional) – Method of interpolation to use on the data. Default is “linear”.

Returns:

aerosol_asymmetry_factor – Aerosol asymmetry factor.

Return type:

numpy.array of floats

Notes

1) ‘RH’’ can be an array of any length, while ‘wavelength’ is a float; and viceversa. However, if ‘RH’ and ‘wavelength’ are both arrays, they should be the same length.

References

[1] Shettle, Eric & Fenn, Robert. (1979). Models for the Aerosols of the Lower Atmosphere and the Effects of Humidity Variations on their Optical Properties. Environ. Res.. 94.

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from solrad.atmosphere.aerosol_asymmetry_factor import compute_aerosol_asymmetry_factor_using_SF
>>>
>>> wavelengths = np.linspace(280, 4000, 1000)
>>> RHs = np.array([0, 50, 70, 80, 90, 95, 98, 99])
>>>
>>> for model in ["Rural", "Urban", "Maritime"]:
>>>
>>>       data = np.zeros((len(RHs), len(wavelengths)))
>>>       fig = plt.figure(figsize=(15,10))
>>>
>>>       for i, RH in enumerate(RHs):
>>>           data[i,:] = compute_aerosol_asymmetry_factor_using_SF(RH, wavelengths, model, interp_method="linear")
>>>           plt.plot(wavelengths, data[i,:], label = f"{RH}%")
>>>
>>>       plt.xlim(280, 4000)
>>>       plt.xlabel("Wavelengths [nm]")
>>>       plt.ylabel("Aerosol Asymmetry Factor [-]")
>>>       plt.title(f"Model= {model}")
>>>       plt.legend(title = "Relative Humidity")
>>>       plt.grid()
>>>       plt.show()

solrad.atmosphere.angstrom_exponent module#

This module contains all functions, methods and classes related to the computation and manipulation of the Angstrom Turbidity Exponent of a site.

solrad.atmosphere.angstrom_exponent.compute_angstrom_exponent_using_SF(RH, wavelength=500, model='Urban')#

Compute the Ansgtrom turbidity exponent suing the Shettel and Fenn model, as detailed in [1].

Parameters:
  • RH (float or array_like of floats) – Relative Humidity of the air in %. Must be a non-negative number or array of numbers between 0 and 100.

  • wavelength (float, optional) – Wavelength in nanometers for which the Angstrom turbidity exponent is to be computed. Must be a non-ngeative number. Default is 500.

  • model ({“Rural”, “Urban” and "Maritime"}, optional) – Model to be used in the computation of the the Angstrom exponent.

Returns:

alpha – Angstrom turbidity coefficient.

Return type:

float or numpy.array of floats

References

[1] Gueymard, Chris. (1995). SMARTS2, a simple model of the atmospheric radiative transfer of sunshine: algorithms and performance assessment.

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from solrad.atmosphere.angstrom_exponent import compute_angstrom_exponent_using_SF
>>>
>>> RHs = np.linspace(0, 100, 101)
>>> for model in ["Rural", "Urban", "Maritime"]:
>>>
>>>     fig = plt.figure(figsize=(15,10))
>>>     alpha1 = compute_angstrom_exponent_using_SF(RHs, 499, model=model)
>>>     alpha2 = compute_angstrom_exponent_using_SF(RHs, 500, model=model)
>>>     plt.plot(RHs, alpha1, label="λ < 500 nm")
>>>     plt.plot(RHs, alpha2, label="λ ≥ 500 nm")
>>>     plt.grid()
>>>     plt.xlim(0,100)
>>>     plt.xlabel("RH [%]")
>>>     plt.ylabel("Angstrom Exponent")
>>>     plt.title(f"Model = {model}")
>>>     plt.legend(title = "Spectral Range")
>>>     plt.show()

solrad.atmosphere.aod_550nm module#

This module contains all functions, methods and classes related to the computation and manipulation of the Aerosol Optical Depth at 550nm (AOD_550) of a site.

CLIMATE DATA STORE

“The Copernicus - Climate Data Store (CDS) is an online open and free service that allows users to browse and access a wide range of climate datasets via a searchable catalogue. It also allows users to build their own applications, maps and graphs.”

1) CDS webpage at: https://cds.climate.copernicus.eu/cdsapp#!/home

2) More info about its API, at: https://cds.climate.copernicus.eu/api-how-to

3) Useful tutorial on how to use the API, at https://youtu.be/cVtiVTSVdlo

NOTE: As described by the links in 2) and 3), it is necessary to have a CDS account (and be currently logged in) account in order to be able to use the API. Furtheremore, the user’s key and the API website link should be stored in a place, recognisable by the system being used.

solrad.atmosphere.aod_550nm.fill_CDS_aod_550nm_data_nans(path, iterations=20000, show_progress=False, replace=False)#

Fill NaNs with suitable numeric aproximation of CDS aod_550nm raw data.

The data retrieved from the Climate Data Store (CDS) database referenced in [1] has a considerable amount of missing or defective values in its files. This is inconvenient for later computations. As such, this function reads all ‘raw.npy’ files in the directory specified by the path argument (i.e, the local aod_550nm database), that were obtained via the function get_CDS_aod_550nm_data(); and uses the function fill_CDS_globe_nans_using_laplace() to fill each file’s NaN values with a suitable numeric approximation and then saves each modified file back to the same directory as a ‘filled_NaNs.npy’ file.

Parameters:
  • path (path-str) – Path of the folder where the raw.npy files, containing the aerosol optical depth at 550 nm (aod_550nm) information downloaded from the aforementioned database, are stored. The resulting filled_NaNs.npy files will also be stored in this same directory.

  • iterations (int) – Number of iterations that the fill_CDS_globe_nans_using_laplace() function should use for computing the numerical approximation to the NaN values, before stopping (must be non-negative). The greater the number of iterations, the greater the chance that convergence of the computed values has been reached. However, the time of computation also increases. Default is 20000.

  • show_progress (bool, optional) – If True, after processing each file, it prints how many files have been processed as of yet. If False, it prints nothing. Default is False.

  • replace (bool, optional) – Whether to errase the original raw.npy files, after the new filled_NaNs.npy files (with have been created. This, as a way to save space in memory). Default is False.

Return type:

None

Raises:

1) Exception – “Local aod_550nm database is empty. No aod_550nm raw.npy files to retrieve were found.”

References

[1] Copernicus Climate Change Service, Climate Data Store, (2019): Aerosol properties gridded data from 1995 to present derived from satellite observation. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). DOI: 10.24381/cds.239d815c

solrad.atmosphere.aod_550nm.get_CDS_aod_550nm_data(path, year, month=None, file_format='numpy')#

Connects to the Climate Data Store (CDS) through its API and downloads the monthly-averaged aerosol optical depth at 550 nm (aod_550nm) data from the database in [1], for the requested time frame. A new folder (whose path is specified by the user) is then automatically created to store the downloaded files.

Parameters:
  • path (path-str) – Path of the folder where one wishes to store the downloaded files in.

  • year (list of str) – List of years for which the water-column data is to be retieved. The years must be of type str rather than int. Eg.: year = [“2020”, “2021”, “2022”].

  • month (None or list of str, optional) – If is None (default), all months for the selected years are retrieved. If not None, it must be list of months for which to retrieve the data. Said months must be of type str rather than int. Eg.: month = [“01”, “02”, “11”, “12”].

  • file_format ({'NetCDF4', 'numpy'}, optional) – Format in which the data is to be downloaded. If ‘NetCDF4’, the data is downloaded in its original format and no changes are made to it. If ‘numpy’ , the relevant aod_550nm data are downloaded, along with the latitude and longitude data, as numpy arrays. We also convert units from kg/m² to atm-cm (see notes for more info). Default is ‘numpy’.

Return type:

None

Notes

  1. For this function to work, the user must have a Climate Data Store account and be currently logged in. Furthermore, the user’s key and the API website link should be stored in a place, recognisable by the system being used. See https://youtu.be/DIdgltyoIYg?si=q7Ylu2p0IDFT9UGm for a quick Youtube tutorial about it. See https://cds.climate.copernicus.eu/api-how-to for the official documentation.

  2. For more information on the specific databse used, see: https://cds.climate.copernicus.eu/cdsapp#!/dataset/satellite-total-column-water-vapour-land-ocean?tab=overview

References

[1] Copernicus Climate Change Service, Climate Data Store, (2019): Aerosol properties gridded data from 1995 to present derived from satellite observation. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). DOI: 10.24381/cds.239d815c

solrad.atmosphere.aod_550nm.process_CDS_aod_550nm_data(path, percentile=0.5, interp_method='linear')#

Process Aerosol Optical Depth at 550nm (aod_550nm) data located in the local aod_550nm database. This function reads all the raw.ny and filled_NaNs.npy aod_550nm files (files which were obtained via the get_CDS_aod_550nm_data() and fill_CDS_globe_nans_using_laplace() functions) stored at the directory specified by path and then computes multiple useful quantities.

Parameters:
  • path (path-str) – Path of the folder where the aod_550nm raw.ny and filled_NaNs.npy files are stored. That is, the path to the local aod_550nm database.

  • percentile (float) – Percentile for computing the ‘percentile_data’ and ‘percentile_data_funcs’ dictionaries. Must be a number between 0 and 1. Default is 0.5.

  • interp_method ({'linear', 'nearest', 'slinear', 'cubic', 'quintic'}) – The method of interpolation to perform when computing the res[‘filled_nans_data_funcs’], res[‘avg_data_funcs’] and res[‘percentile_data_funcs’] dictionaries. Supported methods are the same as supported by scipy’s RegularGridInterpolator. Default is “linear”.

Returns:

res – Dictionary of computed quantities. It has the following key-value pairs:

“latitude”numpy.array of floats (npoints,)

Array of latitude values (in degrees) used by the raw.npy and filled_NaNs.npy files to specify the locations at which the aod_550nm data is reported.

”longitude”numpy.array of floats (mpoints,)

Array of longitude values (in degrees) used by the raw.npy and filled_NaNs.npy files to specify the locations at which the aod_550nm data is reported.

”raw_data”dict

Dictionary containing the raw data of aod_550nm values stored by the raw.npy files in the local aod_550nm database. It has the following key-value pair format:

(year, month)2D numpy.array of floats (npoints, mpoints)

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm).

”filled_nan_data”dict

Dictionary containing the filled-NaN data of aod_550nm values stored by the filled_NaNs.npy files in the local aod_550nm database. It has the following key-value pair format:

(year, month)2D numpy.array of floats (npoints, mpoints)

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm).

”filled_nan_data_funcs”dict

Dictionary containing the interpolating functions of the filled-NaN data of aod_550nm values stored in the local aod_550nm database. It has the following key-value pair format:

(year, month)scipy.interpolate.RegularGridInterpolator object

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the aod_550nm value expected at that location.

”avg_data”dict

Dictionary containing the year-wise averaged data of filled-NaN aod_550nm values stored in the local aod_550nm database, for each month. It has the following key-value pair format:

month2D numpy.arrays of floats (npoints, mpoints)

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm).

”avg_data_funcs”dict

Dictionary containing the interpolating functions of the year-wise averaged data of filled-NaN aod_550nm values stored in the local aod_550nm database, for each month. It has the following key-value pair format:

monthscipy.interpolate.RegularGridInterpolator object

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the aod_550nm value expected at that location.

”percentile_data”dict

Dictionary containing the year-wise ‘percentile’-th percentile of the filled-NaN aod_550nm data values stored in the local water database, for each month. It has the following key-value pair format:

month2D numpy.arrays of floats (npoints, mpoints)

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm).

”percentile_data_funcs”dict

Dictionary containing the interpolating functions of the filled-NaN year-wise ‘percentile’-th percentile data of aod_550nm values stored in the local aod_550nm database. It has the following key-value pair format:

monthscipy.interpolate.RegularGridInterpolator object

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the aod_550nm value expected at that location.

Return type:

dict

Raises:
  • 1) Exception – “Local aod_550nm database is empty. No aod_550nm raw.npy nor filled_NaNs.npy files to retrieve were found.”

  • 2) Exception – “Latitude data could not be recovered. No latitude.npy files are present in the database.”

  • 3) Exception – “Longitude data could not be recovered. No longitude.npy files are present in the database.”

Warns:
  • 1) Warning – “Local aod_550nm database is empty of filled_NaNs.npy files. No aod_550nm filled_NaNs.npy files to retrieve were found.”

  • 2) Warning – “Local aod_550nm database is empty of raw.npy files. No aod_550nm raw.npy files to retrieve were found.”

  • 3) Warning – “Not all raw.npy files have an associated filled_NaNs.npy file in the database, and viceversa. Therefore, not all information will be available for all files.”

  • 4) Warning – “WARNING: Local aod_550nm database lacks raw.npy data files for all 12 months of the year.”

  • 5) Warning – “WARNING: Local aod_550nm database lacks filled_NaNs.npy data files for all 12 months of the year.”

Notes

  1. res[“raw_data”] contains as many key-value pairs as there are raw.npy files in the local aod_550nm database.

  2. res[“filled_nan_data”], res[“filled_nan_data_funcs”], res[“avg_data”], res[“avg_data_funcs”], res[“precentile_data”] and res[“precentile_data_funcs”] as many key-value pairs as there are filled_NaNs.npy files in the local aod_550nm database.

  3. Latitude of -90° corresponds to the geographic South pole, while a latitude of 90° corresponds to the geographic North Pole.

  4. A negative longitude correspondes to a point west of the greenwhich meridian, while a positive longitude means it is east of the greenwhich meridian.

solrad.atmosphere.ozone_column module#

This module contains all functions, methods and classes related to the computation and manipulation of the atmospheric ozone column of a site.

CLIMATE DATA STORE

“The Copernicus - Climate Data Store (CDS) is an online open and free service that allows users to browse and access a wide range of climate datasets via a searchable catalogue. It also allows users to build their own applications, maps and graphs.”

1) CDS webpage at: https://cds.climate.copernicus.eu/cdsapp#!/home

2) More info about its API, at: https://cds.climate.copernicus.eu/api-how-to

3) Useful tutorial on how to use the API, at https://youtu.be/cVtiVTSVdlo

NOTE: As described by the links in 2) and 3), it is necessary to have a CDS account (and be currently logged in) account in order to be able to use the API. Furtheremore, the user’s key and the API website link should be stored in a place, recognisable by the system being used.

solrad.atmosphere.ozone_column.compute_van_Heuklon_ozone(latitude, longitude, timestamp)#

Returns the ozone contents in atm-cm for the given latitude/longitude and timestamp according to van Heuklon’s Ozone model. The model is described in Van Heuklon, ‘T. K. (1979). Estimating atmospheric ozone for solar radiation models. Solar Energy, 22(1), 63-68’. This function uses numpy functions, so you can pass arrays and it will return an array of results. The timestamp argument can be either an array/list or a single value. If timestamp is a single value then this will be used for all lat/lon values given.

Parameters:
  • latitude (float or array-like of floats (npoints,)) – Site’s latitude in degrees. Values must be between -90 and 90.

  • longitude (float or array-like of floats (npoints,)) – Site’s longitude in degrees. Values must be between -180 and 180.

  • timestamp (pandas.Timestamp object or array-like of pandas.Timestamp objects float or array-like of floats (npoints,)) – The times for which the ozone is to be computed. It is strongly recommend that the timestamp use an ISO 8601 format of yyyy-mm-dd.

Returns:

result – Ozone amount in atm-cm.

Return type:

float

Raises:
  • 1) ValueError – “lan and lon arrays must be the same length”

  • 2) ValueError – “Timestamp must be the same length as lat and lon”

Notes

  1. This function was directly taken from https://github.com/robintw/vanHOzone all credit goes to him. I copy-pasted the code rather than directly downloading tthe pachage from pip as I wanted to add some very minor changes.

  2. The function supports array-like inputs for latitude, longitude and timestamp, as long as all 3 arguments are the same length.

  3. Latitude of -90° corresponds to the geographic South pole, while a latitude of 90° corresponds to the geographic North Pole.

  4. A negative longitude correspondes to a point west of the greenwhich meridian, while a positive longitude means it is east of the greenwhich meridian.

solrad.atmosphere.ozone_column.get_CDS_ozone_column_data(path, year, month=None, file_format='numpy')#

Connects to the Climate Data Store (CDS) through its API and downloads the ozone-column data from the database in [1], for the requested time frame. A new folder (whose path is specified by the user) is then automatically created to store the downloaded files.

Parameters:
  • path (path-str) – Path of the folder where one wishes to store the downloaded files.

  • year (list of str) – List of years for which the ozone-column data is to be retieved. The years must be of type str rather than int. Eg.: year = [“2019”, “2020”, “2021”].

  • month (None or list of str) – If is None (default), all months for the selected years are retrieved. If not None, it must be list of months for which to retrieve the data. Said months must be of type str rather than int. Eg.: month = [“01”, “02”, “11”, “12”].

  • file_format ({'NetCDF4', 'numpy'}, optional) – Format in which the data is to be downloaded. If ‘NetCDF4’, the data is downloaded in its original format and no changes are made to it. If ‘numpy’ , the relevant water column data are downloaded, along with the latitude and longitude data, as numpy arrays. We also convert units from Dobson to atm-cm (see notes for more info). Default is ‘numpy’.

Return type:

None

References

[1] Copernicus Climate Change Service, Climate Data Store, (2020): Ozone monthly gridded data from 1970 to present derived from satellite observations. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). DOI: 10.24381/cds.4ebfe4eb

Notes

  1. For this function to work, the user must have a Climate Data Store account and be currently logged in. Furthermore, the user’s key and the API website link should be stored in a place, recognisable by the system being used. See https://youtu.be/DIdgltyoIYg?si=q7Ylu2p0IDFT9UGm for a quick Youtube tutorial about it. See https://cds.climate.copernicus.eu/api-how-to for the official documentation.

  2. For more information on the specific databse used, see: https://cds.climate.copernicus.eu/cdsapp#!/dataset/satellite-ozone-v1?tab=overview

  3. The downloaded data are .nc files holding the monthly-average of ozone-column data (in m atm-cm, i.e, Dobson) of the whole globe, for the requested time frame.

solrad.atmosphere.ozone_column.process_CDS_ozone_column_data(path, percentile=0.5, interp_method='linear')#

Process ozone data located in the local ozone database. This function reads the raw.npy ozone-column files (files which were obtained via the get_CDS_ozone_column_data() function) stored at the directory specified by path and then computes multiple useful quantities.

Parameters:
  • path (path-str) – Path of the folder where the water column raw.ny and filled_NaNs.npy files are stored. That is, the path to the local water column database.

  • percentile (float) – Percentile for computing the ‘percentile_data’ and ‘percentile_data_funcs’ dictionaries. Must be a number between 0 and 1. Default is 0.5.

interp_method{‘linear’, ‘nearest’, ‘slinear’, ‘cubic’, ‘quintic’}

The method of interpolation to perform when computing the res[‘raw_data_funcs’], res[‘avg_data_funcs’] and res[‘percentile_data_funcs’] dictionaries. Supported methods are the same as supported by scipy’s RegularGridInterpolator. Default is “linear”.

Returns:

res – Dictionary of computed quantities. It has the following key-value pairs:

“latitude”numpy.array of floats (npoints,)

Array of latitude values (in degrees) used by the raw.npy and filled_NaNs.npy files to specify the locations at which the water column data is reported.

”longitude”numpy.array of floats (mpoints,)

Array of longitude values (in degrees) used by the raw.npy and filled_NaNs.npy files to specify the locations at which the water column data is reported.

”raw_data”dict

Dictionary containing the raw data of ozone-column values stored by the raw.npy files in the local water column database. It has the following key-value pair format:

(year, month)2D numpy.array of floats (npoints, mpoints)

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm).

”raw_data_funcs”dict

Dictionary containing the interpolating functions of the raw data of ozone-column values stored in the local ozone database. It has the following key-value pair format:

(year, month)scipy.interpolate.RegularGridInterpolator object

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the ozone-column value expected at that location.

”avg_data”dict

Dictionary containing the year-wise averaged data of ozone-column values stored in the local ozone database, for each month. It has the following key-value pair format:

month2D numpy.arrays of floats (npoints, mpoints)

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm).

”avg_data_funcs”dict

Dictionary containing the interpolating functions of the year-wise averaged data of ozone-column values stored in the local ozone database, for each month. It has the following key-value pair format:

monthscipy.interpolate.RegularGridInterpolator object

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the ozone-column value expected at that location.

”percentile_data”dict

Dictionary containing the year-wise ‘percentile’-th percentile of the ozone-column data values stored in the local ozone database, for each month. It has the following key-value pair format:

month2D numpy.arrays of floats (npoints, mpoints)

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm).

”percentile_data_funcs”dict

Dictionary containing the interpolating functions of the year-wise ‘percentile’-th percentile of the ozone-column data values stored in the local ozone database, for each month. It has the following key-value pair format:

monthscipy.interpolate.RegularGridInterpolator object

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the ozone-column value expected at that location.

Return type:

dict

Raises:
  • 1) Exception – “Local ozone column database is empty. No ozone column raw.npy nor filled_NaNs.npy files to retrieve were found.”

  • 2) Exception – “Latitude data could not be recovered. No latitude.npy files are present in the database.”

  • 3) Exception – “Longitude data could not be recovered. No longitude.npy files are present in the database.”

Warns:

1) Warning – “WARNING: Local ozone column database lacks raw.npy data files for all 12 months of the year.”

Notes

  1. res[“raw_data”], res[“raw_data_funcs”], res[“avg_data”], res[“avg_data_funcs”], res[“precentile_data”] and res[“precentile_data_funcs”] as many key-value pairs as there are raw.npy files in the local ozone database.

  2. Latitude of -90° corresponds to the geographic South pole, while a latitude of 90° corresponds to the geographic North Pole.

  3. A negative longitude correspondes to a point west of the greenwhich meridian, while a positive longitude means it is east of the greenwhich meridian.

solrad.atmosphere.single_scattering_albedo module#

This module contains all functions, methods and classes related to the computation and manipulation of the Single-Scattering Albedo of a site.

solrad.atmosphere.single_scattering_albedo.compute_single_scattering_albedo_using_SF(RH, wavelength, model, interp_method='linear')#

Compute the single scattering albedo using the Shettel and Fenn (SF) model as described in [1].

Parameters:
  • RH (float or array_like of floats) – Relative Humidity of the air in %. Must be a non-negative number or array of numbers between 0 and 100.

  • wavelength (float or array_like of floats) – Wavelength in nanometers for which the single scattering albedo is to be computed. Must be a number or array of numbers between 200 and 4500.

  • model ({“Rural”, “Urban”, "Maritime"}) – Model to be used in the computation of the single scattering albedo.

  • interp_method ({"linear", "nearest", "cubic"}, optional) – Method of interpolation to use on the data. Default is “linear”.

Returns:

single_scattering_albedo – Single scattering albedo.

Return type:

numpy.array of floats

Notes

1) ‘RH’’ can be an array of any length, while ‘wavelength’ is a float; and viceversa. However, if ‘RH’ and ‘wavelength’ are both arrays, they should be the same length.

References

[1] Shettle, Eric & Fenn, Robert. (1979). Models for the Aerosols of the Lower Atmosphere and the Effects of Humidity Variations on their Optical Properties. Environ. Res.. 94.

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from solrad.atmosphere.single_scattering_albedo import compute_single_scattering_albedo_using_SF
>>>
>>> wavelengths = np.linspace(280, 4000, 1000)
>>> RHs = np.array([0, 50, 70, 80, 90, 95, 98, 99])
>>>
>>> for model in ["Rural", "Urban", "Maritime"]:
>>>
>>>     data = np.zeros((len(RHs), len(wavelengths)))
>>>     fig = plt.figure(figsize=(15,10))
>>>
>>>     for i, RH in enumerate(RHs):
>>>         data[i,:] = compute_single_scattering_albedo_using_SF(RH, wavelengths, model, interp_method="linear")
>>>         plt.plot(wavelengths, data[i,:], label = f"{RH}%")
>>>
>>>
>>>     plt.xlim(280, 4000)
>>>     plt.xlabel("Wavelengths [nm]")
>>>     plt.ylabel("Single Scattering Albedo [-]")
>>>     plt.title(f"Model= {model}")
>>>     plt.legend(title = "Relative Humidity")
>>>     plt.grid()
>>>     plt.show()

solrad.atmosphere.water_column module#

This module contains all functions, methods and classes related to the computation and manipulation of the precipitable water column of a site.

CLIMATE DATA STORE

“The Copernicus - Climate Data Store (CDS) is an online open and free service that allows users to browse and access a wide range of climate datasets via a searchable catalogue. It also allows users to build their own applications, maps and graphs.”

1) CDS webpage at: https://cds.climate.copernicus.eu/cdsapp#!/home

2) More info about its API, at: https://cds.climate.copernicus.eu/api-how-to

3) Useful tutorial on how to use the API, at https://youtu.be/cVtiVTSVdlo

NOTE: As described by the links in 2) and 3), it is necessary to have a CDS account (and be currently logged in) account in order to be able to use the API. Furtheremore, the user’s key and the API website link should be stored in a place, recognisable by the system being used.

solrad.atmosphere.water_column.fill_CDS_water_column_data_nans(path, iterations=20000, show_progress=False, replace=False)#

Fill NaNs with suitable numeric aproximation of CDS water column raw data.

The data retrieved from the Climate Data Store (CDS) database referenced in [1] has a considerable amount of missing or defective values in its files. This is inconvenient for later computations. As such, this function reads all ‘raw.npy’ files in the directory specified by the path argument (i.e, the local water column database), that were obtained via the function get_CDS_water_column_data(); and uses the function fill_CDS_globe_nans_using_laplace() to fill each file’s NaN values with a suitable numeric approximation and then saves each modified file back to the same directory as a ‘filled_NaNs.npy’ file.

Parameters:
  • path (path-str) – Path of the folder where the raw.npy files, containing the water column information downloaded from the aforementioned database, are stored. The resulting filled_NaNs.npy files will also be stored in this same directory.

  • iterations (int) – Number of iterations that the fill_CDS_globe_nans_using_laplace() function should use for computing the numerical approximation to the NaN values, before stopping (must be non-negative). The greater the number of iterations, the greater the chance that convergence of the computed values has been reached. However, the time of computation also increases. Default is 20000.

  • show_progress (bool, optional) – If True, after processing each file, it prints how many files have been processed as of yet. If False, it prints nothing. Default is False.

  • replace (bool, optional) – Whether to errase the original raw.npy files, after the new filled_NaNs.npy files (with have been created. This, as a way to save space in memory. Default is False.

Raises:

1) Exception : – “Local water column database is empty. No water column raw.npy files to retrieve were found.”

Return type:

None

References

[1] Preusker, R., El Kassar, R. (2022): Monthly total column water vapour over land and ocean from 2002 to 2012 derived from satellite observation. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). DOI: 10.24381/cds.8e0e4724

solrad.atmosphere.water_column.get_CDS_water_column_data(path, year, month=None, file_format='numpy')#

Connects to the Climate Data Store (CDS) through its API and downloads the monthly-averaged water column data from the database in [1], for the requested time frame. A new folder (whose path is specified by the user) is then automatically created to store the downloaded files.

Parameters:
  • path (path-str) – Path of the folder where one wishes to store the downloaded files in.

  • year (list of str) – List of years for which the water-column data is to be retieved. The years must be of type str rather than int. Eg.: year = [“2009”, “2010”, “2011”].

  • month (None or list of str, optional) – If is None (default), all months for the selected years are retrieved. If not None, it must be list of months for which to retrieve the data. Said months must be of type str rather than int. Eg.: month = [“01”, “02”, “11”, “12”].

  • file_format ({'NetCDF4', 'numpy'}, optional) – Format in which the data is to be downloaded. If ‘NetCDF4’, the data is downloaded in its original format and no changes are made about it. If ‘numpy’ , the relevant water column data are downloaded, along with the latitude and longitude data, as numpy arrays. We also convert units from kg/m² to atm-cm (see notes for more info). Default is ‘numpy’.

Return type:

None

Notes

1) For this function to work, the user must have a Climate Data Store account and be currently logged in. Furtheremore, the user’s key and the API website link should be stored in a place, recognisable by the system being used. See https://youtu.be/DIdgltyoIYg?si=q7Ylu2p0IDFT9UGm for a quick Youtube tutorial about it. See https://cds.climate.copernicus.eu/api-how-to for the official documentation.

2) For more information on the specific databse used, see: https://cds.climate.copernicus.eu/cdsapp#!/dataset/satellite-total-column-water-vapour-land-ocean?tab=overview

3) The original, unaltered, downloaded data are .nc files holding the Total Column Water Vapour (in kg/m²) of the whole globe, for the requested time frame.

4) “Total Column Water Vapour (also called integrated Water Vapour (IWV) or Precipitable Water Vapour (PWV)) is the integrated mass of gaseous water in the total column of the atmosphere over an area of 1 m²” and it is usually given in kg/m². However, another common way of expressing this same variable, is as the height (in cm) that a column of x kilograms of water would have, when being bounded by a cube whose base has an area of 1 m². Using the average density of water (997 kg/m³ ≈ 1000 kg/m³), we see that a Total column of water vapour of x kg/m² would roughly equate to a x/10 cm water column.

References

[1] Preusker, R., El Kassar, R. (2022): Monthly total column water vapour over land and ocean from 2002 to 2012 derived from satellite observation. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). DOI: 10.24381/cds.8e0e4724

solrad.atmosphere.water_column.process_CDS_water_column_data(path, percentile=0.5, interp_method='linear')#

Process the water column data located in the local water column database. This function reads all the raw.ny and filled_NaNs.npy water column files (files which were obtained via the get_CDS_water_column_data() function) and fill_CDS_globe_nans_using_laplace() functions) stored at the directory specified by path and then computes multiple useful quantities.

Parameters:
  • path (path-str) – Path of the folder where the water column raw.ny and filled_NaNs.npy files are stored. That is, the path to the local water column database.

  • percentile (float) – Percentile for computing the ‘percentile_data’ and ‘percentile_data_funcs’ dictionaries. Must be a number between 0 and 1. Default is 0.5.

  • interp_method ({'linear', 'nearest', 'slinear', 'cubic', 'quintic'}) – The method of interpolation to perform when computing the res[‘filled_nans_data_funcs’], res[‘avg_data_funcs’] and res[‘percentile_data_funcs’] dictionaries. Supported methods are the same as supported by scipy’s RegularGridInterpolator. Default is “linear”.

Returns:

res – Dictionary of computed quantities. It has the following key-value pairs:

“latitude”numpy.array of floats (npoints,)

Array of latitude values (in degrees) used by the raw.npy and filled_NaNs.npy files to specify the locations at which the water column data is reported.

”longitude”numpy.array of floats (mpoints,)

Array of longitude values (in degrees) used by the raw.npy and filled_NaNs.npy files to specify the locations at which the water column data is reported.

”raw_data”dict

Dictionary containing the raw data of water-column values stored by the raw.npy files in the local water column database. It has the following key-value pair format:

(year, month)2D numpy.array of floats (npoints, mpoints)

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm).

”filled_nan_data”dict

Dictionary containing the filled-NaN data of water-column values stored by the filled_NaNs.npy files in the local water column database. It has the following key-value pair format:

(year, month)2D numpy.array of floats (npoints, mpoints)

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm).

”filled_nan_data_funcs”dict

Dictionary containing the interpolating functions of the filled-NaN data of water-column values stored in the local water column database. It has the following key-value pair format:

(year, month)scipy.interpolate.RegularGridInterpolator object

Where ‘year’ and ‘month’ are integers that specify the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the water-column value expected at that location.

”avg_data”dict

Dictionary containing the year-wise averaged data of filled-NaN water-column values stored in the local water database, for each month. It has the following key-value pair format:

month2D numpy.arrays of floats (npoints, mpoints)

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm).

”avg_data_funcs”dict

Dictionary containing the interpolating functions of the year-wise averaged data of filled-NaN water-column values stored in the local water database, for each month. It has the following key-value pair format:

monthscipy.interpolate.RegularGridInterpolator object

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the water-column value expected at that location.

”percentile_data”dict

Dictionary containing the year-wise ‘percentile’-th percentile of the filled-NaN water-column data values stored in the local water database, for each month. It has the following key-value pair format:

month2D numpy.arrays of floats (npoints, mpoints)

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm).

”percentile_data_funcs”dict

Dictionary containing the interpolating functions of the filled-NaN year-wise ‘percentile’-th percentile data of water-column values stored in the local water column database. It has the following key-value pair format:

monthscipy.interpolate.RegularGridInterpolator object

Where ‘month’ is an integer that specifies the time period for the array of data (with units atm-cm) that the function interpolates. It takes as input a value of latitude and longitude and returns the water-column value expected at that location.

Return type:

dict

Raises:
  • 1) Exception – “Local water column database is empty. No water column raw.npy nor filled_NaNs.npy files to retrieve were found.”

  • 2) Exception – “Latitude data could not be recovered. No latitude.npy files are present in the database.”

  • 3) Exception – “Longitude data could not be recovered. No longitude.npy files are present in the database.”

Warns:
  • 1) Warning – “Local water column database is empty of filled_NaNs.npy files. No column water filled_NaNs.npy files to retrieve were found.”

  • 2) Warning – “Local water column database is empty of raw.npy files. No column water raw.npy files to retrieve were found.”

  • 3) Warning – “Not all raw.npy files have an associated filled_NaNs.npy file in the database, and viceversa. Therefore, not all information will be available for all files.”

  • 4) Warning – “WARNING: Local water column database lacks raw.npy data files for all 12 months of the year.”

  • 5) Warning – “WARNING: Local water column database lacks filled_NaNs.npy data files for all 12 months of the year.”

Notes

1) res[“raw_data”] contains as many key-value pairs as there are raw.npy files in the local water database.

2) res[“filled_nan_data”], res[“filled_nan_data_funcs”], res[“avg_data”], res[“avg_data_funcs”], res[“precentile_data”] and res[“precentile_data_funcs”] as many key-value pairs as there are filled_NaNs.npy files in the local water database.

3) Latitude of -90° corresponds to the geographic South pole, while a latitude of 90° corresponds to the geographic North Pole.

4) A negative longitude correspondes to a point west of the greenwhich meridian, while a positive longitude means it is east of the greenwhich meridian.

Module contents#