Pyspectral Documentation

Transcription

1 Pyspectral Documentation Release Adam Dybbroe Apr 24, 2017

2

3 Contents 1 Installation The spectral response data Installation Configuration file Usage 5 3 Example with SEVIRI data Integration with MPOP Derivation of the 3.7 micron reflectance Derive the emissive part of the 3.7 micron band Brightness temperature to spectral radiance Determination of the in-band solar flux Rayleigh scattering correction A few words on the Rayleigh scattering simulations Some definitions Symbols and definitions used in Pyspectral Constants Central wavelength and central wavenumber Spectral Irradiance TOA Solar irridiance and solar constant In-band solar flux Planck radiation The inverse Planck function The pyspectral API Blackbody radiation Spectral responses Solar irradiance Near-Infrared reflectance Rayleigh scattering Utils Indices and tables 25 i

4 Python Module Index 27 ii

5 Pyspectral is a package to read meteorological satellite instrument relative spectral response functions and solar irradiance spectra, and e.g. provide functionality to derive the in-band solar flux for various satellite sensors. Among the sensors supported are VIIRS, MODIS, AVHRR, SEVIRI, AHI (Himawari). Since version it is also possible to apply atmospheric (Rayleigh scattering and aerosol absorption) correction in the 400 to 800 nanometer spectral range. This allows for the atmospheric correction of true color imagery of any sensor provided it has the necessary bands in this spectral range (e.g. MODIS, VIIRS and AHI). The source code of the module can be found on the github page. With pyspectral and mpop (or satpy) it is possible to make RGB colour composites like the SEVIRI day solar or the day microphysical RGB composites according to the MSG Interpretation Guide (EUMETSAT). Also with mpop and satpy integration it is possible to make Rayleigh corrected true color imagery. Contents 1

6 2 Contents

7 CHAPTER 1 Installation Pyspectral reads relative spectral response functions for various satellite sensors. The original agency specific spectral response data are stored in various formats (e.g. ascii, excel, or netcdf) and usually not following any agreed international standard. These data are usually available at the satellite agencies responsible for the instrument in question. That is for example EUMETSAT, NOAA, NASA, JMA and CMA. The Global Space-based Inter-Calibration System (GSICS) Coordination Center (GCC) holds a place with links to several relevant instrument response data. But far from all data are available through that web-site. The spectral response data So all these instrument relative spectral response data are stored in different formats with varying levels of detailed information available. Therefore, in order to make life easier for the pyspectral user we have defined one common internal hdf5 format. That way it is also easy to add support for new instruments. Currently the relative spectral reponses for Suomi-NPP VIIRS, all of the NOAA/TIROS-N and Metop AVHRRs, Terra/Aqua MODIS, Meteosat 8-11 SEVIRI, Sentinel-3A SLSTR and OLCI, Envisat AATSR, GOES-16 ABI, and Himawari-8 are available. The data are automagically downloaded and installed when needed. But if you need to specifically retrieve the data independently the data are available from the pyspectral rsr repository. (The md5sum of this gzipped tar file is fd45755a4dbde9010d266e8df). It is still also possible to download the original spectral responses from the various satellite operators instead and generate the internal hdf5 formatet files yourself. However, this should normaly never be needed. For SEVIRI on Meteosat download the data from eumetsat and unzip the Excel file. Installation Installation of the latest stable version is always done using: $> pip install pyspectral 3

8 Some static data are part of the package but both the Rayleigh correction coefficients and the spectral responses are downloaded and installed once pyspectral is being run the first time. On default these static data will reside in ~/.local/share/pyspectral. See further down. You can also choose to download the pyspectral source code from github: $> git clone git://github.com/adybbroe/pyspectral.git and then run: $> python setup.py install or, if you want to hack the package: $> python setup.py develop Configuration file A default configuration file pyspectral.cfg is installed automatically and being part of the package under the etc directory. In many cases the default settings will allow one to do all what is needed. However, it can easily be overwritten by making your own copy and set an environment variable pointing to this configuration file, as e.g.: $> PSP_CONFIG_FILE=/home/a000680/pyspectral.cfg; export PSP_CONFIG_FILE So, in case you want to download the internal pyspectral formatet relative spectral responses as well as the rayleighcorrection look-up-tables once and for all, and keep them somewhere else, here is what you need to do: $> cd /path/to/internal/rsr_data $> wget $> tar xvzf pyspectral_rsr_data.tgz $> cd /path/to/rayleigh/correction/luts $> cd rural_aerosol rayleigh_only $> cd rayleigh_only/ $> wget rayleigh_only.tgz $> tar xvzf rayleigh_luts_rayleigh_only.tgz $> cd../rural_aerosol $> wget rural_aerosol.tgz $> tar xvzf rayleigh_luts_rural_aerosol.tgz Then adjust the pyspectral.cfg so it looks something like this: [general] rsr_dir = /path/to/internal/rsr_data rayleigh_dir = /path/to/rayleigh/correction/luts download_from_internet = False 4 Chapter 1. Installation

