CFstandarization of the domain characteristics for ORCDHIEE

In this page some recommendations are given in order to standardize the files used to define the domain characteristics of ORCDHIEE and ensure that XIOS will be able to read and interpolate them to the model grid. It is attempted to be as close as possible to the CF-conventions standard: ​CF-conventions

Dimensions

Files must have at least two dimensions for the geographical localization, labeled lon and lat Files might have other dimensions:

• time: for files with temporal evolution of the values
• Ntypes: for files where a percentage of a series of types is given at each grid cell
• Lstring: A string length (typically 80 characters) to provide self-explicative information about the content of the file (when applicable)

Dimensional variables

These are the variables which provide information about the records of the dimensions

• lon, lat: These two variables provide the geo-localization of the data. They need to have three attributes:
  1. standard_name : longitude/latitude
  2. long_name : Longitude/Latitude
  3. units : degrees_East/degrees_North

If the map is not a regular longitude latitude grid, then the bounds of each cell are needed. The CF-convention needs to be followed ​http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#_data_representative_of_cells

• time: These variable must be used to provide information about the temporal dimension. It need to have three attributes:
  1. standard_name: time
  2. long_name: description of the temporal axis (e.g.: multi-year mean monthly values)
  3. units: units of the steps and origin of the axis (e.g.: month/seconds since date) ​http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#time-axis-ex

• typenames(Ntypes,Lstring): This variable should be used to provide consistent and human readable information about the types defined in each grid cell. It can refer to two different kind of information:
  • axis-values: For that variables where at each grid-point there is an additional dimension (e.g.: on 'PFTmap.nc' grid point have 13 levels, which corresponds to the fraction of each PFT)
  • range-values: At each grid point can find a unique integer value within a given range (e.g.: on 'carteveg5km.nc' there are 94 Olson-type of pfts)

Each type should have a clear description of the assigned value (e.g.: for `PFTmap.nc' )

value string

1	bare soil
2	tropical broad-leaved evergreen
3	tropical broad-leaved raingreen
4	temperate needleleaf evergreen
5	temperate broad-leaved evergreen
6	temperate broad-leaved summergreen
7	boreal needleleaf evergreen
8	boreal broad-leaved summergree
9	boreal needleleaf summergreen
10	C3 grass
11	C4 grass
12	C3 agriculture
13	C4 agriculture

Variable

The variable which content the data to be interpolated to the desired resolution to run ORCDHIEE. If the range of values is known that the field can take, please make sure that there is not any value outside the range. No data checks will be made by ORCDHIEE previously its interpolation. Currently (12 Arpil 2016) ORCHIDEE make a series of checks previously to the interpolation (see table below, these checks will be remove in the future). At the same time, it should have the following attributes:

• standard_name : provide a clear short name for its identification
• long_name : provide a clear description of the meaning of the variable
• units : provide units of the variable (e.g.: 1, for fractions)
• _FillValue : the value of the variable for which there is not value. If the variable only exists over continents (as is mostly the case for ORCHIDEE) then all oceanic points should be set to the value of _FillValue.
• valid_min : Valid minimal value of the variable (any `missing' value should be outside the [valid_min, valid_max])
• valid_max : Valid maximum value of the variable
• article : reference to the article or articles from which the data is retrieved
• dataset : name of the data-set from which the data was generated/processed (when applicable)

Land-See mask

A specific variable for the land-sea mask is strongly discouraged. This information should be provided by masking the oceanic points using the "_FillValue" attribute to the variable. Only this method can ensure that the interpolation masks properly this data.

Current file checks/mask

file name	var name	var dims	check	mask	Original File	CF complient file	Retro-compatibility
PFTmap.nc	maxvegetfrac	3D	--	min_sechiba < SUM(maxvegetfrac(i,j)) < 1.-1.e-7 1.-1.e-7 < SUM(maxvegetfrac(i,j)) < 2.	​XXX	​YYY	Yes
soils_param.nc	soiltext	2D	--	> min_sechiba	​XXX	​YYY	Yes
soils_param.nc	soilcolor	2D	--	> min_sechiba	​XXX	​YYY	Yes
alb_bg_jrctip.nc	bg_albedo	4D	--	variable 'mask' in file	​XXX	​YYY	Yes
cartepente2d_15min.nc	pente	2D	--	> min_sechiba	​XXX	​YYY	Yes
lai2D.nc	LAI	4D	< 0.	< 20.	​XXX	​YYY	Yes
carteveget5km.nc	vegetation_map	2D	--	> min_sechiba	​XXX	​YYY	Yes
orchidee_fertilizer_1995.nc	N_qt_WRICE_year	2D	--	--	​XXX	​YYY	Yes
orchidee_fertilizer_1995.nc	N_qt_OTHER_year	2D	--	--	​XXX	​YYY	Yes
orchidee_bbg_clim.nc	flx_co2_bbg_year	2D	--	--	​XXX	​YYY	Yes
reftemp.nc	temperature	2D	--	--	​XXX	​YYY	Yes

file rectifier

A python script file_rectifier.py​ is provided to rectify input files. One should at least provide: filename, name of the variable to rectify, range of the variable, names of the variables with the longitudes, latitudes and output file. A series of complementary arguments will be demanded as function of the characteristics of the variable. Different methodologies to generate the sea/land mask are provided.

$ python file_rectifier.py -f [filename] -v [varname] -r [varmin],[varmax] -d [londimname],[latdimname] -l [lonname],[latname] -m [maskmethod] -z [oceanvalue] -o [outputfile] -A [extraAttributes]

file checker

A python script file_checker.py​ is provided to check the consistency of the file. One should only provide the filename. It will check for the presence of the mandatory variables: 'lon', 'lat', 'mask' and realize other complementary tests

$ python file_checker.py -f [filename]

Presentation

Some slides about the work done presented on the ORCHIDEE meeting on 7th June 2016 at LSCE, are available here DYNAMICO_ORCDHIDEE.pdf​