Software for spatially-explicit simulation of forest dynamics

Detailed output files

The model saves its detailed output in a detailed output file. A simulation's detailed output file is in fact a collection of individual files packaged together. Within the detailed output package are two types of files: a copy of the parameter file originally used to perform the run, and individual timestep files, which hold the saved data for each timestep. All the files are written in plain text in the XML data format.

Contents of a detailed output file

Detailed output timestep files are collections of map files that you set up using the Edit-> Output setup window. They are identified by having "_x" added to the filename, where "x" is the timestep number. The parameter file copy is given the detailed output package's filename. Each file produced is then compressed using the GZIP program, and all the files for a single run are put into an archive file using the TAR program. The detailed output output for a single run is one file with a ".gz.tar" extension.

For example: if the parameter file "testpar.xml" was used to run 5 timesteps, with a detailed output file to be saved named "my detailed output", at the end of the run there would be a file named "my detailed output.gz.tar". This TAR archive would contain the following files:

  • "my detailed output.gz" - a copy of the "testpar.xml" parameter file
  • "my detailed output_0.gz" - the data saved after setup occurred, before the model started running. These are the initial conditions.
  • "my detailed output_1.gz" - the data saved after the first timestep had run
  • "my detailed output_2.gz" - the data saved after the second timestep had run
  • "my detailed output_3.gz" - the data saved after the third timestep had run
  • "my detailed output_4.gz" - the data saved after the fourth timestep had run
  • "my detailed output_5.gz" - the data saved after the fifth timestep had run

The ".gz" extension indicates that these files are compressed. If uncompressed, the ".gz" extension would be replaced with ".xml".

Detailed output files are very flexible and can contain any subset of the model's underlying tree and grid data. You pick each individual piece of data that you wish to save, and the frequency with which you wish to save it. The data can be saved at any interval from every timestep to only at the first and last timesteps, and each piece of data has its own save frequency. You can use this to cut down on detailed output file size. Data you are less interested in can be saved less frequently.

You can also save data separately for just a portion of the plot by defining subplots.

Viewing the data in a detailed output file

The data visualization capabilities of the model interface allow you to see your data graphically. If you want the data raw to do your own analysis, you can save the contents of individual maps within the detailed output files as tab-delimited text. The easiest way to write tree data is to use the Timestep tree writer tool listed in the "Tables" options after a detailed output file has been loaded for data visualization. Grid map data can be written from any grid map display.

Detailed output files as input to other runs

The maps in a detailed output timestep file can be used as initial conditions on a subsequent run, provided that they are compatible with the parameter file being used. See the Using output as input to a new run topic.

Copying and renaming detailed output files

Because of their structure, detailed output files cannot be renamed like ordinary files. If you change the file name, the file will be broken. Use the Copy detailed output file tool in the Tools menu to safely make a copy of the file with a new name. (You can safely copy and move detailed output files to different file locations as long as the name stays the same.)