Modifying a VELMA SpatialData Pool Using Grid ASCII Map Data

Overview

The contents of a VELMA simulator spatial data pool can be modified at an arbitrary simulation step, or at multiple steps, by specifying "Modify Spatial Data By Map" (shorthand term: "Modify-By-Map") disturbances as part of a simulator run's simulation configuration. Each spatial data pool (and each layer of that pool for multi-layer pools) that is modified must have a separate disturbance specified and parameterized for it, and its own Grid ASCII (.asc) map file available for the disturbance to use as a data source.

Requirements

One Modify-By-Map item parameterization per spatial data pool, layer, and modification. (Modifying multiple layers of a single spatial data pool requires multiple Modify-By-Map item parameterizations.)
One Grid ASCII (.asc) map file per Modify-By-Map item parameterization.
The .asc map file must have the same dimensions as the simulation's specified DEM Grid file.
The .asc map file's values may be positive or negative, but units for the values are assumed to match the units of the targeted spatial data pool. No error-checking or validation of the values is performed.

Adding a Modify-By-Map Disturbance to a Simulation Configuration

In JVelma, with a simulation configuration created or loaded, click/open the menu item: Edit -> Disturbances -> Add a Disturbance
In the Disturbance Model Selector dialog, scroll down through the drop-down selector items list to ModifySpatialDataByMapDisturbanceModel and click/set it as the Disturbance Type.
In the text box next to the "Disturbance Name" prompt, type a name for this specific disturbance.
The name must be unique, and must also be an valid Xml identifier (e.g., cannot start with a numeral).
Best practice when selecting a name: avoid whitespaces (use underscore '_' characters instead) and (apart from hyphen and underscore) eschew non-alphanumeric characters.
Click the dialog's OK button.
This closes the dialog, and adds a new Modify-By-Map item parameterization to your simulation configuration

Configuring a Modify-By-Map Disturbance's Parameters

Modify-By-Map parameters specify ...

When the modification should occur,
The source for modification data (i.e. the Grid .asc map file to use),
The target spatial data pool to modify,
How the source data map's values should modify the target spatial data pool's values. (The Modify-By-Map item parameterization also contains a metadata parameter, but its value should be left untouched.)

When Parameters

Parameter Name	Expected Value	Description	Can leave blank?
`initializeActiveLoops`	One-based Loop number(s)	The disturbance can occur only in listed Loops	NO
`initializeActiveYears`	Full-digits Year number(s)	The disturbance can occur only in listed Years	NO
`initializeActiveJdays`	Julian day(s)	The disturbance occurs for every listed Jday	NO
`occursAtStepStart`	"true" or "false" (without quotes)	determines whether the disturbance occurs at the beginning or the end of simulation steps	NO

The following rules apply to values for the Loop, Year, and Jdays parameters.

All values must be positive integers.
The parameter value as whole may consist of:
- a single value (e.g. 1)
- a range (e.g. 1999-2010)
- or a list of values and/or ranges (e.g. 1, 32, 59, 100-205, 365, 366)
Lists elements must be comma-separated.
Loop values outside of the [1, numberOfLoops] are ignored.
Year values must be full values (e.g. the "99" is treated as the year 99, not the year 1999).
Year values outside the range of the simulation configuration's [syear, eyear] (start year and end year) parameter values are ignored.
Jday values outside the range [1, 366] are ignored, and the value 366 is ignore in non-leap years.

Source Parameters

Parameter Name	Expected Value	Description	Can leave blank?
`spatialDataFileFullName`	A filename	The full or partial path+name of a valid Grid ASCII (.asc) map file	NO

Unless the specified filename is a fully-specified path + name, it is assumed to be relative to the directory, location specified by the simulation configuration's inputDataLocationRootName/inputDataLocationDirName pair of parameters.

Use forward slash “/” characters as path separators. Also, be very careful with whitespace; if there is any, it must exactly match whatever whitespace is present in the actual path and filename.

