How to create an analysis file

General information about analysis files

The analysis or initial contition files is a file which must contain certain atmospheric and surface fields which the model will use to initialize the run. Therefore the fields must cover the model grid region and the date must be the starting date of the run. But the resolution and grid orientation can be different from the model grid.

Atmospheric fields

The atmospheric fields can be on model or pressure levels. (Idealy on the same model level than the model.)
These are the minimum fields needed to to initialize a run:

Fields on pressure levels:

Fields on model levels:

Surface fields

for water/ocean:

    TM : sea surface temperature
    LG : sea ice fraction (GL in model output!)

for ISBA:

    I0 : surface and soil temperatures
    I1 : soil volumetric water contents
    I2 : soil volumetric ice contents
    I3 : water retained on the vegetation
    I4 : water in the snow pack
    I6 : albedo of snow
    I7 : sea ice temperature
    I8 : sea ice thickness
    I9 : glaciers temperature
    SD : snow depth
    DN : snow density in kg/m3

for CLASS:

same as for ISBA plus the following fields:

    I5  : snow mass (SWE)
    SK : snow stored on canopy
    R2 : temperature at the base of soil water column
    Q4 : temperature of water lying on the surface
    M9 : height of water lying on the surface
    TN : ground snow temperature
    TE : canopy temperature
    GR : canopy growth factor

for lakes schemes:

    common fields:
    LIFR : Lake ice fraction
    LITH : Lake ice thickness (optional)
    LITP  : Lake ice surface temperature (optional)
    LTRN : Lake water transparency (optional)
    LMLD : Lake mixed layer thickness (optional)

    FLake fields:
    LSF   : Lake shape factor (thermocline) (optional)
    LMLT : Lake mixed layer temperature (optional)
    LBTP : Lake bottom temperature (optional)
    LWTP : Lake water average temperature (optional)

    Hostetler fields:
    LTLT : Lake top layer temperature (optional)
    LTPF : Lake water vertical temp profile (optional)



There are already several analysis files on 'guillimin' & 'cedar' & 'beluga' under ${MODEL_DATA}/Analysis

One can use any of these analysis files. Pick the one that fits best to your grid and of course your start date. If you cannot find the right start date you can also take an analysis file for another date (i.e. another year) and change the date in the file.


Analysis files for LAM grids

If an analysis file is used to initialize a LAM run it is recommended to use for the atmospheric fields in the analysis files fields from the same data which will be use to pilot the run.

Here is an example to create an analysis file 'anal_sgmip2r05+ERA40_1996090100' for a LAM run which will be piloted with ERA40 starting September 1st 1996:
  1. Go in the directory in which you want to create the analysis file.
  2. Set variables for analysis file and archive, i.e.:
    anal_file=anal_sgmip2r05_1996090100
    anal_arch=/local/sata1/data/Analysis/Global_360x180_v321/analyses_sgmip2r05_part2.ca
  3. Unarchive the analysis file: cmcarc -x ${anal_file} -f ${anal_arch}
  4. Set variables for pilot file, i.e.:
    pil_file=pranalec_199609010000
    pil_arch=/local/sata1/data/ERA40/nest_info_era40_199608_part1.ca     Note: The pilot file for the 1st of a month at 0 zulu is always in the archive of the previous month!
  5. Unarchive the pilot file:cmcarc -x ${pil_file} -f ${pil_arch}
    6. Note that the pilot file for the first day of a month at 0 zulu is always in the archive of the previous month!
  6. Extract the surface fields from the analysis file:rm -f surface_fields
    echo "desire(-1,['I0','I1','I2','I3','I4','I6','I7','I8'])
          desire(-1,['I9','SD','DN','TM','LG','^^','>>'])" | editfst2000 -s ${anal_file} -d surface_fields
  7. Add the atmospheric fields from the pilot file to the surface fields, i.e.:r.diag2000 joinup ./anal_sgmip2r05+ERA40_1996090100 surface_fields ${pil_file}
  8. Erase the original analysis file and the pilot file since you don't need them anymore:rm -f ${anal_file} ${pil_file} surface_fields

Change the date

If you cannot find an analysis file with the right date, you can take another one (or part of one), i.e. from another year, and "change" the date. Let's say you have only an analysis file with a validity date for 1996090100 but you need one for 1999090100.

To check the validity date in an RPN standart file you can use 'r.fstliste'. Type 'r.fstliste -help' to get a list of all possible keys. (The program is similar to 'voir' but provides more information.) I.e.:
r.fstliste -izfst anal_sgmip2r05+ERA40_1996090100 For each record you will get a list of field descriptors. In this case the most important are:
The validity date for all fields mentioned above needs to match the start date of your simulation. If this is not the case you need to change it!

The problem with this is that you cannot directly change the validity date but only the start date. Though the difference between the start date and the validity date will always stay the same. So if you want to, let's say, move the validity date 3 years ahead, you need to move the start date 3 years ahead. Be careful with leap years!!! If leap years are involved you might have to move the start date one day more or less.

Since you need to change the start date according to the validity date you can only treat files having the same start and validity date for all fields. So in this example you would first have to separate the surface from the 3D fields. (Or better change the dates before doing step 5 above.)

First you need to calculate the new start date. In our example this is trivial for the 3D fields since for them start and validity date are the same. So the new start date for the 3D fields would be 1999090100.

Now we come to the surface fields. We want to move the validity date 3 years forwards, so the new start date will be 1978010100 + 3 years = 1981010100. But since there is a leap year involved, we need to set the start date to 1980123100. You can either find the new start date by try and error or do this little calculation:
# Current validity date in julien hours:
v1=`cdate -gj 1996 09 01 00`
# New validity date in julien hours:
v2=`cdate -gj 1999 09 01 00`
# Difference in julien hours:
diff=$(( ${v2} - ${v1} ))
# Current start date in julien hours:
s1=`cdate -gj 1978 01 01 00`
# New start date in julien hours:
s2=$(( ${s1} + ${diff} ))
# New start date in YYYY MM DD HH:
cdate -jg ${s2}

Once you know the new start date you need the cmc time stamp (the coded date), i.e. for the surface fields: CMCSTAMP=`r.date -Sn 1980123100`
Now you can zap (change) the date:
echo "zap(-1,-1,-1,${CMCSTAMP})" | editfst2000 -s surface_fields -d surface_fields_19990901
Be sure to check the validity dates in the new file again with 'r.fstliste'.



Author: Katja Winger
Last update: February 2009