9 CHAPTER 2 Usage A simple use case: >>> from pyspectral.rsr_reader import RelativeSpectralResponse >>> from pyspectral.solar import (SolarIrradianceSpectrum, TOTAL_IRRADIANCE_SPECTRUM_ 2000ASTM) >>> modis = RelativeSpectralResponse('EOS-Aqua', 'modis') >>> solar_irr = SolarIrradianceSpectrum(TOTAL_IRRADIANCE_SPECTRUM_2000ASTM, dlambda=0. 005) >>> sflux = solar_irr.inband_solarflux(modis.rsr['20']) >>> print("solar flux over Band: ", round(sflux, 6)) ('Solar flux over Band: ', ) And, here is how to derive the solar reflectance (removing the thermal part) of the Aqua MODIS 3.7 micron band: >>> from pyspectral.near_infrared_reflectance import Calculator >>> sunz = 80. >>> tb3 = >>> tb4 = >>> refl37 = Calculator('EOS-Aqua', 'modis', '20', detector='det-1', solar_flux= ) >>> print round(refl37.reflectance_from_tbs(sunz, tb3, tb4), 6) And, here is how to derive the rayleigh (with additional optional aerosol absorption) contribution in a short wave band: >>> from pyspectral import rayleigh >>> rcor = rayleigh.rayleigh('goes-16', 'abi') >>> import numpy as np >>> sunz = np.array([[50., 60.], [51., 61.]]) >>> satz = np.array([[40., 50.], [41., 51.]]) >>> azidiff = np.array([[160, 160], [160, 160]]) >>> blueband = np.array([[0.1, 0.15], [0.11, 0.16]]) >>> print rcor.get_reflectance(sunz, satz, azidiff, 'ch2', blueband) [[ ] [ ]] 5

10 6 Chapter 2. Usage

11 CHAPTER 3 Example with SEVIRI data Let us try calculate the 3.9 micron reflectance for Meteosat-10: >>> sunz = 80. >>> tb3 = >>> tb4 = >>> from pyspectral.near_infrared_reflectance import Calculator >>> refl39 = Calculator('Meteosat-10', 'seviri', 'IR3.9') >>> print('%4.3f' %refl39.reflectance_from_tbs(sunz, tb3, tb4)) You can also provide the in-band solar flux from outside when calculating the reflectance, saving a few milliseconds per call: >>> from pyspectral.solar import (SolarIrradianceSpectrum, TOTAL_IRRADIANCE_SPECTRUM_ 2000ASTM) >>> solar_irr = SolarIrradianceSpectrum(TOTAL_IRRADIANCE_SPECTRUM_2000ASTM, dlambda= ) >>> from pyspectral.rsr_reader import RelativeSpectralResponse >>> seviri = RelativeSpectralResponse('Meteosat-10', 'seviri') >>> sflux = solar_irr.inband_solarflux(seviri.rsr['ir3.9']) >>> refl39 = Calculator('Meteosat-10', 'seviri', 'IR3.9', solar_flux=sflux) >>> print('%4.3f' %refl39.reflectance_from_tbs(sunz, tb3, tb4)) Integration with MPOP The mpop package integrates pyspectral so that it is very easy with only a very few lines of code to make RGB images with the 3.9 reflectance as one of the bands. Here we show you how this can be done using the built-in snow RGB using the 0.8 micron, the 1.6 micron and the 3.9 micron reflectance derived using pyspectral: >>> from mpop.satellites import GeostationaryFactory >>> from datetime import datetime 7

