3.3. Input/Output Files for the JEDI DA System

This chapter describes the configuration of the offline Land Data Assimilation (DA) System, which utilizes the UFS Noah-MP component together with the jedi-bundle (Skylab v7.0) to enable cycled model forecasts. The data assimilation framework applies the Local Ensemble Transform Kalman Filter (LETKF) algorithm with pseudo-ensemble error covariance.

3.3.1. Joint Effort for Data Assimilation Integration (JEDI)

Attention

Users are encouraged to visit the JEDI Documentation. Much of the information in this chapter is drawn directly from there with modifications to clarify JEDI’s use specifically in the context of the Land DA System.

The Joint Effort for Data assimilation Integration (JEDI) is a unified and versatile data assimilation (DA) system for Earth system prediction that can be run on a variety of platforms. JEDI is developed by the Joint Center for Satellite Data Assimilation (JCSDA) and partner agencies, including NOAA. The core feature of JEDI is separation of concerns. The data assimilation update, observation selection and processing, and observation operators are all coded with no knowledge of or dependency on each other or on the forecast model.

The NOAH-MP offline Land DA System uses three JEDI components:

• The Object-Oriented Prediction System (OOPS) for the data assimilation algorithm

• The Interface for Observation Data Access (IODA) for the observation formatting and processing

• The Unified Forward Operator (UFO) for comparing model forecasts and observations

JEDI’s Unified Forward Operator (UFO) links observation operators with the Object Oriented Prediction System (OOPS) to compute a simulated observation given a known model state. It does not restrict observation operators based on model-specific code structures or requirements. The UFO code structure provides generic classes for observation bias correction and quality control. Within this system, IODA converts the observation data into model-specific formats to be ingested by each model’s data assimilation system. This involves model-specific data conversion efforts.

3.3.1.1. Object-Oriented Prediction System (OOPS)

A data assimilation experiment requires a YAML configuration file that specifies the details of the data assimilation and observation processing. OOPS provides the core set of data assimilation algorithms in JEDI by combining the generic building blocks required for the algorithms. The OOPS system does not require knowledge of any specific application model implementation structure or observation data information. In the Noah-MP offline Land DA System, OOPS reads the model forecast states from the restart files generated by the Noah-MP model. JEDI UFO contains generic quality control options and filters that can be applied to each observation system, without coding at certain model application levels. More information on the key concepts of the JEDI software design can be found in Trémolet and Auligné [TA20] (2020), Holdaway et al. [HVMWK20] (2020), and Honeyager et al. [HHZ+20] (2020).

3.3.1.1.1. JEDI Configuration Files & Parameters

The DA experiment integrates information from several YAML configuration files, which contain certain fundamental components such as geometry, time window, background, driver, local ensemble DA, output increment, and observations. These components can be implemented differently for different models and observation types, so they frequently contain distinct parameters and variable names depending on the use case. Therefore, this section of the User’s Guide focuses on assisting users with understanding and customizing these top-level configuration items in order to run Land DA experiments. Users may also reference the JEDI Documentation for additional information.

In the Land DA workflow, letkfoi_snow.yaml contains most of the information on geometry, time window, background, driver, local ensemble DA, and output increment, while GHCN.yaml contains detailed information to configure observations. In the develop branch, these files reside in the land-DA_workflow/parm/jedi directory. Some of the variables in these files are templated, so they bring in information from other files, such as the workflow configuration files (parm_xml.yaml and template.land_analysis.yaml) and the actual netCDF observation file (e.g., ghcn_snwd_ioda_20000103.nc). In the analysis task, this information is assembled into one letkf_land.yaml file that is used to perform the snow data assimilation. This file resides in the ptmp/test/tmp/analysis.${PDY}${cyc}.${jobid}/ directory, where ${PDY}${cyc} is in YYYYMMDDHH format (see Section 3.1.3.1 for more on these variables), and the ${jobid} is the job ID assigned by the system. The example below shows what the complete letkf_land.yaml file might look like for the 2000-01-03 00Z cycle. The following subsections explain the variables used within this YAML file.

