Page tree
Skip to end of metadata
Go to start of metadata

Function documentation

If you have a request for a DOME function, please let us know.

Data Overlay for Multimodel Export

Four types of DOME files have been developed to allow measured data from a farm or field experiment to be supplemented with additional assumed or hypothetical data, in order to direct crop model simulations.

Field overlay DOME: Data collected in regional surveys are often insufficient to characterize inputs for the crop model simulations. In these cases, it is necessary to provide harmonized assumptions uniformly over a region and across all crop models.  A field overlay DOME is used to fill in missing data with information required by crop models, but not specifically measured in the field. These data are used in the crop model simulations, but are stored separately for documentation purposes.  The DOME data are merged with ACE site data and the combined data stream is provided to the model-specific translators, which then produce model-ready crop model input files.

A second application of the DOME will be to apply management regimens, such as might be defined by RAPs (Representative Agricultural Pathways) for a region.  These management regimens would override existing recorded management and replace those data with the prescribed management regimen.

Seasonal Strategy DOME:  Data collected for a single season can be used for multi-year simulations with the use of a Seasonal strategy DOME. These simulations are used to study the effects of climate variability. All data, including initial soil conditions, are used for multiple simulations using a number of years of weather data.
Rotational Analysis DOME: Similar to the seasonal strategy, the Rotational analysis simulates multiple years of weather data, however under this analysis, the simulation is a sinlge continuous simulation, with intitial conditions being applied only once at the beginning of the simulation. These analyses are used to study long-term sustainability of management practices and the effects on soil fertility.
Batch DOME: Batch DOMEs are used to vary one or more variables in multiple simulations for the purposes of sensitivity analyses or to simulate multiple climate scenarios. The Batch DOME will result multiple translations of crop modeling data. These DOMEs are used to run C3MP analyses (

DOME Metadata

Metadata at the top of each DOME file describe the simulation for which the DOME data are being added.

!Sample Metadata for Seasonal Strategy 
!CommentDome_Name ->NIORO--R1-A1--IEXA-PD3! Auto-generated from following 6 fields.
&INFOREG_IDNIORO! Assigned by econ modeling teams
&INFOSTRATUM ! Assigned by econ modeling teams
&INFORAP_ID R1! Blank for baseline simulation
&INFOMAN_ID A1! Management ID
&INFORAP_VER ! Blank or zero for baseline simulation. Used for changes to RAP from a previous set of simulations.
&INFODESCRIPTIONPD3! FIELD=field overlay for filling in regional assumptions

These metadata are carried through to the ACMO file and used to describe each crop model simulation. If multiple DOMEs are used, metadata are used first from the Batch DOME, then the Seasonal Strategy DOME, then the field overlay, and finally from the data.

DOME functions

Each of the functions begins with a specification of whether this overlay should fill in where data are missing ("FILL" operator) or whether the existing data in the database should be replaced with the specified value ("REPLACE" operator). The "FILL" operator should be used where observed data are insufficient or incomplete for crop model simulations. The "REPLACE" operator is typically used to override baseline management to impose a hypothetical management regimen.

The following types of specifications are proposed:

  • Direct replacement or filling in missing values of ICASA variables with a specified value. Examples:
    • FILL, PLPOP, 2.5
      A planting density (PLPOP) of 2.5 plants/m2 will be used only for sites where planting population was not recorded. Actual recorded plant populations will be used where available.
    • REPLACE, PLPOP, 2.5
      A planting density (PLPOP) of 2.5 plants/m2 will be used for all sites in the batch of simulations, overriding any observed values.
    • FILL, APSIM_CONA, 3.5
      Uses a value of 3.5 for the APSIM-specific 2nd stage soil evaporation coefficient, CONA.
      Set the fertilizer application date (FEDATE) to the user-supplied value of planting date (PDATE), when the value has not been supplied.
  • Use known data and a selected function to fill in missing values or replace all values. Examples:
      Fertilizer application date, FEDATE, is computed to be 14 days after the recorded planting date for all sites, using the OFFSET function.
    • FILL, ICH20, PCTAWC(), 50
      Sets initial soil water content, variable ICH2O, at 50% of available water capacity using the PCTAWC function where initial soil water contents were not originally specified.

Syntax for a DOME specification:

  • Column 1 "!" denotes comment, "&" denotes a DOME operative 
  • Column 2 contains one of three DOME operatives: "FILL", "REPLACE" or "INFO".
  • Column 3 contains the name of the variable to be modified. 
    • If a DOME function modifies more than one variable, any one of them may be used here.
    • Variable names refer to ICASA variables (ICASA Master Variable List)
  • Column 4 contains the value of the variable or the name of a DOME function.
    • DOME Function names always include empty parentheses after the name to indicate that it is a function, e.g., OFFSET() or ROOT_DIST()
    • ICASA variable names are preceded by a $ when used as a value or a function argument, e.g., $PDATE
  • Column 5 and higher contain the function arguments. Refer to documentation in this wiki for the arguments required by each function.

Sample DOME functions used to fill in soil parameters in a field overlay DOME:

!Soil Parameters     
!Dome operatorVariable to be modifiedValue or FunctionFunction arguments  
! Soil organic C array (%)Root distribution functionValue in topsoil (%)Depth of topsoil (cm)Depth at which value is 2% of surface amount (cm)
! Soil organic C array (%)Root distribution functionValue in topsoil (%)Depth of topsoil (cm)Depth at which value is 2% of surface amount (cm)
! Stable organic C array (%)Distribution of stable organic C functionFraction of stable organic C in topsoil (fraction)Depth of topsoil (cm)Depth at which SOM3 is ~98% of total (cm)
! Inert organic C arrayMultiply functionstable organic Cmultiplier 
! soil fertility factor for photosynthesisvalue   


Sample DOME file in Excel format

This file contains an annotated sample of common DOME commands, including annotations about the order of functions, dependencies on other data and syntax. Also included are details of several of the functions, including graphs that can be manipulated to see responses to input variables.

DOME functions_v1.5.xlsx

The following file shows the continuance feature (using + mark at first column)


Uses for DOME functions:

Examples of some of the variables that can potentially be supplied by the DOME are:

  • Start of simulation date (SDATE)
  • Initialization date (ICDAT)
  • Initial soil water content by soil layer (ICH2O, mm3/mm3) as a percentage of available water capacity using function PCTAWC
  • Initial soil layer distributions of NH4 (ICNH4, ppm), NO3 (ICNO3, ppm), total organic carbon (SLOC, %), fresh organic matter and other variables using various distribution functions
  • Proportions of stable, intermediate, microbial and inert organic carbon pools 
  • Planting date based on a total rainfall accumulation over n days within a given planting window
  • Details of fertilizer application including date or relative date, proportion of total N applied in the season (a known value), fertilizer type, application method and depth of incorporation. Multiple fertilizer applications can be specied.
  • Details of organic amendment applications including date or relative date, proportion of total dry matter applied, type of organic matter, C:N ratio, application method, depth of incorporation, and percent incorporation.
  • Model-specific variables:
    • SLPF (DSSAT)
    • drainage coefficient
    • runoff CN
    • CONA (APSIM)
    • potential root distribution functions
  • Number of years of simulation (EXP_DUR)

Model-specific variables that can be specified in the DOME are listed here. These variables are not listed in the ICASA Master Variable list, but can still be used for a particular model by using a model prefix. 

Set linkage between DOME and field with link file:

Linkage between ACE data and one or more DOMEs is done through a Linkage file. The link file is a spreadsheet file in CSV format, the extension could be *.alnk or *.csv. Following is a sample to show the structure of the link file. Basically it is a lite version of ACMO CSV file, and that means you can use ACMO file as link file to re-run existing experiments.


EXNAME                            : The experiment name, is required when try to assign the DOMEs to a particular experiment.

FIELD_OVERLAY              : The field overlay DOME id. When apply multiple DOME to one target, use "|" to divide each DOME ids.

SEASONAL_STRATEGY  The seasonal strategy DOME id. When apply multiple DOME to one target, use "|" to divide each DOME ids.

ROTATIONAL_ANALYSIS The rotational analysis DOME id. When apply multiple DOME to one target, use "|" to divide each DOME ids. Currently its functionality is not implemented yet.

SOIL_ID                              : The soil id, is required when experiment is not provided, otherwise it could be ignored

WST_ID                              : The weather station id, is required when experiment is not provided, otherwise it could be ignored.

You can also find the latest sample link CSV file from Github by click here.
Secondly, you need to load this file via the input box located in the user interface as follow.
  1. Check the check box marked below to active the input box for linkage file.

2. Load the link file via the marked input box


Finally, run the translation and see if the expected DOME is applied to your data.

  • No labels