ROMS observations to DART observation sequences

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: ROMS.html 11427 2017-03-31 21:24:30Z $



The relationship between ROMS and DART is slightly different than most other models. ROMS has the ability to apply its own forward operator as the model is advancing (a capability needed for variational assimilation) which produces something the ROMS community calls 'verification' observations. The observation file that is input to ROMS is specified by the variable. The verification obs are written out to a netcdf file whose name is specified by the variable. Since each ROMS model is advancing independently, a set of verification observation files are created during a DART/ROMS assimilation cycle. This set of files can be converted using convert_roms_obs to produce a DART observation sequence file that has precomputed forward operators (FOs). convert_roms_obs can also convert,MODname files to a DART observation sequence file that does not have the precomputed FOs.

The ROMS verification observation files must contain the obs_provenance as a global attribute and the following variables:

Note that the obs_provenance:flag_values, and obs_provenance:flag_meanings attributes are totally ignored - those relationships are specified by the global attribute obs_provenance.

Locations only specified by obs_Xgrid, obs_Ygrid, obs_depth are not supported.

The conversion of a (set of) ROMS verification observations requires metadata to coordinate the relationship of the ROMS observation provenance to a DART observation TYPE. ROMS provides significant flexibility when specifying the observation provenance and it is simply impractical for DART to try to support all of them. An example of the current practice is described in the PROGRAMS section below.

Important: filter and perfect_model_obs must also be informed which DART observation types use precomputed forward operators. This is done by setting the input.nml&obs_kind_nml namelist. An example is shown at the end of the PROGRAMS section below.



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.

   ens_size               = 1
   roms_mod_obs_files     = ''
   roms_mod_obs_filelist  = 'filelist.txt'
   dart_output_obs_file   = 'obs_seq.out'
   append_to_existing     = .false.
   use_precomputed_values = .true.
   add_random_noise       = .false.
   pert_amplitude         = 0.01
   verbose                = 0
   type_translations      = 'NULL'

Item Type Description
ens_size integer Number of ensemble members which are expected to be found when creating the expected obs values. This must match the number of ROMS "mod" files listed in either the 'roms_mod_obs_files' or 'roms_mod_obs_filelist' namelist items. It is an error if they are not the same length.
roms_mods_obs_files character(len=256), dimension(100) List of filenames, one per ensemble member, that contain the observation values for each ensemble member. These are output from the ROMS program. If listing the files explicitly in this list, 'roms_mod_obs_filelist' must be ' ' (null).
roms_mods_obs_filelist character(len=256) The name of an ASCII file which contains, one per line, a list of filenames, one per ensemble member, that contain the expected obs values for each ensemble member. The filenames should NOT be quoted. These are output from the ROMS program. If using a filelist, then 'roms_mod_obs_files' must be ' ' (null).
dart_output_obs_file character(len=256) The name of the DART obs_seq file to create. If a file already exists with this name, it is either appended to or overwritten depending on the 'append_to_existing' setting below.
append_to_existing logical If an existing 'dart_output_obs_file' is found, this namelist item controls how it is handled. If .true. the new observations are appended to the existing file. If .false. the new observations overwrite the existing file.
use_precomputed_values logical flag to indicate that the output DART observation sequence file should include the verification observation values from all of the ROMS observation files. If .true. this will result in the DART file having the precomputed FOs to be used in the DART assimilation. If .false. this will result in DART files having the instrument values only.
add_random_noise logical Almost always should be .false. . The exception is the first cycle of an assimilation if all the ROMS input files are identical (no ensemble currently exists). To create differences in the forward operator values (since they are computed by ROMS), we can add gaussian noise here to give them perturbed values. This should be set as well as the "perturb_from_single_instance = .true." namelist in the &filter_nml namelist. After the first cycle, both these should be set back to .false. .
pert_amplitude real(r8) Ignored unless 'add_random_noise' is .true. . Controls the range of random values added to the expected obs values. Sets the width of a gaussian.
verbose integer If greater than 0, prints more information during the conversion.
type_translations character(256), dimension(2, 100) A set of strings which control the mapping of ROMS observation types to DART observation types. These should be specified in pairs. The first column should be a string that occurs in the global attribute 'obs_provenance'. Note that the obs_provenance:flag_values and obs_provenance:flag_meanings attributes are ignored. The second column should be a DART specific obs type that is found in DART/assimilation_code/modules/observations/obs_kind_mod.f90, which is created by the DART preprocess program.


The origin of the input observation files used by ROMS are completely unknown to me.


Only convert_roms_obs will be discussed here.

The global attribute obs_provenance is used to relate the observation provenance to DART observation TYPES. The ROMS 'MODname' netCDF file(s) must have both the obs_provenance variable and a obs_provenance global attribute. The exact strings must be repeated in the DART convert_roms_obs_nml:type_translations variable to be able to convert from the integer value of the obs_provenance to th DART type in the following example:

ncdump -h (the output has been pruned for clarity)

netcdf roms_mod_obs {
        record = 2 ;
        survey = 5376 ;
        state_var = 8 ;
        datum = 2407217 ;
        int obs_provenance(datum) ;
                obs_provenance:long_name = "observation origin" ;
                obs_provenance:flag_values = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ;
        double obs_time(datum) ;
                obs_time:long_name = "time of observation" ;
                obs_time:units = "days since 1900-01-01 00:00:00 GMT" ;
                obs_time:calendar = "gregorian" ;
        double obs_lon(datum) ;
                obs_lon:long_name = "observation longitude" ;
                obs_lon:units = "degrees_east" ;
        double obs_lat(datum) ;
                obs_lat:long_name = "observation latitude" ;
                obs_lat:units = "degrees_north" ;
        double obs_depth(datum) ;
                obs_depth:long_name = "ROMS internal depth of observation variable" ;
                obs_depth:units = "meters or fractional z-levels" ;
                obs_depth:negative_value = "downwards" ;
                obs_depth:missing_value = 1.e+37 ;
        double obs_error(datum) ;
                obs_error:long_name = "observation error covariance" ;
        double obs_value(datum) ;
                obs_value:long_name = "observation value" ;
        double obs_scale(datum) ;
                obs_scale:long_name = "observation screening/normalization scale" ;
                obs_scale:_FillValue = 0. ;
        double NLmodel_value(datum) ;
                NLmodel_value:long_name = "nonlinear model at observation locations" ;
                NLmodel_value:_FillValue = 1.e+37 ;
     :obs_provenance = "\n",
             "1: gridded AVISO sea level anomaly (zeta)\n",
             "2: gridded Aquarius SSS (salinity)\n",
             "3: XBT from Met Office (temperature)\n",
             "4: CTD from Met Office (temperature)\n",
             "5: CTD from Met Office (salinity)\n",
             "6: ARGO floats (temperature)\n",
             "7: ARGO floats (salinity)\n",
             "8: glider UCSD (temperature)\n",
             "9: glider UCSD (salinity)\n",
             "10: blended satellite SST (temperature)" ;

Note the integer values that start the obs_provenance strings are used to interpret the integer contents of the obs_provenance variable. They need not be consecutive, nor in any particular order, but they must not appear more than once.

The following is the relevent section of the DART input.nml:

   ens_size               = 32
   roms_mod_obs_filelist  = 'precomputed_files.txt'
   dart_output_obs_file   = 'obs_seq.out'
   append_to_existing     = .false.
   use_precomputed_values = .true.
   add_random_noise       = .false.
   verbose                = 1
   type_translations = "gridded AVISO sea level anomaly (zeta)", "SATELLITE_SSH",
                       "gridded Aquarius SSS (salinity)",        "SATELLITE_SSS",
                       "XBT from Met Office (temperature)",      "XBT_TEMPERATURE",
                       "CTD from Met Office (temperature)",      "CTD_TEMPERATURE",
                       "CTD from Met Office (salinity)",         "CTD_SALINITY",
                       "ARGO floats (temperature)",              "ARGO_TEMPERATURE",
                       "ARGO floats (salinity)",                 "ARGO_SALINITY",
                       "glider UCSD (temperature)",              "GLIDER_TEMPERATURE",
                       "glider UCSD (salinity)",                 "GLIDER_SALINITY",
                       "blended satellite SST (temperature)",    "SATELLITE_BLENDED_SST"

A complete list of DART observation TYPES is available in obs_def_ocean_mod.f90

Any or all of the DART observation types that appear in the second column of type_translations must also be designated as observations that have precomputed forward operators. This is done by setting the input.nml&obs_kind_nml namelist as follows:

   assimilate_these_obs_types =          'SATELLITE_SSH',
   use_precomputed_FOs_these_obs_types = 'SATELLITE_SSH',




  1. either remove the need for ens_size or use it to check the consistency of the number of files to convert.
  2. remove the roms_obs_files() mechanism.
  3. remove the roms_obs_file mechanism -or- IF the ens_size is specified, just use the first file and ignore the roms_obs_file.
  4. extend the type_translations table to be able to support a superset of obs_provenance-to-DART_TYPE relationships.
  5. support the ability to use the IJK locations.

Terms of Use

DART software - Copyright UCAR. This open source software is provided by UCAR, "as is", without charge, subject to all terms of use at

Contact: nancy collins
Revision: $Revision: 11427 $
Source: $URL: $
Change Date: $Date: 2017-03-31 15:24:30 -0600 (Fri, 31 Mar 2017) $
Change history:  try "svn log" or "svn diff"