geometry:
  fms initialization:
    namelist filename: Data/fv3files/fmsmpp.nml
    field table filename: Data/fv3files/field_table
  akbk: Data/fv3files/akbk64.nc4
  npx: 97   # $RES + 1
  npy: 97   # $RES + 1
  npz: 64
  field metadata override: gfs-land.yaml
  time invariant fields:
    state fields:
      datetime: 2000-01-02T00:00:00Z
      filetype: fms restart
      skip coupler file: true
      state variables: [orog_filt]
      datapath: /scratch2/NAGAPE/epic/User.Name/landda/land-DA_workflow/fix/FV3_fix_tiled/C96
      filename_orog: oro_C96.mx100.nc
    derived fields: [nominal_surface_pressure]

time window:
  begin: 2000-01-02T00:00:00Z
  length: PT24H

background:
  date: &date 2000-01-03T00:00:00Z
  members:
    - datetime: 2000-01-03T00:00:00Z
      filetype: fms restart
      state variables: [snwdph,vtype,slmsk]
      datapath: mem_pos/
      filename_sfcd: 20000103.000000.sfc_data.nc
      filename_cplr: 20000103.000000.coupler.res
    - datetime: 2000-01-03T00:00:00Z
      filetype: fms restart
      state variables: [snwdph,vtype,slmsk]
      datapath: mem_neg/
      filename_sfcd: 20000103.000000.sfc_data.nc
      filename_cplr: 20000103.000000.coupler.res

driver:
  save posterior mean: false
  save posterior mean increment: true
  save posterior ensemble: false
  run as observer only: false

local ensemble DA:
  solver: LETKF
  inflation:
    rtps: 0.0
    rtpp: 0.0
    mult: 1.0

output increment:
  filetype: fms restart
  filename_sfcd: xainc.sfc_data.nc

observations:
  observers:
  - obs space:
      name: SnowDepthGHCN
      distribution:
        name: Halo
        halo size: 250e3
      simulated variables: [totalSnowDepth]
      obsdatain:
        engine:
          type: H5File
          obsfile: GHCN_2000010300.nc
      obsdataout:
        engine:
          type: H5File
          obsfile: output/DA/hofx/letkf_hofx_ghcn_2000010300.nc
    obs operator:
      name: Identity
    obs error:
      covariance model: diagonal
    obs localizations:
    - localization method: Horizontal SOAR
      lengthscale: 250e3
      soar horizontal decay: 0.000021
      max nobs: 50
    - localization method: Vertical Brasnett
      vertical lengthscale: 700
    obs filters:
    - filter: Bounds Check # negative / missing snow
      filter variables:
      - name: totalSnowDepth
      minvalue: 0.0
      maxvalue: 10000.0
    - filter: Domain Check # missing station elevation (-999.9)
      where:
      - variable:
          name: MetaData/stationElevation
        minvalue: -999.0
        maxvalue: 10000.0
    - filter: Domain Check # land only
      where:
      - variable:
          name: GeoVaLs/slmsk
        minvalue: 0.5
        maxvalue: 1.5
    - filter: RejectList  # no land-ice
      where:
      - variable:
          name: GeoVaLs/vtype
        minvalue: 14.5
        maxvalue: 15.5
    - filter: Background Check # gross error check
      filter variables:
      - name: totalSnowDepth
      threshold: 6.25
      action:
        name: reject

Note

Any default values indicated in the sections below are the defaults set in letkfoi_snow.yaml, GHCN.yaml, parm_xml.yaml, or template.land_analysis.yaml.

3.3.1.1.1.1. Geometry

The geometry: section is used in JEDI configuration files to specify the model grid’s parallelization across compute nodes (horizontal and vertical).

fms initialization

This section contains two parameters, namelist filename and field table filename, which are required for FMS initialization.

namelist filename (Default: Data/fv3files/fmsmpp.nml)

Specifies the path to the namelist file.

field table filename (Default: Data/fv3files/field_table)

Specifies the path to the field table file.

akbk (Default: Data/fv3files/akbk64.nc4)

Specifies the path to a file containing the coefficients that define the hybrid sigma-pressure vertical coordinate used in FV3. Files are provided with the repository containing ak and bk for some common choices of vertical resolution for GEOS and GFS.

npx (Default: 97)