12 >>> from mpop.projector import get_area_def >>> europe = get_area_def("europecanary") >>> tslot = datetime(2015, 4, 20, 10, 0) >>> glbd = GeostationaryFactory.create_scene("Meteosat-10", "", "seviri", tslot) >>> glbd.load(['vis006', 'VIS008', 'IR_016', 'IR_039', 'IR_108', 'IR_134'], area_ extent=europe.area_extent) >>> area = "germ" >>> lcd = glbd.project(area) >>> img = lcd.image.snow() >>> img.show() _static/mpop_germ_day_snow_thumb.png The magic is all happening when calling lcd.image.snow() which use instruments/compositer.py inside mpop. If you want to customize your own RGB using the r3.9 reflectance you can follow the example below. We will here need pyorbital as well in order to get the sun zenith angles: >>> from mpop.satellites import GeostationaryFactory >>> from datetime import datetime >>> from mpop.projector import get_area_def >>> from mpop.imageo.geo_image import GeoImage >>> from pyorbital.astronomy import sun_zenith_angle as sza >>> import numpy as np >>> europe = get_area_def("europecanary") >>> tslot = datetime(2015, 4, 20, 10, 0) >>> glbd = GeostationaryFactory.create_scene("Meteosat-10", "", "seviri", tslot) >>> glbd.load(area_extent=europe.area_extent) >>> area = "germ" >>> lcd = glbd.project(area) So, now the data are loaded and remapped on the germ area, just as before, and we can start getting the 3.9 micron reflectance and the sun zenith angles, and then generate the RGB image: >>> r39 = lcd[3.9].get_reflectance(lcd[10.8].data, sun_zenith=none, tb13_4=lcd[13.4]. data) >>> lonlats = lcd[3.9].area.get_lonlats() >>> sunz = sza(tslot, lonlats[0], lonlats[1]) >>> sunz = np.ma.masked_outside(sunz, 0.0, 88.0) >>> sunzmask = sunz.mask >>> sunz = sunz.filled(88.) >>> costheta = np.cos(np.deg2rad(sunz)) >>> red = np.ma.masked_where(sunzmask, lcd[0.8].data / costheta) >>> green = np.ma.masked_where(sunzmask, lcd[1.6].data / costheta) >>> img = GeoImage((red, green, r39 * 100), area, tslot, crange=((0, 100), (0, 70), (0, 30)), fill_value=(0, 0, 0), mode="rgb") >>> img.enhance(gamma=1.7) >>> img.show() 8 Chapter 3. Example with SEVIRI data

13 CHAPTER 4 Derivation of the 3.7 micron reflectance The monochromatic reflectivity (or reflectance) ρ λ is the ratio of the reflected (backscattered) radiance to the incident radiance. In the case of solar reflection one can write: L λ ρ λ = μ 0 L λ0 where L λ is the measured radiance, L λ0 is the incoming solar radiance, and μ 0 is the cosine of the solar zenith angle θ 0. Assuming the solar radiance is independent of direction, the equation for the reflectance can be written in terms of the solar flux F λ0 : ρ λ = L λ 1 π μ 0F λ0 For the 3.7μm channel the outgoing radiance is due to solar reflection and thermal emission. Thus in order to determine a 3.7μm channel reflectance, it is necessary to subtract the thermal part from the satellite signal. To do this, the temperature of the observed object is needed. The usual candidate at hand is the 11μm brightness temperature (e.g. VIIRS I5 or M12), since most objects behave approximately as blackbodies in this spectral interval. The 3.7μm channel reflectance may then be written as ρ 3.7 = L 3.7 ε 3.7 Φ (λ)b λ (T 11 )dλ 1 π μ 0F 3.7,0 where L 3.7 is the measured radiance at 3.7μm, Φ 3.7 (λ) is the 3.7μm channel spectral response function, B λ is the Planck radiation, and T 11 is the 11μm channel brightness temperature. If the observed object is optically thick (transmittance equals zero) then: ε 3.7 = 1 ρ 3.7 and then ρ 3.7 = L 3.7 Φ (λ)b λ (T 11 )dλ 1 π μ 0F 3.7,0 Φ (λ)b λ (T 11 )dλ 9

14 Derive the emissive part of the 3.7 micron band Now that we have the reflective part of the 3.x signal, it is easy to derive the emissive part, under the same assumptions of completely opaque (zero transmissivity) objects. L 3.7,thermal = (1 ρ 3.7 ) 0 Φ 3.7 (λ)b λ (T 11 )dλ Brightness temperature to spectral radiance If the satellite observation is given in terms of the brightness temperature, then the corresponding spectral radiance can be derived by convolving the relative spectral response with the Planck function and diving by the equivalent band width: L 3.7 = where the equivalent band width λ is defined as: 0 λ = Φ 3.7 (λ)b λ (T 3.7 )dλ λ 0 Φ 3.7 (λ)dλ This gives the spectral radiance given the brightness temperature and may be expressed in W/m 2 μm 1. In order to get the total radiance over the band one has to multiply with the equivalent band width. Inserting the Planck radiation: L 3.7 = 2hc 2 0 Φ 3.7(λ) λ 5 λ dλ hc e λk B (T 3.7 ) 1 This is expressed in wavelength space. But the spectral radiance can also be given in terms of the wavenumber ν, provided the relative spectral response is given as a function of ν: L ν(3.7) = where the equivalent band width ν is defined as: and inserting the Planck radiation: 0 ν = Φ 3.7 (ν)b ν (T 3.7 )dν ν 0 Φ 3.7 (ν)dν L ν(3.7) = 2h ν c Φ (ν) 3 dν hc ν e λk B T :3.7 1 Determination of the in-band solar flux The solar flux (SI unit W m ) over a spectral sensor band can be derived by convolving the top of atmosphere spectral 2 irradiance and the sensor relative spectral response curve, so for the 3.7μm band this would be: F 3.7 = where S(λ) is the spectral solar irradiance. 0 Φ 3.7 (λ)s(λ)dλ 10 Chapter 4. Derivation of the 3.7 micron reflectance

