Spatial Data Writer Items

Spatial Data Writers Report a Simulation Result for Every Cell in the Simulation Grid

Spatial Data Writers are how the VELMA simulation provides spatially-explicit results output.

Spatial Data Writers are layer- and result-specific. You must configure separate spatial data writerparameterizations for each result type you will to output, and for layer of that result type. (E.g. to getspatial data output for the Root Biomass pool layers 3 and 4, you would need to add and configure two separateSpatial Data Writer parameterizations to your simulation configuration.

23.1 - Spatial Data Writer Items by Model Type

Adding a Spatial Data Writer to a Simulation Configuration

Spatial Data Writers are optional. Simulation configurations contain zero instances of them by default. Whenadded, they do not change the simulation computations - they only report results.

To add a Spatial Data Writer to your simulation configuration:

Click the "Edit" "Spatial Data Writer" "Add a New Spatial Writer".

image

Clicking "Add a New Spatial Writer" opens the Spatial Writer Type and Name dialog which looks like this:

image

Leave the Spatial Data Writer Type selector set to "SpatialDataWriter".

The Spatial Data Writer Name must be unique (i.e. no other Spatial Data Writer already specified for thissimulation configuration can share the name you specify). Avoid whitespace and punctuation characters (e.g. "("and ")"). As an example, here are a couple of acceptable

names (assuming they're not already in use by another Spatial Data Writer, and the Spatial Data Writer we'readding will report layer 3 root biomass; "Root_Biomass_Layer_3" and "Root_L3".

23.2 - Spatial Data Writer Items Data Sources

Configuring a Spatial Data Writer's Parameters

After you click OK in the Spatial Data Writer's Type and Name dialog, the VELMA GUI adds the Spatial Data Writerto the simulation configuration, and sets the All Parameters tab's filters to display only the parameters of thenewly-added Spatial Data Writer.

Assuming we named our new Spatial Data Writer "Root_Biomass_Layer_3" and clicked OK, the VELMA GUI would looklike this afterwards:

image

Notice, in passing, that the configuration outline does not automatically get set by the GUI. In the examplescreen capture above, it displays "0.0 All Configuration Parameters" - which is not what is being displayed inthe parameterization table. This behavior is harmless.

A Spatial Data Writer has 7 parameters. None are optional, but one (modelClass) is set automatically bythe GUI, and two others (allowNonWatershedCellValues and trimOutputToWatershedBoundary) default toreasonable values automatically. The remaining 4 parameters specify when this parameterization writes itsspecified spatial data source to file, and what that spatial data source should be.

The Spatial Data Sources Parameter Specifies What Data Is Written

Set the initializeSpatialDataSources parameter to the name of the spatial data source you want to reportresults for. The name is case-sensitive, and must exactly match a name from the Table of Spatial Data Sourcesgiven below. Be careful to avoid leading or trailing whitespace when you enter the spatial data sources name;leading or trailing whitespace can "break" the simulation configuration.

If the spatial data source you choose is multi-layered (see the table), you may (in some instances, must)explicitly specify the layer you wish to write. Specify an explicit layer by adding it, comma-separated, afterthe spatial data source name. The range of valid layer numbers is [1 to 4].

For example: "BIOMASS_ROOT_N" specifies the spatial data source name for biomass root, and"BIOMASS_ROOT_N, 2" specifies biomass root data, layer 2 (enter these, and all parameterization values,without the surrounding quotation (") marks).

23.3 - Spatial Data Writer Items Core Scheduling

The Three "InitializeActive…" Parameters Specify When Data Is Written

Select "23.3 Spatial Data Writer Items Core Scheduling" from the All Parameters drop-down outline selector menu:

image

Set the initializeActiveLoops, initializeActiveYears and initializeActiveJdays parametervalues to the loop numbers, years and Julian day values that you want the Spatial Data Writer to write resultsfor.

Any specified Loop numbers, years or Julian days that are "beyond bounds" are ignored. I.e. if the simulationconfiguration specifies 3 loops, and the Spatial Data Writer initializeActiveLoops value is set to 4, nodata will ever be written. It is an error to specify negative numbers for Loop, Year or Jday parameters.

[TIP: Setting an initializeActiveLoops value greater than the number of loops the simulation configurationspecifies run is an unintuitive yet handy way to temporarily "shut off" a spatial data writer's output withoutremoving it from the simulation configuration.]

You may specify more than one value by separating values with commas, and you may specify an inclusive range ofvalues by separating the start and end values by dashes.

(E.g. specifying "1, 3-7, 12" for initializeActiveLoops would allow the spatial data writer towrite data in loops 1, loops 3 through 7, and loop 12 - assuming the simulation configuration's numberOfLoopsparameter is set to 12 or more.)

You May Emphasize the Watershed Cells, or Not

When the allowNonWatershedCellValues parameter is set false, its spatial data writer writes anycell value outside the watershed as NO_DATA (the value "-9999.0"). The default value is false,which makes it easy to discern the watershed's delineation in the results file. If you want the results file toinclude every cell value, regardless of whether a given cell is in or out of the watershed delineation, set thisparameter to true.

23.4 - Spatial Data Writer Items Output Map Size

You May Reduce the Dimensions of the Results Grid File

Select "23.4 Spatial Data Writer Items Output Map Size" from the All Parameters drop-down outline selector menu:

image

When trimOutputToWatershedBoundary is set false, the spatial data writer writes a results file withthe same grid dimensions at the simulation configuration's DEM file. This (default value) make it easy to overlySpatial Data Writer output results on top of the DEM, cover Id map, or soil Id map files. When set totrue, the spatial data writer writes a results file that contains only the cells within the boundingrectangle of the delineated watershed. Depending upon the size of the watershed relative to the overall DEM,this may result in Spatial Data Writer files that are smaller, and easier to review "by hand".

[TIP: Spatial Data Writer output results files are not really meant for "manual" review (e.g. via Notepad or asimilar simple text editor). The choice of the Grid ASCII format was for ease of use with GIS systems, and sothat they could be readily "fed back" into the VELMA Simulator as subsequent initialization input. However,there's nothing wrong with opening a results file in a text editor or spreadsheet for a quick sanity check.]

To reduce the Dimensions of the Results Grid File, click the All Parameters tab's configuration outline dropdownselector and select "23.4 Spatial Data Writer Items Output Map Size".

image

Spatial Data Writer Output is a Grid ASCII File

The VELMA simulator creates 1 .asc file each time a given Spatial Data Writer is triggered (based on its activeLoops, Years and Jdays parameter settings).

Spatial Data Writer output files are written to the Results Data Location folder. Their filenames always beginwith the prefix "Spatial_" and include the name of the spatial data source and layer number of the data theycontain. The dimensions of the Grid ASCII file match those of the simulation configuration's DEM .asc file,unless the trimOutputToWatershedBoundary parameter was set "true"; in that case, the dimensions of theSpatial Data Writer output file are those of the bounding box of the simulation run's delineated watershed.

Each data value in the output .asc file contains the value for the specified data source for a particular cell,on the particular loop, year and Julian day during the simulation run that the output file was written.

Spatial Data Writers and Spatial Data Writers are Different, but Complementary

A Spatial Data Writer reports a specific result for all the cells in the simulation watershed on user-specifieddays. A Spatial Data Writer reports all the results data available for a specific cell on user-specified days.Both are optional for simulation runs.

Table of Spatial Data Sources

This table lists the available spatial data source name and their layer requirements.

SpatialDataSource Keyword means:

The spatial data source keyword names that are valid values for the

initializeSpatialDataSources parameter value of a Spatial Data Writer's parameterization.

    "Type" means:
  • Accessor = Spatial Data that is not directly stored in a spatial data pool object.
  • Direct = Spatial Data that is directly stored in a spatial data pool object.
  • Buffered = Spatial Data directly stored in a spatial data pool object, but only when a Spatial Data Writerrequires it.

(In practice, you can ignore what type a spatial data source is when you are configuring a Spatial Data Writer.)

    Can Sum Column? means:
  • N/A = Not applicable
  • No = The data cannot be summed: if MultiLayer is "YES" for this type of data, then a layer must beexplicitly provided in the initializeSpatialDataSources parameter value.
  • Optional = If MultiLayer is "YES" for this type of data and no explicit layer number is indicated in theinitializeSpatialDataSources parameter value, the value reported will be the sum of all layer values at a givencell's location.
  • Always = The spatial data type is MultiLayer, but only summed data is available; no explicit layer value isallowed in the initializeSpatialDataSources parameter value.
Type SpatialDataSource Keyword MultiLayer? Can Sum Column?
Accessor AirTemperature N/A
Accessor CellWriter N/A
Accessor CoverAge N/A
Accessor CoverId N/A
Accessor DenitrificationLayer YES No
Accessor FlowAccumulation No
Accessor No3DenitrificationFactorLayer YES No
Accessor QetLayer YES No
Accessor Rain N/A
Accessor Snow N/A
Accessor SoilId N/A
Accessor SurfaceElevation N/A
Accessor TotalBiomassCarbon Always
Accessor TotalBiomassNitrogen Always
Accessor TotalDetritusCarbon Always
Accessor TotalDetritusNitrogen Always
Accessor TotalHumusCarbon Always
Accessor TotalVolumetricSoilMoisture Always
Accessor VolumetricSoilMoistureLayer YES No
Direct ACCUMULATED_DEGREE_DAY N/A
Direct ACCUMULATED_N_IN N/A
Direct ASYMBIOTIC_NITROGEN_FIXED N/A
Direct BIOMASS_AG_STEM_N N/A
Direct BIOMASS_APEX_TOTAL_STEM_N N/A
Direct BIOMASS_BG_STEM_N N/A
Direct BIOMASS_DELTA_AG_STEM_N N/A
Direct BIOMASS_DELTA_BG_STEM_N N/A
Direct BIOMASS_DELTA_LEAF_N N/A
Direct BIOMASS_DELTA_ROOT_N YES Optional
Direct BIOMASS_HARVESTED_TO_OFFSITE_C N/A
Direct BIOMASS_LEAF_N N/A
Direct BIOMASS_ROOT_N YES Optional
Direct CO2 YES Optional
Direct DENITRIFICATION YES Optional
Direct DENITRIFICATION_CO2_SCALAR YES Optional
Direct DENITRIFICATION_NO3_SCALAR YES Optional
Direct DENITRIFICATION_WATER_SCALAR YES Optional
Direct DETRITUS_AG_STEM_N N/A
Direct DETRITUS_BG_STEM_N YES Optional
Direct DETRITUS_BURNED_C N/A
Direct DETRITUS_LEAF_N N/A
Direct DETRITUS_ROOT_N YES Optional
Direct DOC YES Optional
Direct DON YES Optional
Direct GROUND_SURFACE_TEMPERATURE N/A
Direct GROUND_TEMPERATURE_LAYERS YES Optional
Direct HUMUS YES Optional
Direct LATERAL_INFLOW YES Optional
Direct LATERAL_OUTFLOW YES Optional
Direct NH4 YES Optional
Direct NITRIFICATION YES Optional
Direct NO3 YES Optional
Direct NPP_C N/A
Direct NPP_N N/A
Direct STANDING_WATER N/A
Direct SURFACE_LATERAL_OUTFLOW N/A
Direct SYMBIOTIC_NITROGEN_FIXED_HUMUS N/A
Direct SYMBIOTIC_NITROGEN_FIXED_PLANT N/A
Direct UPTAKE_N YES Optional
Direct WATER_STORED YES Optional
Buffered DOC_LATERAL_IN YES Optional
Buffered DOC_LATERAL_OUT YES Optional
Buffered DOC_LOSS YES Optional
Buffered DON_LATERAL_IN YES Optional
Buffered DON_LATERAL_OUT YES Optional
Buffered DON_LOSS YES Optional
Buffered FERTILIZATION_HUMUS_N_ADDED N/A
Buffered FERTILIZATION_NH4_ADDED N/A
Buffered FERTILIZATION_NO3_ADDED N/A
Buffered NH4_LATERAL_IN YES Optional
Buffered NH4_LATERAL_OUT YES Optional
Buffered NH4_LOSS YES Optional
Buffered NO3_LATERAL_IN YES Optional
Buffered NO3_LATERAL_OUT YES Optional
Buffered NO3_LOSS YES Optional