Specifies the number of grid points in the east-west direction.

npy (Default: 97)

Specifies the number of grid points in the north-south direction.

npz (Default: 64)

Specifies the number of vertical layers.

field metadata override (Default: gfs-land.yaml)

Specifies the path to field metadata file.

time invariant fields

This YAML section contains state fields and derived fields.

state fields:

This parameter contains several subparameters listed below.

datetime (Default: XXYYYP-XXMP-XXDPTXXHP:00:00Z) Specifies the time in YYYY-MM-DDTHH:00:00Z format, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour.

filetype (Default: fms restart) Specifies the type of file. Valid values include: fms restart

skip coupler file (Default: true) Specifies whether to enable skipping coupler file. Valid values are: true | false

Value	Description
true	enable
false	do not enable

state variables (Default: [orog_filt]) Specifies the list of state variables. Valid values include: [orog_filt]

datapath (Default: $LANDDAROOT/land-DA_workflow/fix/FV3_fix_tiled/C96) Specifies the path for state variables data.

filename_orog (Default: oro_C96.mx100.nc) Specifies the name of orographic data file.

derived fields: (Default: [nominal_surface_pressure])

3.3.1.1.1.2. Window begin, Window length

These two items define the assimilation window for many applications, including Land DA.

time window:

Contains information related to the start, end, and length of the experiment.

begin: (Default: XXYYYP-XXMP-XXDPTXXHP:00:00Z)

Specifies the beginning time window. The format is YYYY-MM-DDTHH:00:00Z, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour.

length: (Default: PT24H)

Specifies the time window length. The form is PTXXH, where XX is a 1- or 2-digit hour. For example: PT6H

3.3.1.1.1.3. Background

The background: section includes information on the analysis file(s) (also known as “members”) generated by the previous cycle.

date: (Default: &date XXYYYY-XXMM-XXDDTXXHH:00:00Z)

Specifies the background date. The format is &date YYYY-MM-DDTHH:00:00Z, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour. For example: &date 2000-01-03T00:00:00Z

members:

Specifies information on analysis file(s) generated using information from a previous cycle.

datetime: (Default: XXYYYY-XXMM-XXDDTXXHH:00:00Z)

Specifies the date and time. The format is YYYY-MM-DDTHH:00:00Z, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour.

filetype: (Default: fms restart)

Specifies the type of file. Valid values include: fms restart

state variables: (Default: [snwdph,vtype,slmsk])

Specifies a list of state variables. Valid values: [snwdph,vtype,slmsk]

datapath:

Specifies the path for state variable data. Valid values: mem_pos/ | mem_neg/. (With default experiment values, the full path will be ptmp/test/tmp/analysis.${PDY}${cyc}.${jobid}.)

filename_sfcd: (Default: XXYYYYXXMMXXDD.XXHH0000.sfc_data.nc)

Specifies the name of the surface data file. This usually takes the form YYYYMMDD.HHmmss.sfc_data.nc, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour, mm is a valid 2-digit minute and ss is a valid 2-digit second. For example: 20000103.000000.sfc_data.nc

filename_cprl: (Default: XXYYYYXXMMXXDD.XXHH0000.coupler.res)

Specifies the name of file that contains metadata for the restart. This usually takes the form YYYYMMDD.HHmmss.coupler.res, where YYYY is a 4-digit year, MM is a valid 2-digit month, DD is a valid 2-digit day, and HH is a valid 2-digit hour, mm is a valid 2-digit minute and ss is a valid 2-digit second. For example: 20000103.000000.coupler.res

3.3.1.1.1.4. Driver

The driver: section describes optional modifications to the behavior of the LocalEnsembleDA driver. For details, refer to Local Ensemble Data Assimilation in OOPS in the JEDI Documentation.

save posterior mean: (Default: false)

Specifies whether to save the posterior mean. Valid values: true | false

Value	Description
true	save
false	do not save

save posterior mean increment: (Default: true)

Specifies whether to save the posterior mean increment. Valid values: true | false

Value	Description
true	enable
false	do not enable

save posterior ensemble: (Default: false)

Specifies whether to save the posterior ensemble. Valid values: true | false

Value	Description
true	enable
false	do not enable

