PROGRAM obs_common_subset

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: obs_common_subset.html 6597 2013-11-11 15:55:33Z nancy $

NAMELIST / BUILDING / FILES / REFERENCES / ERRORS / PLANS / TERMS OF USE

Overview

This specialized tool allow you to select sets of observations from two or more input observation sequence files where the obs were successfully assimilated in all files. It creates a new set of observation sequence files containing only that subset of the original observations.

The intended use of this tool is as part of the process of comparing the results from a group of related experiments in which the same observation sequence file is used as input for all runs. The tool cannot process observation sequence files which differ in anything other than whether an observation was successfully assimilated/evaluated or not.

Experiments with different configurations can assimilate different numbers of the available observations. In that case there will be differences in the diagnostic plots which are not directly relatable to the differences in the quality of the assimilation. If this tool is run on the obs_seq.final files from all the experiments and then the diagnostics are generated, only the observations which were assimilated in all experiments will contribute to the summary statistics. A more direct comparison can be made and improvements attributed to the differences in the experimental parameters.

See the two experiment diagnostic plot documentation for Matlab scripts supplied with DART to directly compare the observation diagnostic output from multiple experiments (more than two, the script has a poor name).

This is one of a set of tools which operate on observation sequence files. For a more general purpose tool, see the obs_sequence_tool.

[top]

NAMELIST

This namelist is read from the file input.nml. Namelists start with an ampersand '&' and terminate with a slash '/'. Character strings that contain a '/' must be enclosed in quotes to prevent them from prematurely terminating the namelist.

&obs_common_subset_nml
 num_to_compare_at_once = 2,
 filename_seq           = '',
 filename_seq_list      = '',
 filename_out_suffix    = '.common' ,
 print_every            = 1000,
 dart_qc_threshold      = 3,
 calendar               = 'Gregorian',
 print_only             = .false.,
/


Item Type Description
num_to_process_at_once integer Number of observation sequence files to compare together at a time. Most commonly the value is 2, but can be any number. If more than this number of files are listed as inputs, the tool will loop over the list N files at a time.
filename_seq character(len=256), dimension(5000) The array of names of the observation sequence files to process. If more than N files (where N is num_to_compare_at_once) are listed, they should be ordered so all files from the first experiment are together, followed by all files from the second experiment, up to N experiments.
filename_seq_list character(len=256) An alternative way to specify the list of input observation sequence files. Give the name of a text file which contains, one per line, the names of the observation sequence files to process. You can only specify one of filename_seq OR filename_seq_list, not both. As with the filename_seq item, if more than N files (where N is num_to_compare_at_once) are listed, they should be ordered so all files from the first experiment are together, followed by all files from the second experiment, up to N experiments.
filename_out_suffix character(len=32) A string to be appended to each of the input observation sequence file names to create the output filenames.
print_every integer To indicate progress, a count of the successfully processed observations is printed every Nth set of obs. To decrease the output volume set this to a larger number. To disable this output completely set this to -1.
dart_qc_threshold integer The limit for the DART QC value. For an observation which was successfully assimilated or evaluated in both the Prior and Posterior this should be set to 1. To also include observations which were successfully processed in the Prior but not the Posterior, set to 3. It is not recommended to set it to a higher value than 3. Note that this is the QC value set by filter to indicate the outcome of trying to assimilate an observation. This is not related to the incoming data QC.
calendar character(len=32) Set to the name of the calendar; only controls the printed output for the dates of the first and last observations in the file. Set this to "no_calendar" if the observations are not using any calendar.
print_only logical If .TRUE. do not create the output files, but print a summary of the number and types of each observation in each of the input and output files.


[top]

BUILDING

Most $DART/models/*/work directories will build the tool along with other executable programs. It is also possible to build the tool in the $DART/observations/utilities directory. The preprocess program must be built and run first, to define what set of observation types will be supported. See the preprocess documentation for more details on how to define the list and run it. The combined list of all observation types which will be encountered over all input files must be in the preprocess input list. The other important choice when building the tool is to include a compatible locations module. For the low-order models, the oned module should be used; for real-world observations, the threed_sphere module should be used.

Generally the directories where executables are built will include a "quickbuild.csh" script which will build and run preprocess and then build the rest of the executables. The "input.nml" namelists will need to be edited to include all the required observation types first.

[top]

MODULES USED

types_mod
utilities_mod
time_manager_mod
obs_def_mod
obs_sequence_mod
[top]

FILES

[top]

REFERENCES

[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
obs_common_subset num_input_files > max_num_input_files. The default is 5000 total files. To process more, change max_num_input_files in source code
obs_common_subset num_to_compare_at_once and filename_seq length mismatch The number of filenames is not an even multiple of the count.
handle_filenames cannot specify both filename_seq and filename_seq_list You can either specify the files directly in the namelist, or give a filename that contains the list of input files, but not both.

KNOWN BUGS

none

[top]

FUTURE PLANS

none at this time.

[top]

Terms of Use

DART software - Copyright 2004 - 2013 UCAR.
This open source software is provided by UCAR, "as is",
without charge, subject to all terms of use at
http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 6597 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Lanai/obs_sequence/obs_common_subset.html $
Change Date: $Date: 2013-11-11 08:55:33 -0700 (Mon, 11 Nov 2013) $
Change history:  try "svn log" or "svn diff"