15 CHAPTER 5 Rayleigh scattering correction In particular at the shorter wavelengths around nm, which include the region used e.g. for ocean color products or true color imagery, the Rayleigh scattering due to atmospheric molecules or atoms becomes significant. As this atmospheric scattering is obscuring the retrieval of surface parameters and since it is strongly dependent on observation geometry, it is custom to try to correct or subtract this unwanted signal from the data before performing the geophysical retrieval. In order to correct for the Rayleigh scattering we have simulated the solar reflectance under various sun-satellite viewing conditions for a set of different standard atmospheres, using a radiative transfer model. For a given atmosphere the reflectance is dependent on wavelenght, solar-zenith angle, satellite zenith angle, and the relative sun-satellite azimuth difference angle: σ = σ(θ 0, θ, φ, λ) The relative sun-satellite azimuth difference angle is defined as illustrated in the figure below: To apply the rayleigh correction for a given satellite sensor band, the procedure involves the following three steps: Find the effective wavelength of the band Derive the Rayleigh scattering part Subtract that from the observations As the Rayleigh scattering is proportional to 1 λ the effective wavelength is derived by convolving the spectral response 4 with 1 λ. 4 To get the Rayleigh scattering contribution for an arbitrary band, first the solar zenith, satellite zenith and the sunsatellite azimuth difference angles should be loaded. For the VIIRS M2 band the interface looks like this: >>> from pyspectral.rayleigh import Rayleigh >>> viirs = Rayleigh('Suomi-NPP', 'viirs') >>> refl_cor_m2 = viirs.get_reflectance(sunz, satz, ssadiff, 'M2') This rayleigh contribution should then of course be subtracted from the data. Optionally the blueband can be provided as the fifth argument, which will provide a more gentle scaling in cases of high reflectances (above 20%): 11

16 >>> refl_cor_m2 = viirs.get_reflectance(sunz, satz, ssadiff, 'M2', blueband) In case you do not know the name of the band (defined in the pyspectral rsr files) you can provide the approximate band frequency in micro meters: >>> refl_cor_m2 = viirs.get_reflectance(sunz, satz, ssadiff, 0.45, blueband) At the moment we have done simulations for a set of standard atmospheres in two different configuration, one only considering rayleigh scattering, and one also accounting for aerosols. On default we use the simulations without aerosol absorption, but it is possible to specify if you want the other setup, e.g.: >>> from pyspectral.rayleigh import Rayleigh >>> viirs = Rayleigh('Suomi-NPP', 'viirs', atmosphere='midlatitude summer', rural_ aerosol=true) >>> refl_cor_m2 = viirs.get_reflectance(sunz, satz, ssadiff, 0.45, blueband) 12 Chapter 5. Rayleigh scattering correction

17 A few words on the Rayleigh scattering simulations _static/refl_subarctic_winter_lambda_0400_ssa_180.png 5.1. A few words on the Rayleigh scattering simulations 13

18 _static/refl_subarctic_winter_lambda_0500_ssa_180.png 14 Chapter 5. Rayleigh scattering correction

19 CHAPTER 6 Some definitions In radiation physics there is unfortunately several slightly different ways of presenting the theory. For instance, there is no single custom on the mathematical symbolism, and various different non SI-units are used in different situations. Here we present just a few terms and definitions with relevance to Pyspectral, and how to possible go from one common representation to another. Symbols and definitions used in Pyspectral λ Wavelength (μm) ν = 1 λ Wavenumber (cm 1 ) λ c Central wavelength for a given band/channel (μm) ν c Central wavelength for a given band/channel (cm 1 ) Φ i (λ) Relative spectral response for band i as a function of wavelength E λ Spectral irradiance at wavelength λ (W/m 2 μm 1 ) E ν Spectral irradiance at wavenumber ν (W/m 2 (cm 1 ) 1 ) B λ Blackbody radiation at wavelength λ (W/m 2 μm 1 ) B ν Blackbody radiation at wavenumber ν (W/m 2 (cm 1 ) 1 ) L ν Spectral radiance at wavenumber ν (W/m 2 sr 1 (cm 1 ) 1 ) L λ Spectral radiance at wavelength λ (W/m 2 sr 1 μm 1 ) Constants k B Boltzmann constant ( e23) h Planck constant ( e 34) c Speed of light in vacuum ( e8) 15

