Update radar obs_converter README

CHANGELOG.rst

@@ -22,6 +22,10 @@ individual files.
 
 The changes are now listed with the most recent at the top.
 
+**October 27 2021 :: Observation converter documentation update. Tag: v9.11.12**
+
+- Improved documentation for radar observation converters
+
 **September 30 2021 :: Bug fix for very large models. Tag v9.11.11**
 
 - mpi_utilties_mod using correct check for message length > SNDRCV_MAXSIZE

README.rst

@@ -320,7 +320,7 @@ References
    observations/obs_converters/quikscat/QuikSCAT
    observations/obs_converters/even_sphere/README
    observations/obs_converters/obs_error/README
-   observations/obs_converters/radar/radar
+   observations/obs_converters/radar/README
    observations/obs_converters/snow/snow_to_obs
    observations/obs_converters/text/text_to_obs
    observations/obs_converters/tpw/tpw

conf.py

@@ -21,7 +21,7 @@
 author = 'Data Assimilation Research Section'
 
 # The full version, including alpha/beta/rc tags
-release = '9.11.11'
+release = '9.11.12'
 master_doc = 'README'
 
 # -- General configuration ---------------------------------------------------

guide/available-observation-converters.rst

@@ -8,18 +8,25 @@ into the format required by DART.
 Each directory has at least one converter:
 
 -  ``AIRS``: :doc:`/observations/obs_converters/AIRS/README`
+-  ``AURA``: See ``DART/observations/obs_converters/AURA``
 -  ``Aviso+/CMEMS``: :doc:`../observations/obs_converters/AVISO/AVISO`
 -  ``Ameriflux``: :doc:`../observations/obs_converters/Ameriflux/level4_to_obs`
+-  ``CHAMP``: :doc:`../observations/obs_converters/CHAMP/work/README`
 -  ``cice``: :doc:`../observations/obs_converters/cice/cice_to_obs`
+-  ``CNOFS``: See ``DART/observations/obs_converters/CNOFS``
+-  ``CONAGUA``: :doc:`../observations/obs_converters/CONAGUA/README`
 -  ``COSMOS``: :doc:`../observations/obs_converters/COSMOS/COSMOS_to_obs`
 -  ``DWL``: :doc:`../observations/obs_converters/DWL/dwl_to_obs`
+-  ``GMI``: :doc:`../observations/obs_converters/GMI/README`
 -  ``GOES``: :doc:`../observations/obs_converters/GOES/README`
 -  ``GPSPW``: :doc:`../observations/obs_converters/GPSPW/README`
+-  ``GRACE``: See ``DART/observations/obs_converters/GRACE``
 -  ``GSI2DART``: :doc:`../observations/obs_converters/GSI2DART/readme`
 -  ``GTSPP``: :doc:`../observations/obs_converters/GTSPP/GTSPP`
 -  ``MADIS``: :doc:`../observations/obs_converters/MADIS/MADIS`
 -  ``MIDAS``: :doc:`../observations/obs_converters/MIDAS/MIDAS_to_obs`
 -  ``MODIS``: :doc:`../observations/obs_converters/MODIS/MOD15A2_to_obs`
+-  ``MPD``: See ``DART/observations/obs_converters/MPD``
 -  ``NCEP``: (prepbufr -> ascii) :doc:`../observations/obs_converters/NCEP/prep_bufr/prep_bufr`
 -  ``NCEP``: (ascii -> obs_seq) :doc:`../observations/obs_converters/NCEP/ascii_to_obs/create_real_obs`
 -  ``ROMS``: :doc:`../observations/obs_converters/ROMS/ROMS`
@@ -32,9 +39,10 @@ Each directory has at least one converter:
 -  ``GPS``: :doc:`../observations/obs_converters/gps/gps`
 -  ``ok_mesonet``: :doc:`../observations/obs_converters/ok_mesonet/ok_mesonet`
 -  ``QuikSCAT``: :doc:`../observations/obs_converters/quikscat/QuikSCAT`
