NAMELIST / FILES / USAGE / REFERENCES / ERRORS / BUGS / PLANS / PRIVATE COMPONENTS

PROGRAM obs_diag

Contact: Tim Hoar
Reviewers:  
Revision: $Revision: 1.2 $
Release Name: $Name: post_iceland $
Change Date: $Date: 2006/06/20 18:05:43 $
Change history: see CVS log

OVERVIEW

Main program for evaluating filter performance in observation space. That is, the models expected observations are compared against the actual observations in various ways.

Identity observations are already explored with state-space diagnostics, so obs_diag simply skips them.

It produces matlab-compatible text files for each observation kind (i.e. RADIOSONDE, ACARS, ...) for several variables (i.e. T, WIND, ...) containing:

These data files can then be loaded and displayed using the Matlab® scripts in .../DART/diagnostics/matlab (or, in some cases, .../DART/matlab).

There are two versions of this program, one for high-order models that have real observations and another for low-order models. Since this program is fundamentally interested in the response as a function of region, the division was made if the model has a threed_sphere or a oned location_mod.f90. It did not make sense to ask the lorenz_96 model what part of North America you'd like to investigate. This program provides a number of options that are driven from its namelist.

With the post-iceland release of DART, obs_diag can also handle observations on model levels.

The obs_diag program performs an outlier test on observations, which can be more restrictive than the outlier test in the filter, but not less (see outlier_threshold in filter_nml and rat_cri here).

Optional namelist interface &obs_diag_nml may be read from file input.nml.




OTHER MODULES USED

obs_diag
sort_mod
obs_sequence_mod
obs_kind_mod
obs_def_mod
obs_def_radar_mod
obs_def_dew_point_mod
assim_model_mod
random_seq_mod
random_nr_mod
model_mod
location_mod
types_mod
time_manager_mod
utilities_mod



NAMELIST

We adhere to the F90 standard of starting a namelist with an ampersand '&' and terminating with a slash '/'.

namelist / obs_diag_nml /  &
   obs_sequence_name, obs_select,
   max_num_bins, first_bin_center, last_bin_center, bin_separation, bin_width, time_to_skip,
   mlevel, plevel, hlevel, rat_cri, qc_threshold, print_mismatched_locs,
   Nregions, lonlim1, lonlim2, latlim1, latlim2, reg_names

Discussion

This namelist is read in a file called input.nml.
The date-time integer arrays in this namelist have the form (YYYY, MO, DA, HR, MIN, SEC).
The regions boundaries allowable ranges are: latitude [-90.,90], longitude [0.,360.]
Contents Type Description
obs_sequence_name character Name of the obs files in subdirectories.
Default 'obs_seq.final'
first_bin_center integer, dimension(6) first timeslot of the first obs_seq.final file to process. The six integers are: year, month, day, hour, hour, minute, second -- in that order
last_bin_center integer, dimension(6) last timeslot of interest. (reminder: the last timeslot of day 1 is hour 0 of day 2) The six integers are: year, month, day, hour, hour, minute, second -- in that order
bin_separation integer, dimension(6) Time between bin centers. The year and month values must be zero.
bin_width integer, dimension(6) Time span around bin centers in which obs will be compared. The year and month values must be zero. Frequently, but not required to be, the same as the values for bin_separation.
time_to_skip integer, dimension(6) Time span at the beginning to skip when calculating vertical profiles of rms error and bias. The year and month values must be zero. Useful because it takes some time for the assimilation to settle down from the climatological spread at the start.
max_num_bins integer For dimensioning arrays to accommodate your assimilation timeslots .
mlevel integer Observations on model levels (perfect model observations) at which the rms error, spread, and num_obs time series will be calculated.
plevel integer Same as mlevel, but for observations with pressure (hPa) as the vertical coordinate. Much more common.
hlevel integer Same, but for observations that have height(m) as the vertical coordinate.
obs_select integer Which obs subset to use; all(1), radiosonde only(2), everything but radiosondes(3) .
rat_cri real Critical ratio of distance of the value of observation from the ensemble mean to the standard deviation of the ensemble. If this ratio is too large then the observation is suspect and will be ignored. If this value is larger than the corresponding one in the filter, then it does nothing; that obs has already been excluded by the filter.
qc_threshold real Observations with quality control values greater than this will be excluded from the diagnostics.
Nregions integer Number of regions of the globe for which you'd like obs space diagnostics.
lonlim1 integer Westernmost longitudes of the regions.
lonlim2 integer Easternmost longitudes of the regions.
latlim1 integer Southernmost latitudes of the regions.
latlim2 integer Northernmost latitudes of the regions.
reg_names character Array of names of the regions to be analyzed.
print_mismatched_locs logical print instances where U and V "pairs" don't have the same location.
verbose logical Print extra info about the obs_diag run.



FILES

Discussion




USAGE

Obs_diag is built in .../DART/models/your_model/work, in the same way as the other DART components.

Obs_diag assumes an organization of the assimilation output which has been found to be clear and useful. All the output to be saved is moved from the directory where the assimilation occurs to an Experiment directory (named by you). Experiment should be populated with subdirectories - one for each obs_seq.out(input!) file of the assimilation - containing observation space output files, typically "obs_seq.final". Obs_diag assumes the names of the subdirectories where the obs_seq.final files are found are of the form mm_##. At one point, the first 2 characters of the subdirectory names referred to 'month'. This number will be read from the obs_seq_nml variable first_bin_center(2). The second pair of digits ## define sequentially numbered directories, corresponding to the obs_seq.out files used to run the filter. The ##s that are used will be determined based on the time span specified in obs_seq_nml and the available obs_seq.final files. Obs_diag searches in these subdirectories for the obs_seq.final files which contain dates and times corresponding to those specified in its namelist. For obs_seq.final file numbers < 10 the subdirectory name will be padded with a 0, to make it a 2 character number. The Iceland version of obs_diag won't handle ## > 99.

Obs_diag may require a model input file from which to get grid information, metadata, and links to modules providing the models expected observations.




REFERENCES


ERROR CODES and CONDITIONS

RoutineMessageComment
obs_diag No first observation in sequence. get_first_obs couldn't find a "first obs" in the obs_seq.final.
obs_diag No last observation in sequence get_last_obs couldn't find a "last obs" in the obs_seq.final
obs_diag metadata incomplete Couldn't find the indices on the obs_seq.final file of the Posterior/Prior mean/spread, or the obs index"
filter_get_obs_info Vertical coordinate not recognized It must be "surface", "pressure", or "height"
Convert2Time namelist parameter out-of-bounds. Fix and try again bin_width, bin_separation, and time_to_skip must have year = 0 and month = 0



PRIVATE COMPONENTS




KNOWN BUGS




FUTURE PLANS

Make subdirectory names (containing obs_seq.final files) into simple sequential numbers, independent of months, days, etc. What about no_vert vertical coordinate variables?