run as observer only: (Default: false)

Specifies whether to run as observer only. Valid values: true | false

Value	Description
true	enable
false	do not enable

3.3.1.1.1.5. Local Ensemble DA

The local ensemble DA: section configures the local ensemble DA solver package.

solver: (Default: LETKF)

Specifies the type of solver. Currently, LETKF is the only available option. See Hunt et al. [HEJKS07] (2007).

inflation:

Describes ensemble inflation methods.

rtps: (Default: 0.0)

Relaxation to prior spread (Whitaker and Hamill [WH12], 2012).

rtpp: (Default: 0.0)

Relaxation to prior perturbation (Zhang et al. [ZCSS04], 2004).

mult: (Default: 1.0)

Parameter of multiplicative inflation.

3.3.1.1.1.6. Output Increment

output increment: (Default: fms restart)

filetype:

Type of file provided for the output increment. Valid values include: fms restart

filename_sfcd: (Default: xainc.sfc_data.nc)

Name of the file provided for the output increment. For example: xainc.sfc_data.nc

3.3.1.1.1.7. Observations

The observations: item describes one or more types of observations, each of which is a multi-level YAML/JSON object in and of itself. Each of these observation types is read into JEDI as an eckit::Configuration object (see JEDI Documentation for more details).

3.3.1.1.1.7.1. obs space:

The obs space: section of the YAML comes under the observations.observers: section and describes the configuration of the observation space. An observation space handles observation data for a single observation type.

name: (Default: SnowDepthGHCN)

Specifies the name of observation space. The Land DA System uses SnowDepthGHCN for the default case.

distribution:

name:

Specifies the name of the distribution. Valid values include: Halo

halo size:

Specifies the size of the distribution. Format is e-notation. For example: 250e3

simulated variables:

Specifies the list of variables that need to be simulated by the observation operator. Valid values: [totalSnowDepth]

obsdatain:

This section specifies information about the observation input data.

engine:

This section specifies parameters required for the file matching engine.

type: (Default: H5File)

Specifies the type of input observation data. Valid values: H5File | OBS

obsfile: (Default: GHCN_XXYYYYXXMMXXDDXXHH.nc)

Specifies the input filename.

obsdataout:

This section contains information about the observation output data.

engine:

This section specifies parameters required for the file matching engine.

type: (Default: H5File)

Specifies the type of output observation data. Valid values: H5File

obsfile: (Default: output/DA/hofx/letkf_hofx_ghcn_XXYYYYXXMMXXDDXXHH.nc)

Specifies the output file path.

3.3.1.1.1.7.2. obs operator:

The obs operator: section describes the observation operator and its options. An observation operator is used for computing H(x).

name: (Default: Identity)

Specifies the name in the ObsOperator and LinearObsOperator factory, defined in the C++ code. Valid values include: Identity. See JEDI Documentation for more options.

3.3.1.1.1.7.3. obs error:

The obs error: section explains how to calculate the observation error covariance matrix and gives instructions (required for DA applications). The key covariance model, which describes how observation error covariances are created, is frequently the first item in this section. For diagonal observation error covariances, only the diagonal option is currently supported.

covariance model:

Specifies the covariance model. Valid values include: diagonal

3.3.1.1.1.7.4. obs localizations:

obs localizations:

localization method:

Specifies the observation localization method. Valid values include: Horizontal SOAR | Vertical Brasnett

Value	Description
Horizontal SOAR	Second Order Auto-Regressive localization in the horizontal direction.
Vertical Brasnett	Vertical component of the localization scheme defined in Brasnett [Bra99] (1999) and used in the snow DA.

lengthscale:

Radius of influence (i.e., maximum distance of observations from the location being updated) in meters. Format is e-notation. For example: 250e3

soar horizontal decay:

Decay scale of SOAR localization function. Recommended value: 0.000021. Users may adjust based on need/preference.

max nobs:

Maximum number of observations used to update each location.

3.3.1.1.1.7.5. obs filters:

Observation filters are used to define Quality Control (QC) filters. They have access to observation values and metadata, model values at observation locations, simulated observation value, and their own private data. See Observation Filters in the JEDI Documentation for more detail. The obs filters: section contains the following fields:

filter:

Describes the parameters of a given QC filter. Valid values include: Bounds Check | Background Check | Domain Check | RejectList. See descriptions in the JEDI’s Generic QC Filters Documentation for more.

Filter Name	Description
Bounds Check	Rejects observations whose values lie outside specified limits:
Background Check	This filter checks for bias-corrected distance between the observation value and model-simulated value (y - H(x)) and rejects observations where the absolute difference is larger than the absolute threshold or the \(threshold * observation error\) or the \(threshold * background error\).
Domain Check	This filter retains all observations selected by the where statement and rejects all others.
RejectList	This is an alternative name for the BlackList filter, which rejects all observations selected by the where statement. The status of all others remains the same. Opposite of Domain Check filter.

filter variables:

Limit the action of a QC filter to a subset of variables or to specific channels.

name:

Name of the filter variable. Users may indicate additional filter variables using the name: field on consecutive lines (see code snippet below). Valid values include: totalSnowDepth

filter variables:
- name: variable_1
- name: variable_2

minvalue:

Minimum value for variables in the filter.

maxvalue:

Maximum value for variables in the filter.

threshold:

This variable may function differently depending on the filter it is used in. In the Background Check Filter, an observation is rejected when the difference between the observation value (y) and model simulated value (H(x)) is larger than the threshold * observation error.

action:

Indicates which action to take once an observation has been flagged by a filter. See Filter Actions in the JEDI documentation for a full explanation and list of valid values.

name:

The name of the desired action. Valid values include: accept | reject

where:

By default, filters are applied to all filter variables listed. The where keyword applies a filter only to observations meeting certain conditions. See the Where Statement section of the JEDI Documentation for a complete description of valid where conditions.

variable:

A list of variables to check using the where statement.

name:

Name of a variable to check using the where statement. Multiple variable names may be listed under variable. The conditions in the where statement will be applied to all of them. For example:

filter: Domain Check # land only
  where:
  - variable:
      name: variable_1
      name: variable_2
    minvalue: 0.5
    maxvalue: 1.5

minvalue:

Minimum value for variables in the where statement.

maxvalue:

Maximum value for variables in the where statement.

3.3.1.2. Interface for Observation Data Access (IODA)

This section references Honeyager, R., Herbener, S., Zhang, X., Shlyaeva, A., and Trémolet, Y., 2020: Observations in the Joint Effort for Data assimilation Integration (JEDI) - UFO and IODA. JCSDA Quarterly, 66, Winter 2020.

The Interface for Observation Data Access (IODA) is a subsystem of JEDI that can handle data processing for various models, including the Land DA System. Currently, observation data sets come in a variety of formats (e.g., netCDF, BUFR, GRIB) and may differ significantly in structure, quality, and spatiotemporal resolution/density. Such data must be pre-processed and converted into model-specific formats. This process often involves iterative, model-specific data conversion efforts and numerous cumbersome ad-hoc approaches to prepare observations. Requirements for observation files and I/O handling often result in decreased I/O and computational efficiency. IODA addresses this need to modernize observation data management and use in conjunction with the various components of the Unified Forecast System (UFS).

IODA provides a unified, model-agnostic method of sharing observation data and exchanging modeling and data assimilation results. The IODA effort centers on three core facets: (i) in-memory data access, (ii) definition of the IODA file format, and (iii) data store creation for long-term storage of observation data and diagnostics. The combination of these foci enables optimal isolation of the scientific code from the underlying data structures and data processing software while simultaneously promoting efficient I/O during the forecasting/DA process by providing a common file format and structured data storage.

The IODA file format represents observational field variables (e.g., temperature, salinity, humidity) and locations in two-dimensional tables, where the variables are represented by columns and the locations by rows. Metadata tables are associated with each axis of these data tables, and the location metadata hold the values describing each location (e.g., latitude, longitude). Actual data values are contained in a third dimension of the IODA data table; for instance: observation values, observation error, quality control flags, and simulated observation (H(x)) values.