--  ``Radar``: :doc:`../observations/obs_converters/radar/radar`
+-  ``Radar``: :doc:`../observations/obs_converters/radar/README`
 -  ``snow``: :doc:`../observations/obs_converters/snow/snow_to_obs`
 -  ``Text``: :doc:`../observations/obs_converters/text/text_to_obs`
+-  ``text_GITM``: See ``DART/observations/obs_converters/text_GITM``
 -  ``tpw``: :doc:`../observations/obs_converters/tpw/tpw`
 -  ``Tropical Cyclones``: :doc:`../observations/obs_converters/tropical_cyclone/tc_to_obs`
 -  ``Var (little-r)``: :doc:`../observations/obs_converters/var/littler_tf_dart`

observations/obs_converters/CHAMP/work/README.rst

@@ -1,23 +1,42 @@
 CHAMP
 =====
 
-This is just a modification of a standard "text" converter that comes with DART.
+This is a modification of a standard ``text_to_obs`` converter that comes that
+comes with DART.
 
-It reads CHAMP and GRACE text Density files (which used to be at
-sisko.colorado.edu/sutton/data.html) and outputs DART obs_seq.out files.
+This observation converter reads CHAMP and GRACE density files, as described in
+Sutton (2011) [1]_ and outputs ``obs_seq`` files that can be assimilated using
+DART.
 
-Be aware that if obs_seq.out already exists, it automatically adds new
-observations to that file without deleting it. This is done to allow
-the wrapper script (work/convert.sh) to process sequentially numbered
-Density_*.ascii files (read comments inside convert.sh).
-If this is not the behavior you want, comment out lines 129-132 in
-text_to_obs.f90 and rebuild.
+.. warning::
 
-Please check out work/input.nml:&text_to_obs_nml as it specifies the
-name of the input and the output
+   If an ``obs_seq.out`` file already exists, this converter  automatically adds
+   new observations to that file without deleting it. This is done to allow the
+   wrapper script (work/convert.sh) to process sequentially numbered
+   Density_*.ascii files, as documented in the comments in convert.sh. If you
+   don't want this behavior, comment out lines 129-132 in text_to_obs.f90 and
+   rebuild.
 
-The work/Density_3deg_02_335.ascii is truncated to 2 datapoints to
-demonstrate the format and is not to be used for real experiments.
+Namelist
+--------
 
-Author: Alexey Morozov
+Please inspect the ``text_to_obs_nml`` namelist in ``work/input.nml`` to ensure
+the input and output filenames are specified properly.
+
+.. note::
+
+   The `work/Density_3deg_02_335.ascii` file is truncated to 2 datapoints
+   merely to demonstrate the format. It isn't meant to be used for real
+   experiments.
+
+Author
+------
+
+Thank you to Alexey Morozov for contributing this observation converter.
+
+References
+----------
+
+.. [1]  Sutton, Erik K., 2011: Accelerometer-Derived Atmospheric Density
+        from the CHAMP and GRACE Satellites.
 

observations/obs_converters/README.rst

@@ -357,47 +357,46 @@ observations into the format required by DART.
 The current list of converters (some directories contain multiple
 converters) include:
 
