Usage

radcalnet_oc simulates the top-of-atmosphere (TOA) signal above a water site from a time series of measurements at the surface, typically those of an AERONET-OC station.

Input data

The input is an xarray.Dataset with a time dimension (one row per measurement) and a wl dimension (wavelength in nm) for the water reflectance:

Variable	Dimensions	Description
Rrs	time, wl	remote-sensing reflectance (sr-1), hyperspectral or interpolated from the AERONET-OC bands
sza	time	solar zenith angle (deg)
day_of_year	time	day of year, for the Earth-Sun distance
aot550	time	aerosol optical thickness at 550 nm
aot865, ang_exp	time	aerosol optical thickness at 865 nm and Angström exponent (copied to the output)
pressure	time	surface pressure (hPa)
tcwv, tco3, tcno2	time	total columns of water vapour, ozone and nitrogen dioxide (kg m-2)

Examples are shipped with the package in radcalnet_oc/data/template (template_clear_water.nc, template_turbid_water.nc).

Command line

The radcalnet_oc command reads the input NetCDF file and writes the simulation (see Output) in a NetCDF file:

Usage:
  radcalnet_oc <input_file> [--output <output_file>] [--vza angles] [--azi angles]
   [--aerosol_combination props] [--solar_database name] [--rrs_name name]
   [--bands wavelengths] [--fwhm fwhm] [--expon expon] [--no_clobber]
  radcalnet_oc -h | --help
  radcalnet_oc -v | --version

Options:
  -h --help        Show this screen.
  -v --version     Show version.

  <input_file>     NetCDF file of the surface measurements (time series with the variables
                   Rrs, sza, day_of_year, aot550, pressure, tcwv, tco3, tcno2...)

  -o <output_file>, --output <output_file>  Output NetCDF file
                   (by default: <input_file basename>_radcalnet_oc.nc in the current directory)
  --vza angles     Viewing zenith angles (deg), comma-separated [default: 0]
  --azi angles     Relative azimuth angles (deg), comma-separated [default: 0]
  --aerosol_combination props  Proportion of each aerosol model of config.yml, comma-separated
                   (models: ARCT_rh70, COAV_rh70, DESE_rh70, MACL_rh70, URBA_rh70, WASO_rh0;
                   by default: proportions of config.yml)
  --solar_database name  Extraterrestrial solar spectrum: tsis, thuillier, gueymard or kurucz
                   [default: tsis]
  --rrs_name name  Name of the remote-sensing reflectance variable in <input_file> [default: Rrs]
  --bands wavelengths  Central wavelengths (nm) of sensor bands, comma-separated: the band-averaged
                   Rtoa, Ratm, Ed, E0 and Rrs are added to the output (variables <name>_bands,
                   dimension wl_band)
  --fwhm fwhm      Full width at half maximum (nm) of the bands: one value for all the bands or
                   one per band, comma-separated [default: 10]
  --expon expon    Exponent of the super-Gaussian spectral responses (2: Gaussian) [default: 3]
  --no_clobber     Do not process <input_file> if <output_file> already exists.

  Example:
      radcalnet_oc AAOT_input.nc --vza 0,10 --azi 90 --bands 443,490,560,665,865 --fwhm 20

Python

import numpy as np
import xarray as xr
from importlib.resources import files
import radcalnet_oc as radoc

input_db = xr.open_dataset(files('radcalnet_oc.data.template') / 'template_clear_water.nc')

# viewing geometry of the satellite (one or several angles)
vza = xr.DataArray([0., 10.], coords={'vza': [0., 10.]}, dims='vza')
azi = xr.DataArray([90.], coords={'azi': [90.]}, dims='azi')

process = radoc.Process(input_db=input_db, vza=vza, azi=azi)
process.execute()                  # default aerosol model proportions of config.yml
radcalnet_db = process.radcalnet_db

# convolution with the spectral response of the sensor bands
# (an xarray.Dataset for a multidimensional signal, a DataArray for one spectrum)
spectral = radoc.Spectral(central_wl=np.array([443., 490., 560., 665., 865.]), fwhm=20.)
Rtoa_bands = spectral.convolve2(radcalnet_db.Rtoa).Rtoa

The convolution is vectorized over all the spectra and also works on a simulation read lazily with dask, e.g. xr.open_mfdataset(files, chunks={'time': 1}).Rtoa (see Spectral convolution and the tutorial Sentinel-3/OLCI matchups with RadCalNet-OC).

When several simulations are run in the same Python session (e.g. one per month or per site), the parts of the atmosphere look-up table read by the first run are kept in memory (LUT.toa_lut) and the next runs do not read the file again.

The proportions of the aerosol models can be given explicitly, process.execute(aerosol_combination=[0, 0.5, 0, 0.5, 0, 0]), or retrieved from the AERONET spectral aerosol optical thickness with Aerosol (see Aerosol model mixture).

Output

Process.radcalnet_db is an xarray.Dataset at the full spectral resolution of the simulation (350–2500 nm):

Variable	Unit	Description (see Methods)
Rtoa	–	total reflectance at TOA, \(R_{toa}\)
Ratm	–	atmosphere (intrinsic + surface-reflected) reflectance at TOA, \(T_g^{\downarrow}T_g^{\uparrow}R_{atm}\)
Rrs	sr-1	remote-sensing reflectance used for the simulation
E0	mW m-2 nm-1	plane solar irradiance at TOA
Ed	mW m-2 nm-1	plane solar irradiance at the surface
D2	–	Earth-Sun distance correction factor
aerosol_combination	–	proportion of each aerosol model used for the simulation

together with the input atmospheric parameters (tcwv, tco3, tcno2, pressure, aot550, aot865, ang_exp).