20 Central wavelength and central wavenumber The central wavelength for a given spectral band (i) of a satellite sensor is defined as: Likewise the central wavenumber is: λ ci = ν ci = Φ i (λ)λdλ Φ i (λ)dλ Φ i (ν)νdν Φ i (ν)dν And since ν = 1/λ, we can express the central wavenumber using the spectral response function expressed in wavelength space, as: ν ci = 0 0 Φ i (λ) 1 λ 3 dλ Φ i (λ) 1 λ 2 dλ And from this we see that in general ν c 1/λ c. Taking SEVIRI as an example, and looking at the visible channel on Meteosat-8, we see that this is indeed true: >>> from pyspectral.rsr_reader import RelativeSpectralResponse >>> from pyspectral.utils import convert2wavenumber, get_central_wave >>> seviri = RelativeSpectralResponse('Meteosat-8', 'seviri') >>> print get_central_wave(seviri.rsr['vis0.6']['det-1']['wavelength'], seviri.rsr[ 'VIS0.6']['det-1']['response']) >>> rsr, info = convert2wavenumber(seviri.rsr) >>> print info {'si_scale': 100.0, 'unit': 'cm-1'} >>> wvc = get_central_wave(rsr['vis0.6']['det-1']['wavenumber'], rsr['vis0.6']['det-1 ']['response']) >>> print wvc >>> print 1./wvc*1e This was using the pyspectral unified HDF5 formated spectral response data. If you want to use the original spectral response data from EUMETSAT the code may look like this: >>> from pyspectral.seviri_rsr import Seviri >>> seviri = Seviri() >>> print seviri.central_wavelength['vis0.6']['meteosat-8'] >>> seviri = Seviri(wavespace='wavenumber') >>> print seviri.central_wavenumber['vis0.6']['meteosat-8'] >>> print 1./seviri.central_wavenumber['VIS0.6']['Meteosat-8']*1e Spectral Irradiance We denote the spectral irradiance E which is a function of wavelength or wavenumber, depending on what representation is used. In Pyspectral the aim is to support both representations. The units are of course dependent of which representation is used. 16 Chapter 6. Some definitions

21 In wavelength space we write E(λ) and it is given in units of W/m 2 μm 1. In wavenumber space we write E(ν) and it is given in units of W/m 2 (cm 1 ) 1. To convert a spectral irradiance E λ0 at wavelengh λ 0 to a spectral irradiance E ν0 at wavenumber ν 0 = 1/λ 0 the following relation applies: E ν = E λ λ 2 And if the units are not SI but rather given by the units shown above we have to account for a factor of 10 as: E ν = E λ λ 2 * 0.1 TOA Solar irridiance and solar constant First, the TOA solar irradiance in wavelength space: >>> from pyspectral.solar import (SolarIrradianceSpectrum, TOTAL_IRRADIANCE_ SPECTRUM_2000ASTM) >>> solar_irr = SolarIrradianceSpectrum(TOTAL_IRRADIANCE_SPECTRUM_2000ASTM, dlambda=0.0005) >>> print("%6.2f" % solar_irr.solar_constant()) >>> solar_irr.plot('/tmp/solar_irradiance.png') The solar constant is in units of W/m 2. Instead when expressing the irradiance in wavenumber space using wavenumbers in units of cm 1 the solar flux is in units of mw/m 2 : >>> solar_irr = SolarIrradianceSpectrum(TOTAL_IRRADIANCE_SPECTRUM_2000ASTM, dlambda=0.0005, wavespace='wavenumber') >>> print solar_irr.solar_constant() >>> solar_irr.plot('/tmp/solar_irradiance_wnum.png') 6.5. TOA Solar irridiance and solar constant 17

22 In-band solar flux W The solar flux (SI unit m ) over a spectral sensor band can be derived by convolving the top of atmosphere solar 2 spectral irradiance and the sensor relative spectral response. For band i: F i = 0 Φ i (λ)e(λ)dλ where E(λ) is the TOA spectral solar irradiance at a sun-earth distance of one astronomical unit (AU). In python code it may look like this: >>> from pyspectral.rsr_reader import RelativeSpectralResponse >>> from pyspectral.utils import convert2wavenumber, get_central_wave >>> seviri = RelativeSpectralResponse('Meteosat-8', 'seviri') >>> rsr, info = convert2wavenumber(seviri.rsr) >>> from pyspectral.solar import (SolarIrradianceSpectrum, TOTAL_IRRADIANCE_SPECTRUM_ 2000ASTM) >>> solar_irr = SolarIrradianceSpectrum(TOTAL_IRRADIANCE_SPECTRUM_2000ASTM, dlambda= , wavespace='wavenumber') >>> print solar_irr.inband_solarflux(rsr['vis0.8']) Planck radiation Planck s law describes the electromagnetic radiation emitted by a black body in thermal equilibrium at a definite temperature. Thus for wavelength λ the Planck radiation or Blackbody radiation B(λ) can be written as: B λ (T ) = 2hc2 λ 5 1 e hc λk B T 1 18 Chapter 6. Some definitions