--  `AIRS <AIRS/README.html>`__ `atmospheric variables <AIRS/convert_airs_L2.html>`__
-   and `AMSUA radiances <AIRS/convert_amsu_L1.html>`__
--  AURA (uses a combination of IDL and Fortran)
--  `Aviso+/CMEMS <AVISO/AVISO.html>`__
--  `Ameriflux <Ameriflux/level4_to_obs.html>`__
--  `CHAMP <CHAMP/work/README.html>`__
--  `cice <cice/cice_to_obs.html>`__
--  CNOFS
--  `CONAGUA <CONAGUA/README.html>`__
--  `COSMOS <COSMOS/COSMOS_to_obs.html>`__
--  `DWL <DWL/dwl_to_obs.html>`__
--  `GMI <GMI/README.html>`__
--  `GOES <GOES/README.html>`__
--  `GPSPW <GPSPW/README.html>`__
--  GRACE
--  `GSI2DART <GSI2DART/readme.html>`__
--  `GTSPP <GTSPP/GTSPP.html>`__
--  `MADIS <MADIS/MADIS.html>`__
--  `MIDAS <MIDAS/MIDAS_to_obs.html>`__
--  `MODIS <MODIS/MOD15A2_to_obs.html>`__
--  `MPD <MPD/README.html>`__
--  `NCEP (prepbufr->ascii) <NCEP/prep_bufr/prep_bufr.html>`__
--  `NCEP (ascii->obs_seq) <NCEP/ascii_to_obs/create_real_obs.html>`__
--  `ROMS <ROMS/ROMS.html>`__
--  `SIF <SIF/SIF_to_obs_netcdf.html>`__
--  `SSEC <SSEC/SSEC.html>`__
--  `SST <SST/SST.html>`__
--  `SSUSI <SSUSI/convert_f16_edr_dsk.html>`__
--  `WOD <WOD/WOD.html>`__
--  `gnd_gps_vtec <gnd_gps_vtec/README.html>`__
--  `GPS <gps/gps.html>`__
--  `ok_mesonet <ok_mesonet/ok_mesonet.html>`__
--  `QuikSCAT <quikscat/QuikSCAT.html>`__
--  `Radar <radar/radar.html>`__
--  `snow <snow/snow_to_obs.html>`__
--  `Text <text/text_to_obs.html>`__
--  text_GITM
--  `tpw <tpw/tpw.html>`__
--  `Tropical Cyclones <tropical_cyclone/tc_to_obs.html>`__
--  `Var (little-r) <var/littler_tf_dart.html>`__
--  `Var (radar) <var/rad_3dvar_to_dart.html>`__
+-  ``AIRS``: :doc:`./AIRS/README`
+-  ``AURA``: See ``./AURA``
+-  ``Aviso+/CMEMS``: :doc:`./AVISO/AVISO`
+-  ``Ameriflux``: :doc:`./Ameriflux/level4_to_obs`
+-  ``CHAMP``: :doc:`./CHAMP/work/README`
+-  ``cice``: :doc:`./cice/cice_to_obs`
+-  ``CNOFS``: See ``./CNOFS``
+-  ``CONAGUA``: :doc:`./CONAGUA/README`
+-  ``COSMOS``: :doc:`./COSMOS/COSMOS_to_obs`
+-  ``DWL``: :doc:`./DWL/dwl_to_obs`
+-  ``GMI``: :doc:`./GMI/README`
+-  ``GOES``: :doc:`./GOES/README`
+-  ``GPSPW``: :doc:`./GPSPW/README`
+-  ``GRACE``: See ``./GRACE``
+-  ``GSI2DART``: :doc:`./GSI2DART/readme`
+-  ``GTSPP``: :doc:`./GTSPP/GTSPP`
+-  ``MADIS``: :doc:`./MADIS/MADIS`
+-  ``MIDAS``: :doc:`./MIDAS/MIDAS_to_obs`
+-  ``MODIS``: :doc:`./MODIS/MOD15A2_to_obs`
+-  ``MPD``: See ``./MPD``
+-  ``NCEP``: (prepbufr-> ascii) :doc:`./NCEP/prep_bufr/prep_bufr`
+-  ``NCEP``: (ascii-> obs_seq) :doc:`./NCEP/ascii_to_obs/create_real_obs`
+-  ``ROMS``: :doc:`./ROMS/ROMS`
+-  ``SIF``: :doc:`./SIF/SIF_to_obs_netcdf`
+-  ``SSEC``: :doc:`./SSEC/SSEC`
+-  ``SST``: :doc:`./SST/SST`
+-  ``SSUSI``: :doc:`./SSUSI/convert_f16_edr_dsk`
+-  ``WOD``: :doc:`./WOD/WOD`
+-  ``gnd_gps_vtec``: :doc:`./gnd_gps_vtec/README`
+-  ``GPS``: :doc:`./gps/gps`
+-  ``ok_mesonet``: :doc:`./ok_mesonet/ok_mesonet`
+-  ``QuikSCAT``: :doc:`./quikscat/QuikSCAT`
+-  ``Radar``: :doc:`./radar/README`
+-  ``snow``: :doc:`./snow/snow_to_obs`
+-  ``Text``: :doc:`./text/text_to_obs`
+-  ``text_GITM``: See ``./text_GITM``
+-  ``tpw``: :doc:`./tpw/tpw`
+-  ``Tropical Cyclones``: :doc:`./tropical_cyclone/tc_to_obs`
+-  ``Var (little-r)``: :doc:`./var/littler_tf_dart`
+-  ``Var (radar)``: :doc:`./var/rad_3dvar_to_dart`
 
 In addition the following external program produces DART observation
 sequence files:

