oDepth
index
/users/schrei_f/src/py4CAtS/lite/src/oDepth.py

oDepth
 
Read and convert / plot / write molecular optical depth (e.g., to reformat or plot).
 
usage:
oDepth [options] od_file(s)
 
command line options:
  -c  char(s)   comment character in input file(s) (default #)
  -f  string    format for output file [default: 'xy']
  -h            help
  -m  char      "a|A"   accumulate delta optical depth to cumulative optical depth
                        from bottom --> top OR top --> bottom
                "d|D"   convert cumulative optical depth to delta optical depth
                "s|S"   sum delta optical depth to total path optical depth       (default!)
                "r|R"   revert accumulated optical depths
                "t"     convert optical depths to transmissions = exp(-od)
                "T"     sum delta optical depth to total and convert to transmission = exp(-od)
                "1"     locate (approximately) the altitude/distance where od=1 (for uplooking view)
 --BoA  float   bottom-of-atmosphere altitude [km]  (read opt.depth only for levels above)
 --ToA  float   top-of-atmosphere altitude [km]     (read opt.depth only for levels below)
                NOTE:  no interpolation, i.e. integration starts/stops at the next level above/below BoA/ToA
  -i   string   interpolation method for spectral domain (optical depth vs wavenumber)
  -n            convert x axis from wavenumber to wavelength[nanometer]
                NOTE: if the input x is already wavelength[nanometer], then the new x is converted back to wavenumber!
  -o  file      output file (default: standard output)
  -p            matplotlib for quicklook of input optical depth(s)
  -P            matplotlib for quicklook of output optical depth(s) or transmission/weighting function
  -r            on output reverse layer optical depth order:  top <--> bottom of atmosphere
  -x  Interval  lower,upper wavenumbers/wavelengths (comma separated pair of floats, no blanks!)
 --xFormat string  format to be used for wavenumbers,   default '%12f'   (only for ascii tabular)
 --yFormat string  format to be used for optical depth, default '%11.5f' (only for ascii tabular)
  -z  float     zenith angle:  scale optical depth by 1/cos(zenithAngle)   (0dg=uplooking, 180dg=downlooking)
 
optical depth files:
*   xy formatted ascii file with wavenumbers in column 1 and optical depth(s) (for some layers) in the following column(s).
*   pickled optical depth
*   [ netcdf formatted optical depth file ]
 
NOTES:
*  If no output file is specified, only a summary 'statistics' is given !!!
 
WARNING:
oDepth does NOT know the type of optical depth (delta or accumulated ...) given in the input file!
 
CAUTION:    mode='t' for oDepth -> transmission is inconsistent with mode='t' for total/sum oDepth
            in the lbl2od and ac2od modules

 
Classes
       
numpy.ndarray(builtins.object)
odArray

 
class odArray(numpy.ndarray)
    A subclassed numpy array of optical depths with xLimits, z, p, T, ... attributes added.
The z, p, t attributes here contain the corresponding height, pressure, temperature intervals!
 
Furthermore, some convenience functions are implemented:
*  info:     print the attributes and the minimum and maximum od values
*  dx:       return wavenumber grid point spacing
*  grid:     return a numpy array with the uniform wavenumber grid
*  regrid:   return an odArray with the od data interpolated to a new grid (same xLimits!)
#  truncate: return an odArray with the wavenumber range (xLimits) truncated
*  __eq__:   the equality test accepts 0.1% differences of pressure and all od values
 
 
Method resolution order:
odArray
numpy.ndarray
builtins.object

Methods defined here:
__add__(self, other)
Add two layer optical depths spectra and also 'combine' the layer bounds (z, p, T).
__array_finalize__(self, obj)
None.
__eq__(self, other)
Compare optical depth including its attributes.
(For p and od relative differences < 0.1% are seen as 'equal')
__mul__(self, other)
Multiply optical depth spectrum, e.g. to 'mimick' a slant path
(NOTE: attributes are copied without any change).
__rmul__(self, other)
Return value*self.
__str__(self)
Return str(self).
__sub__(self, other)
Subtract two layer optical depths spectra and also 'reduce' the layer bounds (z, p, T).
convolve(self, hwhm=1.0, srf='Box')
Return optical depth convolved with a spectral response function of half width @ half maximum:
More precisely:  convolve absorption=1-transmission=1-exp(-od) and return -log(1-<abs>)
dx(self)
Return wavenumber grid point spacing.
grid(self)
Setup a uniform, equidistant wavenumber grid.
info(self)
Return basic information (z, p, T, wavenumber and oDepth range).
oldRegrid(self, new, method='l', yOnly=False)
Interpolate optical depth to (usually denser) uniform, equidistant wavenumber grid.
regrid(self, new, method='l', yOnly=False)
Interpolate optical depth to (usually denser) uniform, equidistant wavenumber grid.
truncate(self, xLimits)
Return an optical depth in a truncated (smaller) wavenumber interval.

 
Functions
       
ceil(...)
ceil(x)
 
Return the ceiling of x as an Integral.
This is the smallest integer >= x.
cod2dod(codList)
Subtract consecutive cumulated optical depths to delta (layer) optical depths and return a list of odArray's.
dod2cod(dodList, back=False)
Accumulate all delta (layer) optical depths to cumulative optical depths and return a list of odArray's.
 
back=False    start accumulating with the very first layer (default)
              ===> the last element in the list returned should be the total optical depth
back=True     start accumulating with the very last layer
              ===> the first element in the list returned should be the total optical depth
dod2tod(dodList, interpol='l')
Sum all delta (layer) optical depths to the total optical depth.
Returns an odArray with the spectrum on the densest grid (typically corresponding to the highest layer)
flipod(dodList)
Flip a list of (delta) optical depths (odArray instances) up-down.
(In contrast to the 'simple' dodList[::-1] this function also swaps the z,p,t attributes)
oDepth(optDepth, mode='', interpol='l')
Manipulate optical depth:  convert cumulative <--> delta <--> sum (total).
 
ARGUMENTS:
----------
optDepth:    differential (or cumulative) optical depth
mode:        character triggering the transformation
             "a|A"   accumulate delta optical depth to cumulative optical depth
                     from bottom --> top OR top --> bottom
             "d|D"   convert cumulative optical depth to delta optical depth
             "s|S"   sum delta optical depth to total path optical depth
             "r|R"   revert accumulated optical depths
             "t"     convert optical depth to transmission = exp(-od)
             "T"     sum delta optical depth to total and convert to transmission = exp(-od)
             "1"     locate (approximately) the altitude/distance where od=1 (for uplooking view)
 
NOTE:
-----
This functions assumes that 'optDepth' is the delta|layer optical depth (the default output of lbl2od)
Only if you request mode='d' or 'r', then the input is assumed to be cumulative optical depth
 
CAUTION:    mode='t' for oDepth -> transmission is inconsistent with mode='t' for total/sum oDepth
            in the lbl2od, xs2od, ac2od functions
oDepthOne(dodList, nadir=False, interpol='l', extrapolate=False, verbose=False)
For each wavenumber scan (cumulative) optical depth as a function of altitude distance
and return distance from observer to OD=1.0
 
ARGUMENTS:
----------
dodList:      delta / layer optical depth, a list of odArray instances
nadir:        flag, default uplooking (zenith), alternative downlooking
interpol:     string or number (2|3|4) indicating interpolation method
extrapolate:  flag; default False, i.e. return 'inf'
verbose:      flag; default False
 
RETURNS:
--------
distances     [cm]
 
NOTES:
------
* Distance are returned in cgs units, i.e. centimeters
  If you want to see the "OD=1 altitude spectrum"  (ie. the altitudes where OD=1), then evaluate
  dodList[-1].z.max()-oDepthOne(dodList,1)      for a nadir view, or
  dodList[0].z.min() +oDepthOne(dodList)        for a zenith view
* Cumulative optical depths are computed starting with the very first (or last) layer
  If the observer is at an altitude somewhere in between, give only the subset of relevant odArray's.
  However, oDepthOne does not consider an observer between the levels (layer bounds).
* Extrapolation:  if the delta optical depths of the last layers are tiny,
                  the results might be 'nonsense'
oDepth_altitudes(odList)
Extract altitude levels and check for consistency and monotonicity.
oDepth_temperatures(odList)
Extract temperatures and check for consistency.
oDepth_zpT(odList)
Extract altitude, pressure, and temperature levels and check for consistency.
odInfo(optDepth)
Print information (min, max, mean, ...) for one or several optical depth(s).
odPlot(optDepth, tag='p', mue=False, trans=False)
Quicklook plot of optical depth vs wavenumber.
 
ARGUMENTS:
----------
optDepth:    differential, cumulative or total optical depth(s)
             either an odArray instance or a list thereof
tag:         select z|p|t for display in legend labels (default 'p')
mue:         flag, default False; if True plot vs. wavelength [micrometer]
trans:       flag, default False; if True plot transmission=exp(-od)
odRead(odFile, zToA=0.0, zBoA=0.0, xLimits=None, commentChar='#', verbose=False)
Read an ascii tabular OR pickled OR netcdf file of optical depth(s)
and return data along with atmosphere attributes.
 
ARGUMENTS:
----------
odFile:       data file with optical depths
zToA, zBoA:   ignore layers above top-of-atmosphere and/or below bottom-of-atmosphere altitudes
xLimits:      wavenumber interval (default None, i.e. read all)
commentChar:  default '#'
verbose:      boolean flag, default False
 
RETURNS:
--------
odList:       an odArray instance with an optical depth spectrum and some attributes (zz, pp, tt, ...)
              OR a list thereof
odSave(optDepth, outFile=None, commentChar=None, nanometer=False, flipUpDown=False, interpol='l', xFormat='%12f', yFormat='%11.5g')
Write optical depth to ascii (tabular or hitran) or pickled output file.
 
ARGUMENTS:
----------
optDepth       an odArray instance with an optical depth spectrum and some attributes (zz, pp, tt, ...)
               OR a list thereof
outFile:       file where data are to be stored (if not given, write to stdout)
               if file extension is 'nc' | 'ncdf' | 'netcdf' use netcdf format
commentChar:   if none (default), save data in numpy pickled file,
               otherwise ascii-tabular (wavenumber in first column, oDepth data interpolated to common, densest grid)
nanometer      flag:  save wavelength (instead of wavenumber, default)
flipUpDown     flag:  reorder and save last to first optical depths
interpol       interpolation method, default 'l' for linear interpolation with numpy.interp
                                     2 | 3 | 4  for self-made Lagrange interpolation
xFormat:       output format for wavenumbers, default '%12f' (only for ascii output)
yFormat:       output format for optical depth, default '%10.4g' (only for ascii output)
 
 
RETURNS:       nothing
 
NOTE:          if you want ascii tabular output WITHOUT interpolation,
               save data in individual files, i.e. call odSave in a loop over all layers
od_list2matrix(odList, interpol='l')
Convert a list of (delta) optical depths to a matrix and also return the wavenumber grid.

 
Data
        punctuation = '!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'
simpleNames = {'Altitude': 'z', 'Altitudes': 'z', 'Density': 'air', 'HGT': 'z', 'Height': 'z', 'Heights': 'z', 'PRE': 'p', 'Press': 'p', 'Pressure': 'p', 'Pressures': 'p', ...}