23 and expressed as a function of wavenumber ν: In python it may look like this: B ν (T ) = 2hc 2 ν 3 1 e hcν k B T 1 >>> from pyspectral.blackbody import blackbody_wn >>> wavenumber = >>> rad = blackbody_wn((wavenumber, ), [300., 301]) >>> print rad [ ] Which are the spectral radiances in SI units at wavenumber around 909cm 1 at temperatures 300 and 301 Kelvin. In units of mw/m 2 (cm 1 ) 1 sr 1 this becomes: >>> print rad*1e+5 [ ] And using wavelength representation: >>> from pyspectral.blackbody import blackbody >>> wvl = 1./wavenumber >>> rad = blackbody(wvl, [300., 301]) >>> print rad [ ] Which are the spectral radiances in SI units around 11μm at temperatures 300 and 301 Kelvin. mw/m 2 m 1 sr 1 this becomes: In units of >>> print rad*1e-6 [ ] The inverse Planck function Inverting the Planck function allows to derive the brightness temperature given the spectral radiance. Expressed in wavenumber space this becomes: T B = T (B ν ) = hcν k B log 1 { 2hc2 ν 3 B ν + 1} With the spectral radiance given as a function of wavelength the equation looks like this: In python it may look like this: T B = T (B λ ) = hc λk B log 1 { 2hc2 B λ λ 5 + 1} >>> from pyspectral.blackbody import blackbody_wn_rad2temp >>> wavenumber = >>> temp = blackbody_wn_rad2temp(wavenumber, [ , ]) >>> print temp [ ] Provided the input is a central wavenumber or wavelength as defined above, this gives the brightness temperature calculation under the assumption of a linear planck function as a function of wavelength or wavenumber over the spectral 6.8. The inverse Planck function 19

24 band width and provided a constant relative spectral response. To get a more precise derivation of the brightness temperature given a measured radiance one needs to convolve the inverse Planck function with the relative spectral response function for the band in question: or T B = 0 Φ i (λ)t (B λ )dλ Φ 0 i (λ)dλ T B = T (B ν ) = 0 Φ i (ν)t (B ν )dν Φ 0 i (ν)dν 20 Chapter 6. Some definitions

25 CHAPTER 7 The pyspectral API Blackbody radiation Planck radiation equation pyspectral.blackbody.blackbody(wavel, temp) The Planck radiation or Blackbody radiation as a function of wavelength SI units. blackbody(wavelength, temperature) wavel = Wavelength or a sequence of wavelengths (m) temp = Temperature (scalar) or a sequence of temperatures (K) Output: The spectral radiance per meter (not micron!) Unit = W/m^2 sr^-1 m^-1 pyspectral.blackbody.blackbody_rad2temp(wavelength, radiance) Derive brightness temperatures from radiance using the Planck function. Wavelength space. Assumes SI units as input and returns temperature in Kelvin pyspectral.blackbody.blackbody_wn(wavenumber, temp) The Planck radiation or Blackbody radiation as a function of wavenumber SI units! blackbody_wn(wavnum, temperature) wavenumber = A wavenumber (scalar) or a sequence of wave numbers (m-1) temp = A temperatfure (scalar) or a sequence of temperatures (K) Output: The spectral radiance in Watts per square meter per steradian per m-1: (m^-1)^-1 = W/m sr^-1 Unit = W/m^2 sr^-1 Converting from SI units to mw/m^2 sr^-1 (cm^-1)^-1: 1.0 W/m^2 sr^-1 (m^-1)^-1 = 0.1 mw/m^2 sr^-1 (cm^-1)^-1 pyspectral.blackbody.blackbody_wn_rad2temp(wavenumber, radiance) Derive brightness temperatures from radiance using the Planck function. Wavenumber space Spectral responses Reading the spectral responses in the internal pyspectral hdf5 format 21