Since the raw observational data come in various formats, a diverse set of “IODA converters” exists to transform the raw observation data files into IODA format. While many of these Python-based IODA converters have been developed to handle marine-based observations, users can utilize the “IODA converter engine” components to develop and implement their own IODA converters to prepare arbitrary observation types for data assimilation within JEDI. (See https://github.com/NOAA-PSL/land-DA_update/blob/develop/jedi/ioda/imsfv3_scf2iodaTemp.py for the Land DA IMS IODA converter.)

3.3.2. Input Files

The Land DA System requires grid description files, observation files, and restart files to perform snow DA.

3.3.2.1. Grid Description Files

The grid description files appear in Table 3.2 below:

Table 3.2 Input Files Containing Grid Information

Filename	Description
Cxx_grid.tile[1-6].nc	Cxx grid information for tiles 1-6, where xx is the grid resolution.
Cxx_oro_data.tile[1-6].nc oro_Cxx.mx100.tile[1-6].nc	Orography files that contain grid and land mask information. Cxx refers to the atmospheric resolution, and mx100 refers to the ocean resolution (100=1º). Both file names refer to the same file; there are symbolic links between them.

3.3.2.2. Observation Data

Observation data from 2000 are provided in NetCDF format for the v2.0.0 release. Instructions for downloading the data are provided in Section 2.2.3, and instructions for accessing the data on Level 1 Systems are provided in Section 2.1.4.2.1. Currently, data is taken from the Global Historical Climatology Network (GHCN), but eventually, data from the U.S. National Ice Center (USNIC) Interactive Multisensor Snow and Ice Mapping System (IMS) will also be available for use.

Users can view file header information and notes for NetCDF formatted files using the instructions in Section 3.2.1.1. For example, on Orion, users can run:

# Load modules:
module load netcdf/4.7.0
ncdump -h /work/noaa/epic/UFS_Land-DA_Dev/inputs/DA/snow_depth/GHCN/data_proc/v3/2000/ghcn_snwd_ioda_20000103.nc

to see the header contents of the 2000-01-03 GHCN snow depth file. Users may need to modify the module load command and the file path to reflect module versions/file paths that are available on their system.

3.3.2.2.1. Observation Types

3.3.2.2.1.1. GHCN Snow Depth Files

Snow depth observations are taken from the Global Historical Climatology Network, which provides daily climate summaries sourced from a global network of 100,000 stations. NOAA’s NCEI provides access to these snow depth and snowfall measurements through daily-generated individual station ASCII files or GZipped tar files of full-network observations on the NCEI server or Climate Data Online. Alternatively, users may acquire yearly tarballs via wget:

wget https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/by_year/{YYYY}.csv.gz

where ${YYYY} is replaced with the year of interest. Note that these yearly tarballs contain all measurement types from the daily GHCN output, and thus, snow depth must be manually extracted from this broader data set.

These raw snow depth observations need to be converted into IODA-formatted netCDF files for ingestion into the JEDI LETKF system. However, this process was preemptively handled outside of the Land DA workflow, and the 2019 GHCN IODA files were provided by NOAA PSL (Clara Draper).

The IODA-formatted GHCN files are available in the inputs/DA/snow_depth/GHCN/data_proc/v3/${YEAR} directory and are structured as follows (using 20000103 as an example):

netcdf ghcn_snwd_ioda_20000103 {
dimensions:
   Location = UNLIMITED ; // (10423 currently)
variables:
   int64 Location(Location) ;
      Location:suggested_chunk_dim = 10000LL ;

// global attributes:
             string :_ioda_layout = "ObsGroup" ;
             :_ioda_layout_version = 0 ;
             string :converter = "ghcn_snod2ioda.py" ;
             string :date_time_string = "2000-01-03T18:00:00Z" ;
             :nlocs = 10423 ;

group: MetaData {
   variables:
      int64 dateTime(Location) ;
         dateTime:_FillValue = -9223372036854775806LL ;
         string dateTime:units = "seconds since 1970-01-01T00:00:00Z" ;
      float latitude(Location) ;
         latitude:_FillValue = 9.96921e+36f ;
         string latitude:units = "degrees_north" ;
      float longitude(Location) ;
         longitude:_FillValue = 9.96921e+36f ;
         string longitude:units = "degrees_east" ;
      float stationElevation(Location) ;
         stationElevation:_FillValue = 9.96921e+36f ;
         string stationElevation:units = "m" ;
      string stationIdentification(Location) ;
         string stationIdentification:_FillValue = "" ;
   } // group MetaData

group: ObsError {
   variables:
      float totalSnowDepth(Location) ;
         totalSnowDepth:_FillValue = 9.96921e+36f ;
         string totalSnowDepth:coordinates = "longitude latitude" ;
         string totalSnowDepth:units = "mm" ;
   } // group ObsError

group: ObsValue {
   variables:
      float totalSnowDepth(Location) ;
         totalSnowDepth:_FillValue = 9.96921e+36f ;
         string totalSnowDepth:coordinates = "longitude latitude" ;
         string totalSnowDepth:units = "mm" ;
   } // group ObsValue

group: PreQC {
   variables:
      int totalSnowDepth(Location) ;
         totalSnowDepth:_FillValue = -2147483647 ;
         string totalSnowDepth:coordinates = "longitude latitude" ;
   } // group PreQC
}

The primary observation variable is totalSnowDepth, which, along with the metadata fields of datetime, latitude, longitude, and stationElevation is defined along the nlocs dimension. Also present are ObsError and PreQC values corresponding to each totalSnowDepth measurement on nlocs. These values were attributed during the IODA conversion step (not supported for this release). The magnitude of nlocs varies between files; this is due to the fact that the number of stations reporting snow depth observations for a given day can vary in the GHCN.

3.3.2.2.2. Observation Location and Processing

3.3.2.2.2.1. GHCN

GHCN files for 2000 and 2019 are already provided in IODA format for the v2.0.0 release. Table 2.1.4.2.1 indicates where users can find data on NOAA RDHPCS platforms. Tar files containing the 2000 and 2019 data are located in the publicly-available Land DA Data Bucket. Once untarred, the snow depth files are located in /inputs/DA/snow_depth/GHCN/data_proc/v3/${YEAR}. The 2019 GHCN IODA files were provided by Clara Draper (NOAA PSL). Each file follows the naming convention of ghcn_snwd_ioda_${YYYY}${MM}${DD}.nc, where ${YYYY} is the four-digit cycle year, ${MM} is the two-digit cycle month, and ${DD} is the two-digit cycle day.

In each experiment, the template.land_analysis.yaml file sets the type of observation file (e.g., OBS_TYPES: "GHCN"). Before assimilation, if “GHCN” was specified as the observation type, the ghcn_snwd_ioda_${YYYY}${MM}${DD}.nc file corresponding to the specified cycle date is copied to the run directory (usually $LANDDAROOT/ptmp/test/com/landda/$model_ver/landda.$PDY$cyc/obs by default — see Section 3.1.3.1 for more on these variables) with a naming-convention change (i.e., GHCN_${YYYY}${MM}${DD}${HH}.nc).

Prior to ingesting the GHCN IODA files via the LETKF at the DA analysis time, the observations are combined into a single letkf_land.yaml file, which is a concatenation of letkfoi_snow.yaml and GHCN.yaml (see Section 3.3.1.1.1 for further explanation). The GHCN-specific observation filters, domain checks, and quality control parameters from GHCN.yaml ensure that only snow depth observations which meet specific criteria are assimilated (the rest are rejected). View the contents of GHCN.yaml are on GitHub.

3.3.2.3. Restart Files

To restart the Land DA System successfully after land model execution, all parameters, states, and fluxes used for a subsequent time iteration are stored in a restart file. This restart file is named ufs_land_restart.${FILEDATE}.tile#.nc where FILEDATE is in YYYY-MM-DD_HH-mm-SS format and # is 1-6 (e.g., ufs_land_restart.2000-01-05_00-00-00.tile1.nc). The restart file contains all the model fields and their values at a specific point in time; this information can be used to restart the model immediately to run the next cycle. The Land DA System reads the states from the restart file and replaces them after the DA step with the updated analysis. Table 3.3 lists the fields in the Land DA restart file.

Table 3.3 Files Included in ufs_land_restart.{FILEDATE}.nc

Variable	Long name	Unit
time	time	“seconds since 1970-01-01 00:00:00”
timestep	time step	“seconds”
vegetation_fraction	Vegetation fraction	“-”
emissivity_total	surface emissivity	“-”
albedo_direct_vis	surface albedo - direct visible	“-”
albedo_direct_nir	surface albedo - direct NIR	“-”
albedo_diffuse_vis	surface albedo - diffuse visible	“-”
albedo_diffuse_nir	surface albedo - diffuse NIR	“-”
temperature_soil_bot	deep soil temperature	“K”
cm_noahmp	surface exchange coefficient for momentum	“m/s”
ch_noahmp	surface exchange coefficient heat & moisture	“m/s”
forcing_height	height of forcing	“m”
max_vegetation_frac	maximum fractional coverage of vegetation	“fraction”
albedo_total	grid composite albedo	“fraction”
snow_water_equiv	snow water equivalent	“mm”
snow_depth	snow depth	“m”
temperature_radiative	surface radiative temperature	“K”
soil_moisture_vol	volumetric moisture content in soil level	“m3/m3”
temperature_soil	temperature in soil level	“K”
soil_liquid_vol	volumetric liquid content in soil level	“m3/m3”
canopy_water	canopy moisture content	“m”
transpiration_heat	plant transpiration	“W/m2”
friction_velocity	friction velocity	“m/s”
z0_total	surface roughness	“m”
snow_cover_fraction	snow cover fraction	“fraction”
spec_humidity_surface	diagnostic specific humidity at surface	“kg/kg”
ground_heat_total	soil heat flux	“W/m2”
runoff_baseflow	drainage runoff	“mm/s”
latent_heat_total	latent heat flux	“W/m2”
sensible_heat_flux	sensible heat flux	“W/m2”
evaporation_potential	potential evaporation	“mm/s”
runoff_surface	surface runoff	“mm/s”
latent_heat_ground	direct soil latent heat flux	“W/m2”
latent_heat_canopy	canopy water latent heat flux	“W/m2”
snow_sublimation	sublimation/deposit from snowpack	“mm/s”
soil_moisture_total	total soil column moisture content	“mm”
precip_adv_heat_total	precipitation advected heat - total	“W/m2”
cosine_zenith	cosine of zenith angle	“-”
snow_levels	active snow levels	“-”
temperature_leaf	leaf temperature	“K”
temperature_ground	ground temperature	“K”
canopy_ice	canopy ice	“mm”
canopy_liquid	canopy liquid	“mm”
vapor_pres_canopy_air	water vapor pressure in canopy air space	“Pa”
temperature_canopy_air	temperature in canopy air space	“K”
canopy_wet_fraction	fraction of canopy covered by water	“-”
snow_water_equiv_old	snow water equivalent - before integration	“mm”
snow_albedo_old	snow albedo - before integration	“-”
snowfall	snowfall	“mm/s”
lake_water	depth of water in lake	“mm”
depth_water_table	depth to water table	“m”
aquifer_water	aquifer water content	“mm”
saturated_water	aquifer + saturated soil water content	“mm”
leaf_carbon	carbon in leaves	“g/m2”
root_carbon	carbon in roots	“g/m2”
stem_carbon	carbon in stems	“g/m2”
wood_carbon	carbon in wood	“g/m2”
soil_carbon_stable	stable carbon in soil	“g/m2”
soil_carbon_fast	fast carbon in soil	“g/m2”
leaf_area_index	leaf area index	“m2/m2”
stem_area_index	stem area index	“m2/m2”
snow_age	BATS non-dimensional snow age	“-”
soil_moisture_wtd	soil water content between bottom of the soil and water table	“m3/m3”
deep_recharge	deep recharge for runoff_option 5	“m”
recharge	recharge for runoff_option 5	“m”
temperature_2m	grid diagnostic temperature at 2 meters	“K”
spec_humidity_2m	grid diagnostic specific humidity at 2 meters	“kg/kg”
eq_soil_water_vol	equilibrium soil water content	“m3/m3”
temperature_snow	snow level temperature	“K”
interface_depth	layer-bottom depth from snow surface	“m”
snow_level_ice	ice content of snow levels	“mm”
snow_level_liquid	liquid content of snow levels	“mm”