The APSIM Report Module (REPORT)

Operation

The APSIM report module creates a columnar output file to record data from an APSIM simulation. Output files contain data in columns with headers specifying variable names and units. There is an option to create the files in CSV (comma delimited) format, for direct spreadsheet application.

Parameter file settings

The APSIM report module can report the state of any variable available to the system, from any module. The user can specify various reporting parameters and the method for doing this is similar to the initialisation of parameters in any other module.

The settings available to the user are as follows:-

The output file will be overwritten without warning.

The following example describes the many powerful aspects of the APSIM reporting module. In the control file we could have a line such as

module = report report.par[all_treatments] report.par[treatment1]

This shows that the report module's parameter data is in the file “report.par” in two user defined data groupings:- one group for data specific to treatment one and another group for data relevant to all treatments.

In the file “report.par” we would then have the following sections:-

[treatment1.report.parameters]

    outputfile     = c:\apsim\outputs\treat1.out

[treatment2.report.parameters]

    outputfile     = c:\apsim\outputs\treat2.out

[all_treatments.report.parameters]

    variable = year

    variable = clock.day

    variable = clock.today as date format dd/mm/yyyy

    variable = tracker.sum@rain as tot_rain

    variable = soilwat2.sw

    variable = soilwat2.sw_dep(1) as sw(1)

    variable = soilwat2.sw_dep() as totsw

    variable = wheat.yield as grn_yield

Here we specify a unique output file for each treatment, but the list of outputs will be the same for simulation of all treatments.

Several reporting features are included in the above example.

• The module name (the ‘ x ' in ‘ x.y ') of the reported variable is optional. An error will occur if the module name is omitted and more than one variable of the same name is present the system.
• The day and year are output as supplied by the clock module. No alias is used and so the column headings in the output file will be “day” and “year”. This is the simplest output specification.
• Several of the output variables have been assigned aliases. For example the variable “yield” from the wheat module is given the alias “grn_yield” and this alias will be what is used in the column header of the output file. If no alias is desired then a single dash “-” is placed in the row to signify this.
• The variable “sw” is an array. It cannot be identified as such by simply viewing the reporting parameters but the report module will recognise this when data is sent to it. The output file will record sw using a column for each element in the array.
• The variable “sw_dep” is also an array. The example has two outputs for this variable. The first use specifies that only the first element of the array is to be output. The second use has no array index in between the brackets. In this case all elements in the array will be added together to find a sum total of the array and this will be output in a single column in the output file.
• The variable 'today' is being output with an alias of 'date' and formatting of dd/mm/yyyy. The format string can contain any combination of d, dd, mm, mmm, mmmmmm, yy, yyyy in any order and with any sort of delimiter character e.g. '/' or '-' or '_'

Setting reporting frequency

APSIM report carries its flexibility into the area of reporting frequency. There are two main ways to tell the REPORT module to do an output.

The first is to simply specify the APSIM events that should be used to trigger a line of output in the output file. This is done by using the ‘OutputFrequency' parameter. E.g.

[longterm.report.parameters]

    Outputfile = grower.yearlyout

    OutputFrequency = harvesting

    variable = clock.year as sow_year

    variable = clock.dd/mm/yyyy as date

    variable = clock.day

    variable = manager.wet_yield

    variable = manager.n_available_to_date

In this sample, a line of output will be written immediately the REPORT module receives a ‘harvesting' event from any module in APSIM. The event name can also be qualified by a module name by using the format ‘modulename.eventname'. Multiple events may be specified by separating them with spaces.

The second method involves manually instructing the REPORT module to do an output, usually by using the MANAGE.

The report module accepts a “do_output” action in a message “report do_output” which has no data, and upon receipt, writes the variable values to the output file.

For example, the manager may contain the following

if (day = 100) then

    report do_output

endif

tells the report module to output on day 100.

Or, by putting the report directive with the harvesting criteria in the management file we automatically get an output whenever harvesting takes place.

if (crop.stage_name = ‘maturity') then

    report do_output

    crop harvest

endif

The simplest management reporting criteria would he

[xxx.manager.start_of_day]

    report do_output

on its own. The absence of criteria here means that reporting will occur every single timestep.

Another management reporting option is the

report do_end_day_output

This option forces the output to operate at the “end of the day” regardless of which manager section it appears as opposed to the standard report do_output which reports immediately.

Instantiation of the Report module

Like all other APSIM modules the report module can be instantiated to allow any number of output files to be created. By specifying an instantiated report module in the control file, you are able to create more output files and populate them with output from your simulation. An example “con” file may appear as;

[apsim.sample_report]

Module=clock report.par[sample]%apsuite\apsim\clock\clock.ini[standard]

Module=report (report1) report.par [sample]

Module=report (report2) report.par [sample]

Module=met DALBY.MET [weather]

Module=manager report.par [sample]

This can be referenced in the “report.par” file as;

[sample.report1.parameters]

title = Report Instantiation Sample Simulation file 1

outputfile = report1.out

variable = clock.day

variable = clock.year

variable = met.rain

[sample.report2.parameters]

title = Report Instantiation Sample Simulation file 2

outputfile = report2.out

variable = clock.day

variable = clock.year

variable = wheat.yield

[sample.manager.end_of_day]

if days_since_last_report = 5 then

    report1 do_output

    report2 do_output

endif