observations/obs_converters/radar/README.rst

@@ -0,0 +1,95 @@
+Radar observations
+==================
+
+Overview
+--------
+
+DART provides limited support for the conversion of radar observations to 
+``obs_seq`` format. As an end goal, you want to assimilate radar observations
+that:
+
+* Have been quality controlled to remove non-meteorological scatterers and
+  other artifacts
+* Have horizontal resolution that has been reduced to approximately twice the
+  expected horizontal grid spacing of your model. For example, if your model 
+  has 3 km grid spacing, you should reduce your radar observations to every 6
+  km, interpolated along the sweep plane.
+
+Reflectivity observations are often partitioned into two types:
+
+1. Regular reflectivity observations
+2. Clear-air reflectivity observations where no radar echoes are observed.
+
+Quality control is best done with raw data. You should have an ability to
+perform quality control before converting your observations to obs_seq format.
+
+Synthetic radar observations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``create_obs_radar_sequence`` program generates one or more sets of 
+synthetic `WSR-88D (NEXRAD) <http://en.wikipedia.org/wiki/WSR-88D>`__ radar
+observations. It can generate reflectivity and/or doppler radial velocity
+observations with clear-air or storm sweep patterns. These synthetic
+observations can be used for testing your assimilation setup or for conducting
+Observing System Simulation Experiments (OSSEs).
+
+To build ``create_obs_radar_sequence``, change directory into the ``work`` 
+subdirectory, ensure ``input.nml`` is configured properly and run the build
+script:
+
+.. code-block::
+
+   cd work
+   ./quickbuild.csh
+
+Real radar observations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have ensured that your data are quality controlled, use the 
+`Observation Processing And Wind Synthesis (OPAWS) <http://code.google.com/p/opaws/>`__
+utility convert your data to `obs_seq` format. The OPAWS utility reads specific
+types of files as input, such as DORADE sweep files and NCAR EOL Foray data.
+
+OPAWS analyzes and grids data in either:
+
+* two-dimensions (on the conical surface of each sweep), or
+* three-dimensions (Cartesian).
+
+If your raw data are not in such a format, additional utilities are available
+for conversion such as the 
+`RADX library which is part of the LIDAR/RADAR Open Software Environment <https://github.com/NCAR/lrose-core>`__.
+
+Guidance for Weather Research and Forecasting (WRF) users
+---------------------------------------------------------
+
+If you intend to assimilate radar observations into WRF, you'll need to make
+some code modifications to allow for forward operator calculations. For
+reflectivity, most of the available microphysics schemes have built-in
+capability to output reflectivity, assuming a 10 cm wavelength. If you are not
+using an S-band radar, be aware that attenuation is not accounted for in the
+built-in reflectivity operator.
+
+For radial velocity, you will also need to generate a new diagnostic field:
+terminal fall velocity. There is very limited support for fall velocity in WRF,
+although it is partially supported in the Thompson microphysics scheme. 
+
+.. note:: 
+
+   You will still need to modify WRF code to get this diagnostic output to
+   history files.
+
+With these two fields available in your WRF history files, you can add them to
+your DART `wrf_state_variables` list.
+
+You should also use a special localization radius for radar observations, 
+typically 12-24 km. If you leave range-folding in your radar observations, you
+will need to build the special version of DART that unfolds the velocity
+observations on-the-fly.
+
+With all of those configurations in place, you will be ready to assimilate 
+radar observations using WRF and DART.
+
+For more information, see the WRF tests directory in
+``DART/models/wrf/regression/Radar/`` for pointers to data to run a radar test
+case.
+