26 class pyspectral.rsr_reader.relativespectralresponse(platform_name, instrument) Container for the relative spectral response functions for various satellite imagers convert() Convert spectral response functions from wavelength to wavenumber integral(bandname) Calculate the integral of the spectral response function for each detector. load() Read the internally formatet hdf5 relative spectral response data pyspectral.rsr_reader.main() Main SEVIRI Interface to the SEVIRI spectral response functions for all four MSG satellites class pyspectral.seviri_rsr.seviri(wavespace= wavelength ) Class for Seviri RSR convert2wavenumber() Convert from wavelengths to wavenumber get_centrals() Get the central wavenumbers or central wavelengths of all channels, depending on the given wavespace pyspectral.seviri_rsr.generate_seviri_file(seviri, platform_name) Generate the pyspectral internal common format relative response function file for one SEVIRI pyspectral.seviri_rsr.get_central_wave(wavl, resp) Calculate the central wavelength or the central wavenumber, depending on what is input pyspectral.seviri_rsr.main() Main VIIRS Interface to VIIRS relative spectral responses class pyspectral.viirs_rsr.viirsrsr(bandname, platform_name= Suomi-NPP ) Container for the (S-NPP) VIIRS RSR data pyspectral.viirs_rsr.main() Main AVHRR Solar irradiance Module to read solar irradiance spectra and calculate the solar flux over various instrument bands given their relative spectral response functions class pyspectral.solar.solarirradiancespectrum(filename, **options) Total Top of Atmosphere (TOA) Solar Irradiance Spectrum Wavelength is in units of microns (10^-6 m). The spectral Irradiance in the file TOTAL_IRRADIANCE_SPECTRUM_2000ASTM is in units of W/m^2/micron 22 Chapter 7. The pyspectral API

27 convert2wavenumber() Convert from wavelengths to wavenumber. Units: Wavelength: micro meters (1e-6 m) Wavenumber: cm-1 inband_solarflux(rsr, scale=1.0, **options) Derive the inband solar flux for a given instrument relative spectral response valid for an earth-sun distance of one AU. inband_solarirradiance(rsr, scale=1.0, **options) Derive the inband solar irradiance for a given instrument relative spectral response valid for an earth-sun distance of one AU. interpolate(**options) Interpolate Irradiance to a specified evenly spaced resolution/grid This is necessary to make integration and folding (with a channel relative spectral response) straightforward. dlambda = wavelength interval in microns start = Start of the wavelength interval (left/lower) end = End of the wavelength interval (right/upper end) options: dlambda: Delta wavelength used when interpolating/resampling ival_wavelength: Tuple. The start and end interval in wavelength space, defining where to integrate/convolute the spectral response curve on the spectral irradiance data. plot(plotname=none, **options) Plot the data solar_constant() Calculate the solar constant Near-Infrared reflectance Derive the Near-Infrared reflectance of a given band in the solar and thermal range (usually the micron band) using a thermal atmospheric window channel (usually around microns). class pyspectral.near_infrared_reflectance.calculator(platform_name, instrument, band, solar_flux=none, **kwargs) A thermal near-infrared (e.g. 3.7 micron) band reflectance calculator. Given the relative spectral response of the NIR band, the solar zenith angle, and the brightness temperatures of the NIR and the Thermal bands, derive the solar reflectance for the NIR band removing the thermal (terrestrial) part. The in-band solar flux over the NIR band is optional. If not provided, it will be calculated here! The relfectance calculated is without units and should be between 0 and 1. derive_rad39_corr(bt11, bt13, method= rosenfeld ) Derive the 3.9 radiance correction factor to account for the attenuation of the emitted 3.9 radiance by CO2 absorption. Requires the 11 micron window band and the 13.4 CO2 absorption band, as e.g. available on SEVIRI. Currently only supports the Rosenfeld method emissive_part_3x(tb=true) Get the emissive part of the 3.x band reflectance_from_tbs(sun_zenith, tb_near_ir, tb_thermal, tb_ir_co2=none) The relfectance calculated is without units and should be between 0 and 1. Inputs: sun_zenith: Sun zenith angle for every pixel - in degrees tb_near_ir: The 3.7 (or 3.9 or equivalent) IR Tb s at every pixel (Kelvin) 7.4. Near-Infrared reflectance 23

