Upgrading STICS XML files

Source: vignettes/Upgrading_STICS_XML_files.Rmd

The XML files structure has changed between STICS version 9.2 and versions 10.X.Y and a transformation is mandatory.

So, to avoid difficulties and errors with manual XML files modifications, functionalities have been developed to do so automatically.

One can either transform a complete workspace directory at once or each kind of file individually.

Upgrading a whole workspace

In that case, a workspace adapted to the new version is recreated.

So, apart from the XML files, some other files as outputs definition files (*.mod), weather files attached to USMs and also observation files (named with the USM name, *.obs) are copied to the new workspace.

workspace <- "/path/to/workspace/dir/V9.2"
out_dir <- "/path/to/out/dir/V10.2.0"
javastics <- "/path/to/JavaSTICS-1.41-stics-9.2"
upgrade_workspace_xml(workspace = workspace, javastics = javastics, out_dir = out_dir)

Here is the output display indicating the treated files:

Upgrading files from version V9.2 to V10.2.0    
From:  /path/to/workspace/dir/V9.2   
To:  /path/to/out/dir/V10.2.0    
-----------------------------------   
param_gen.xml   
param_new_form.xml   
usms.xml   
sols.xml   
*_sta.xml   
*_ini.xml   
*_tec.xml   
Copying *.mod files.   
Copying *.obs files.   
Copying weather files.   
*_plt.xml    
-----------------------------------   
Files upgrade and copy is complete.

Upgrading a specific file kind

For each kind of file, a specific function is to be used for upgrading its format.

  • usms.xml : upgrade_usms_xml
  • *_ini.xml files: upgrade_ini_xml
  • param_gen.xml: upgrade_param_gen_xml
  • param_newform.xml: upgrade_param_newform_xml
  • *_plt.xml files: upgrade_plt_xml
  • sols.xml: upgrade_sols_xml
  • *_sta.xml files: upgrade_sta_xml
  • *_tec.xml files: upgrade_tec_xml

The input arguments of these functions may vary, refer to each function help for details about its use.

Sometimes, general parameter files are needed as function inputs because of parameters or options codes movement to specific files.

For example, the usms.xml file is to be upgraded as follows:

usms_path <- "/path/to/workspace/dir/V9.2/usms.xml"
out_dir <- "/path/to/workspace/dir/V10.2.0"
param_gen_path <- "/path/to/JavaSTICS-1.41-stics-9.2/config/param_gen.xml"
upgrade_usms_xml(file = usms_path, param_gen_file = param_gen_path, out_dir = out_dir)