oDepth (version mar21)
index
/users/schrei_f/src/py4CAtS/art/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

 
Modules
       
numpy
os
sys

 
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).
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.

Static methods defined here:
__new__(cls, input_array, xLimits=None, z=None, p=None, t=None)
Create and return a new object.  See help(type) for accurate signature.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)

Data and other attributes defined here:
__hash__ = None

 
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)
dump(obj, file, protocol=None, *, fix_imports=True)
Write a pickled representation of obj to the open file object file.
 
This is equivalent to ``Pickler(file, protocol).dump(obj)``, but may
be more efficient.
 
The optional *protocol* argument tells the pickler to use the given
protocol supported protocols are 0, 1, 2, 3 and 4.  The default
protocol is 3; a backward-incompatible protocol designed for Python 3.
 
Specifying a negative protocol version selects the highest protocol
version supported.  The higher the protocol used, the more recent the
version of Python needed to read the pickle produced.
 
The *file* argument must have a write() method that accepts a single
bytes argument.  It can thus be a file object opened for binary
writing, an io.BytesIO instance, or any other custom object that meets
this interface.
 
If *fix_imports* is True and protocol is less than 3, pickle will try
to map the new Python 3 names to the old module names used in Python
2, so that the pickle data stream is readable with Python 2.
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)
load(file, *, fix_imports=True, encoding='ASCII', errors='strict')
Read and return an object from the pickle data stored in a file.
 
This is equivalent to ``Unpickler(file).load()``, but may be more
efficient.
 
The protocol version of the pickle is detected automatically, so no
protocol argument is needed.  Bytes past the pickled object's
representation are ignored.
 
The argument *file* must have two methods, a read() method that takes
an integer argument, and a readline() method that requires no
arguments.  Both methods should return bytes.  Thus *file* can be a
binary file object opened for reading, an io.BytesIO object, or any
other custom object that meets this interface.
 
Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
which are used to control compatibility support for pickle stream
generated by Python 2.  If *fix_imports* is True, pickle will try to
map the old Python 2 names to the new names used in Python 3.  The
*encoding* and *errors* tell pickle how to decode 8-bit string
instances pickled by Python 2; these default to 'ASCII' and 'strict',
respectively.  The *encoding* can be 'bytes' to read these 8-bit
string instances as bytes objects.
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, lengthUnit=None)
Extract altitude levels and check for consistency and monotonicity (see oDepth_zpT).
Optionally return altitude array converted into appropriate length unit (default 'cm').
oDepth_pressures(odList, pressureUnit=None)
Extract pressure levels and check for consistency and monotonicity (see oDepth_zpT).
Optionally return pressure array converted into appropriate pressure unit (default 'g/cm/s**2)').
oDepth_temperatures(odList)
Extract temperatures and check for consistency (see oDepth_zpT).
oDepth_zpT(odList)
Extract altitude, pressure, and temperature levels from list of odArrays and check for consistency.
 
RETURN:   three numpy arrays
 
NOTE:     the altitudes (pressures) returned are always monotonically increasing (decreasing)!!!
          if the optical depths are non-contiguous, an ERROR is raised.
odInfo(optDepth)
Print information (min, max, mean, ...) for one or several optical depth(s).
odPlot(optDepth, tag='p', mue=False, trans=False, **kwArgs)
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)
kwArgs       passed directly to semilogy and can be used to set colors, line styles and markers etc.
             ignored (cannot be used) in recursive calls with lists or dictionaries of optical depths.
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, transmission=False, flipUpDown=False, interpol='l', xFormat='%12f', yFormat='%11.5g')
Write optical depth to pickled or ascii (tabular) 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)
 
               !!! the following options are only relevant/supported for ascii output !!!
 
nanometer      flag:  save wavelength (instead of default wavenumber)
transmission   flag:  save exp(-od)   (instead of default optical depth)
flipUpDown     flag:  reorder od list 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'
yFormat:       output format for optical depth, default '%10.4g'
 
 
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
        __warningregistry__ = {'version': 15, ('\nThe datapath rcparam was deprecated in Matplotl...2.1 and will be removed two minor releases later.', <class 'matplotlib.cbook.deprecation.MatplotlibDeprecationWarning'>, 69): True}
lengthUnits = {'A': 1e-08, 'au': 14959787070000, 'cm': 1.0, 'dm': 10.0, 'inch': 2.54, 'km': 100000.0, 'ly': 946073047258080000, 'm': 100.0, 'micrometer': 0.0001, 'mm': 0.1, ...}
pressureUnits = {'N/m**2': 10.0, 'N/m^2': 10.0, 'Pa': 10.0, 'Torr': 1333.22, 'atm': 1013250.0, 'bar': 1000000.0, 'dyn/cm**2': 1.0, 'dyn/cm^2': 1.0, 'g/(cm*s**2)': 1.0, 'g/(cm*s^2)': 1.0, ...}
punctuation = '!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'
simpleNames = {'Altitude': 'z', 'Altitudes': 'z', 'Density': 'air', 'HGT': 'z', 'Height': 'z', 'Heights': 'z', 'PRE': 'p', 'Press': 'p', 'Pressure': 'p', 'Pressures': 'p', ...}