28 tb_thermal: The 10.8 (or 11 or 12 or equivalent) IR Tb s at every pixel (Kelvin) tb_ir_co2: The 13.4 micron channel (or similar - co2 absorption band) brightness temperatures at every pixel. If None, no CO2 absorption correction will be applied. Rayleigh scattering Utils Utility functions pyspectral.utils.convert2hdf5(classin, platform_name, bandnames, scale=1e-06) Retrieve original RSR data and convert to internal hdf5 format. scale is the number which has to be multiplied to the wavelength data in order to get it in the SI unit meter pyspectral.utils.convert2wavenumber(rsr) Take rsr data set with all channels and detectors for an instrument each with a set of wavelengths and normalised responses and convert to wavenumbers and responses pyspectral.utils.download_luts() Download the luts from internet. pyspectral.utils.download_rsr() Download the pre-compiled hdf5 formatet relative spectral response functions from the internet pyspectral.utils.get_bandname_from_wavelength(wavelength, rsr, epsilon=0.1) Get the bandname from h5 rsr provided the approximate wavelength. pyspectral.utils.get_central_wave(wav, resp, weight=1.0) Calculate the central wavelength or the central wavenumber, depending on which parameters is input. On default the weighting funcion is f(lambda)=1.0, but it is possible to add a custom weight, e.g. f(lambda) = 1./lambda**4 for Rayleigh scattering calculations pyspectral.utils.get_rayleigh_reflectance(parms, azidiff, sunz, satz) Get the Rayleigh reflectance applying the polynomial fit parameters P(x,y) = c_{00} + c_{10}x c_{n0}x^n + c_{01}y c_{0n}y^n + c_{11}xy + c_{12}xy^ c_{1(n-1)}xy^{n-1} c_{(n-1)1}x^{n-1}y x = relative azimuth difference angle: Azimuth difference 0: Instrument is looking into Sun Azimuth difference 180: Instrument and Sun are looking in the same direction y = secant of the satellite zenith angle NB! The azimuth difference provided here is defined as described in the documentation, and differs by 180 degrees to the angle x required in the polynomial fit. pyspectral.utils.sort_data(x_vals, y_vals) Sort the data so that x is monotonically increasing and contains no duplicates. 24 Chapter 7. The pyspectral API

29 CHAPTER 8 Indices and tables genindex modindex search 25

30 26 Chapter 8. Indices and tables

31 Python Module Index p pyspectral.blackbody, 21 pyspectral.near_infrared_reflectance, 23 pyspectral.rsr_reader, 21 pyspectral.seviri_rsr, 22 pyspectral.solar, 22 pyspectral.utils, 24 pyspectral.viirs_rsr, 22 27

32 28 Python Module Index

33 Index B blackbody() (in module pyspectral.blackbody), 21 blackbody_rad2temp() (in module pyspectral.blackbody), 21 blackbody_wn() (in module pyspectral.blackbody), 21 blackbody_wn_rad2temp() (in module pyspectral.blackbody), 21 D C Calculator (class in pyspectral.near_infrared_reflectance), 23 convert() (pyspectral.rsr_reader.relativespectralresponse method), 22 convert2hdf5() (in module pyspectral.utils), 24 convert2wavenumber() (in module pyspectral.utils), 24 convert2wavenumber() (pyspectral.seviri_rsr.seviri method), 22 convert2wavenumber() (pyspectral.solar.solarirradiancespectrum method), 22 derive_rad39_corr() (pyspectral.near_infrared_reflectance.calculator method), 23 download_luts() (in module pyspectral.utils), 24 download_rsr() (in module pyspectral.utils), 24 E emissive_part_3x() (pyspectral.near_infrared_reflectance.calculator method), 23 G generate_seviri_file() (in module pyspectral.seviri_rsr), 22 get_bandname_from_wavelength() (in module pyspectral.utils), 24 get_central_wave() (in module pyspectral.seviri_rsr), 22 get_central_wave() (in module pyspectral.utils), 24 get_centrals() (pyspectral.seviri_rsr.seviri method), 22 get_rayleigh_reflectance() (in module pyspectral.utils), 24 I inband_solarflux() (pyspectral.solar.solarirradiancespectrum method), 23 inband_solarirradiance() (pyspectral.solar.solarirradiancespectrum method), 23 integral() (pyspectral.rsr_reader.relativespectralresponse method), 22 interpolate() (pyspectral.solar.solarirradiancespectrum method), 23 L load() (pyspectral.rsr_reader.relativespectralresponse method), 22 M main() (in module pyspectral.rsr_reader), 22 main() (in module pyspectral.seviri_rsr), 22 main() (in module pyspectral.viirs_rsr), 22 P plot() (pyspectral.solar.solarirradiancespectrum method), 23 pyspectral.blackbody (module), 21 pyspectral.near_infrared_reflectance (module), 23 pyspectral.rsr_reader (module), 21 pyspectral.seviri_rsr (module), 22 pyspectral.solar (module), 22 pyspectral.utils (module), 24 pyspectral.viirs_rsr (module), 22 R reflectance_from_tbs() (pyspectral.near_infrared_reflectance.calculator 29

34 method), 23 RelativeSpectralResponse (class in pyspectral.rsr_reader), 21 S Seviri (class in pyspectral.seviri_rsr), 22 solar_constant() (pyspec- method), tral.solar.solarirradiancespectrum 23 SolarIrradianceSpectrum (class in pyspectral.solar), 22 sort_data() (in module pyspectral.utils), 24 V ViirsRSR (class in pyspectral.viirs_rsr), Index