Target Parameters

Parameter Name	Expected Value	Description	Can leave blank?
`spatialDataName`	A SpatialData keynames	The name of the spatial data pool to modify	NO
`spatialDataLayer`	One-based layer index number	The layer of the SpatialData	NO

When the spatialDataName value specifies a single-layer spatial data pool, the spatialDataLayer value must be set to 1. Setting spatialDataLayer to a value > the number of layers in a spatial data pool is not caught during simulation initialization, but will cause a runtime error.

VELMA SpatialData pool keynames are listed in a separate document.

How Parameters

Parameter Name	Expected Value	Description	Can leave blank?
`setCellOutcome`	"AUGMENT" or "REPLACE" (without quotes)	Determines if target value is augmented or replaced by source value	NO
`setMapValueMode`	"VALUE" or "FRACTION" (without quotes)	Determines if source value should be treated as a fraction or not	NO

Combining the setCellOutcome and setMapValueMode parameter's values determines which of the four possible operations a given Modify-By-Map item performs:

`setCellOutcome`	`setMapValueMode`	Operation Performed
AUGMENT	VALUE	t_final = t_initial + s
AUGMENT	FRACTION	t_final = t_initial + (t_initial * s)
REPLACE	VALUE	t_final = s
REPLACE	FRACTION	t_final = t_initial * s

In the above table:

t = Spatial Data target cell
s = Grid ASCII map source value corresponding to t's location.
s values can be either positive or negative.
t_final values are not checked to see if they have become negative. It is possible to inadvertently create negative values in a spatial data pool where negative values are not allowed or make no sense (e.g. BIOMASS_LEAF_N).
t and s values are assumed to share the same units. Modify-By-Map disturbances cannot perform unit conversions as part of modify a spatial data pool.

Metadata Parameters (Don't Touch!)

Parameter Name	Expected Value	Description	Can leave blank?
`modelClass`	`ModifySpatialDataByMapDisturbanceModel`	Automatically set when JVelma a the Modify-By-Map item parameterization to a simulation configuration	NO

The modelClass parameter is special and should never be changed from its initial value. It is used by the simulator to decide what disturbance code to load and run for this Modify-By-Map item parameterization.

An Example Modify-By-Map Parameterization

Parameter	Value
`initializeActiveLoops`	1
`initializeActiveYears`	1969
`initializeActiveJdays`	1
`occursAtStepStart`	false
`spatialDataName`	`BIOMASS_LEAF_N`
`spatialDataLayer`	1
`setCellOutcome`	`REPLACE`
`setMapValueMode`	`VALUE`
`spatialDataFileFullName`	./Every_Conifer_Cell_80d5.asc
`modelClass`	`ModifySpatialDataByMapDisturbanceModel`

This example parameterization creates a ModifySpatialDataByMapDisturbanceModel instance that loads data from Grid ASCII map file inputDataLocationRootName/inputDataLocationDirName/Every_Conifer_Cell_80d5.asc and in the first simulation loop, on January 1, 1969 replaces each value of the BIOMASS_LEAR_N spatial data pool with the corresponding value from file Every_Conifer_Cell_80d5.asc. (BIOMASS_LEAR_N is a single-layer pool, so spatialDataLayer's value must be 1.)

Using Modify-By-Map Instead of Set-By-Map

The ModifySpatialDataByMapDisturbanceModel became available in VELMA version 2.1.0.10. Prior to this version the SpatialData modification capability VELMA provided was the SetSpatialDataByMapDisturbance ("Set-By-Map"). Set-By-Map disturbances are functionally equivalent to Modify-By-Map disturbances parameterized with setCellOutcome=REPLACE and setMapValueMode=VALUE.

VELMA still supports Set-By-Map disturbances (for legacy simulation configuration .xml) but now that Modify-By-Map disturbances are available, there is no reason to use Set-By-Map disturbances.

Submit a Suggestion