Spreading

A Spreading Rule simulates the spreading of a community and size class across a given study area. With elements in a study area populated by a community, the community populates elements that share edges with the source element when spreading occurs. Spreading to adjacent elements depends on factors that may hinder or encourage spreading.

Spreading rules tab

The Spreading Rules tab allows you to configure the spreading of a community of a specific size class. In this tab, a spreading rule is created, edited, or deleted. The factors that affect the spreading of the community and size class are configured in this tab (Figure).

Only one spreading rule may be created for a community and size class combination. 

Figure.  The Spreading Rules interface.

Rule Name: displays name of selected Spreading rule as part of dropdown list of all Spreading rules in the study.

Add, Rename, Copy, and Delete Rule: described above in the common features section.

Community: dropdown list of communities in the study.

Size Class: this dropdown field lists the size class members of the selected community.

Generate detailed output: this checkbox controls whether the spreading vectors are generated in the Simulation HDF file after successfully computing the simulation with a spreading rule.

Maintain max vector during size class graduation: this checkbox controls whether the max value of spreading vector is maintained during size class graduation.

Pick Spreading Trigger: these radio buttons control the spreading trigger.

Method to record extent of spreading: these radio buttons control the method for recording the extent of spreading.

Base Movement: this table defines the base movement rate used by the community and size class when spreading across the study area.

Factor: this field displays the selected data, model variable, or time series used as a factor that affects movement.

Add Factor: this button accesses the Variable Picker dialog where data, model variable, or time series can be selected for the factor.

Edit Factor: this button accesses the Variable Picker dialog to edit the selected data, model variable, or time series for the selected factor.

Copy Factor: this button accesses the Variable Picker then creates a copy of the selected factor.

Delete Factor: this button deletes the selected factor. After being removed, the factor is no longer displayed in the Factor field’s dropdown.

Weight: this field applies a multiplier to the attraction strength. This is set to 1 by default.

Strength Plot: this plot displays the configured look-up table for the strength.

Strength Table: this table defines the strength of attraction based on the selected factor that affects movement.

Seasonal Factor Plot: this plot displays the configured look-up table for the seasonal factor.

Seasonal Factor Table: this table defines the seasonal factor for the spreading rule.

Apply: clicking this button saves the spreading rule.

Spreading Trigger

The Spreading Trigger describes when spreading is completed by a community and size class from the source elements to elements that share edges. Currently, Centroid to centroid is the only enabled option. The Percent element being colonized option will be implemented in the future.

With the Centroid to centroid option, the community and size class populates elements tangent to the source elements once the base movement rate covers the distance between centroid to centroid.

Method to Record Extent of Spreading

For a community to spread to suitable elements, the magnitude of spreading must be considered. The magnitude determines whether spreading is suitable and whether the community populates the destination element. For information regarding the magnitude of spreading, see Spreading.

The method to record extent of spreading refers to tracking the magnitude per time step. There are two methods available – additive and resetting as a function of date.

When the Additive (indefinitely) method is selected, the magnitude increments per time step.

When the Resets as a function of date is selected, the magnitude increments per time step similar to the Additive method but resets at the specified date.

Base Movement Rate

The Base Movement table defines the rate of movement for a community and size class to spread across the study area.

The base movement rate may vary across a year. The Base Movement table by default has a single row for a season that starts on January 1. Each season is defined under the Date column following the format of “ddMMM”. The base movement is then defined for each season under the Rate (map units per day) column. Between seasons, the base movement rate can use Linear or Step interpolation.

When there is only one season defined, the base movement rate is treated as a constant value for the entire year.

Factors That Affect Movement

The spreading of a community may be affected by factors. The Spreading Rule tab has configurations for determining that factor. The suitability of spreading can be defined by a look-up table that defines the suitability of spreading based on a selected factor.

The Factor field displays the selected data, model variable, or time series using the Variable Picker. Multiple factors may be configured for a spreading rule. For each factor, the suitability based on strength and season is configured.

The Strength table defines a look-up table with corresponding strength values for variable values. The strength value must be from -1 to 1. A value of 1 is full strength for spreading. A value of -1 makes it unsuitable for spreading to occur. The plot renders the curve based on the look-up table.

The Seasonal Factor table defines when the selected factor is in effect. Without the seasonal factor table configured, the factor is in effect. Each season is a row in the table. The beginning of a season is defined by the day and month following the format of “ddMMM” under the Date column. For each season, a value from 0 to 1 is entered under the Factor column.

The Weight is a multiplier applied to the factor’s strength and seasonal factor.

Configuring a Spreading Rule

When creating a spreading rule, you must:

• Assign a unique rule name,
• Select the community and size class to configure spreading rule for,
• Configure the spreading trigger,
• Configure the method to record extent of spreading,
• Configure the base movement,
• Select the factor(s), and
• Configure how the factor(s) affects movement.

Creating a new Succession Rule

The first step in creating a new spreading rule is to assign a rule name. When attempting to create a spreading rule that duplicates an existing rule’s name, an error is produced.

To create a new spreading rule:

• Click the Add Rule This loads the New Rule dialog (Figure).
• Enter a unique rule name for the new spreading rule in the New Rule
• Click OK in the New Rule
• After the New Rule dialog closes, the new rule name is displayed in the Rule Name

Figure.  Interface for creating a new spreading rule.

Selecting Community and Size Class

When creating a spreading rule, the community and size class is selected from the Community and Size Class dropdown fields. The content in the Size Class dropdown depends on the selected community.

When attempting to create a spreading rule using the same community and size class as an existing spreading rule then clicking the Apply button, a message informs the user that only one spreading rule per community and size class is allowed.

To select the Community and Size Class:

• Expand the Community drop down. The drop down lists all the available communities in the study.
• Select the community to create the spreading rule for. This updates the content in the Size Class
• Expand the Size Class The dropdown lists all the available size classes for the selected community.
• Select the size class to create the spreading rule for.

Selecting the Spreading Trigger

The spreading trigger is set to Centroid to centroid by default. As this is the only option available, the spreading trigger is already configured when a spreading rule is created.

Configuring Method to Record Extent of Spreading

To configure the method to record extent of spreading using additive:

• Select the Additive (indefinitely) radio button.

To configure the method to record extent of spreading where spreading resets as a function of date:

• Select the Resets as a function of date radio button.
• Configure the date.

Configuring Base Movement Rate

To configure the base movement rate:

• Add rows to the Base Movement table for additional seasons.
• Configure the beginning of each season by entering the day and month under the Date
• Configure the base movement rate for each season by entering the value under the Rate (map units per day)
• Select whether to use Linear or Step

Configuring Factors That Affect Movement

The factors that affect movement must be configured by first assigning a data, model variable, or time series.

To add a new factor:

• Click the Add Factor This loads the Variable Picker dialog.
• Select the Category of the variable to use as a factor.
• Select the Member of the variable to use as a factor.
• If necessary, configure Temporal Options for the selected variable.
• Click the OK button in the Variable Picker.
• After the Variable Picker closes, the selected variable is displayed in the Factor
• Repeat the process for each factor needed in the spreading rule.

Configuring How the Factor Affects Movement

After a factor is selected, how the factor affects movement must be configured. The strength needs to be configured. The seasonal factor is optional.

To configure the strength for the spreading rule:

• Add the necessary rows to the Strength
• Configure the Value in the table for each row.
• Configure the Strength for each row in the table.

To configure the season for the selected factor:

• Add the necessary rows to the Seasonal Factor
• Configure the Date in the table for each row.
• Configure the Factor for each row in the table.
• Click the Apply button (Figure).

Figure.  Click the Apply button to save the Spreading rule.

Simulation

For a community and size class to spread to elements that share edges with the source elements, there are a few things to consider:

• The elements to spread to
• The direction to spread to
• The magnitude of spreading

The direction and magnitude of spreading together make up the spreading vectors.

The elements that are spread to by a community share edges with the elements populated by that community before spreading occurs. These elements to spread to must not be populated by the community and size class.

The direction of spreading is the direction of movement from the centroid of the populated elements to the centroid of the elements to spread to as determined previously.

The magnitude of spreading then determines when a community successfully populates the destination elements. This value cannot be less than 0. When the overall magnitude is greater than or equal to 1, the spread occurs. Elements that are not yet populated by the community selected for the spreading rule begin with a magnitude of 0. Once the spreading occurs, the magnitude resets to 0.

The overall magnitude that is computed for each time step is a total of the magnitude from the previous time step and the magnitude for the current time step.

Where:

The magnitude for the current time step considers the base movement rate, the distance between centroid to centroid, and the factors that affect movement during a spreading rule. The base rate is divided by the distance between a centroid to centroid. Then the quotient is multiplied by the sum of factors that affect movement.

Where:

Each factor that affects movement is the product of its weight, strength, and seasonality.

The magnitudes of the spreading vector between centroids of edge-connected pairings of source and destination elements are tracked as fractions of the distance between centroids. The following determines when a factor is picked from the source element or the destination element.

When working with spreading rules, the geometry HDF file of the study has a SpreadingNeighbors table. The Fraction column of this table determines when spreading switches from the source element to the destination element. See SpreadingNeighbors for more information on this geometry HDF table.  

Spreading occurs when the magnitude of the spreading vector reaches 1. If the source and destination elements are equally sized, the element fraction for each element would be half that magnitude resulting in 0.5. When the magnitude is less than or equal to 0.5, the source element is considered. When the magnitude becomes greater than 0.5, the destination element is considered in the next time step.

Consider a study where a community spreads from the center of a study area. The base movement rate is 50 map units/day. The distance between centroid to centroid is 400 map units.

The spreading rule is configured with 2 factors.

Factor 1:

• Variable: Polygon with values for each element that is either 100.0 or 1333.0.
• Weight: 1.0
• Strength: 1.0 when the variable in the element is 100, -1.0 when the variable in the element is 1333.0, and 0 for all other values.
• Seasonality: Not configured. Factor is in effect for entire season.

The value for Factor 1 is:

• If the variable for an element is 100.0:

                                   factor₁ = 1.0 * 1.0 * 1.0 = 1.0

• If the variable for an element is 1333.0:

                                   factor₁ = 1.0 * -1.0 * 1.0 = -1.0

Factor 2:

• Variable: constant data of 100.0.
• Weight: 0.75
• Strength: 0.5 when the variable is 100.0.
• Seasonality: Not configured. Factor is in effect for entire season.

The value for Factor 2 is:

• If the variable for an element is 100.0:

                                   factor₂ = 0.75 * 0.5 * 1.0 = 0.375

The variable used for Factor 1 has the value of 100.0 for both the source and destination elements when spreading occurs for these elements. This results in the following spreading vectors for the time steps it requires to complete spreading from the source to destination elements (Table).

Table.  Spreading vectors based on two factors.

The community successfully spreads to the destination element by the 6^th time step when the overall magnitude reaches 1.031250 and is greater than 1.

Spreading when unsuitable

Spreading into an element is unsuitable when the factor strength is set to -1.0 for a variable. When spreading is unsuitable, the magnitude of the spreading vector still attempts to increment to reach 1.0 but never does until the destination element becomes suitable.

Using the example in Spreading, the magnitude for Factor 1 depends on whether the variable value in an element is 100.0 or 1333.0. When the element has the variable value of 1333.0, the strength is -1.0 making spreading unsuitable for the element. With the source element having the variable value of 100 and therefore the strength of 1.0 and the destination element having the variable value of 1333.0 and therefore the strength of -1.0, this results in the values in the table.

Because the source and destination elements in this example have the same size, and the edge between the elements is equidistant, the element fraction is 0.5.

For time steps 1 and 2, the magnitude still considers the factors in the source element. By time step 3, the magnitude becomes greater than the element fraction of 0.5. For the next time step, the factor in the destination element is used, which is -1.0.

In time step 4, the magnitude becomes less than the element fraction of 0.5. In the next time step, the source element’s factor is used. In time step 5, the magnitude again becomes greater than the element fraction and the destination element’s factor is used in the next step.

The -1.0 strength causes the magnitude to decrease the overall magnitude. This deters the spreading vector from reaching a value of 1 or greater for the community to complete spreading.

Spreading when size class graduation occurs

After a size class graduation occurs, the spreading vector is affected by whether the Maintain max vector during size class graduation checkbox is checked or not in the Spreading Rules tab for a spreading rule. The spreading vector when size class graduation occurs also depends on whether the graduated size class already exists in the source element.

When size class graduation occurs and the graduated size class does not yet exist in the source element

This is when a source element is populated by a single size class of the community. When the community graduates in size, only that new size class exists in the source element.

• When the Maintain max vector during size class graduation checkbox is not checked, the spreading vectors reset to 0 when the size class graduation occurs.
• When the Maintain max vector during size class graduation checkbox is checked, the spreading vector is maintained when the size class graduation occurs.

When size class graduation occurs and the graduated size class exists in the source element

This is when a source element is populated by multiple size classes of the community. When at least one size class graduates into a size class that already exists in the source element, the already existing community at the graduated size class in the element also has a spreading vector value.

Because spreading applies to communities that are immobile, this case occurs when a recruitment or succession occurs in source elements.

• When the Maintain max vector during size class graduation checkbox is not checked, the spreading vector of the source element is maintained.
• When the Maintain max vector during size class graduation checkbox is checked, the spreading vector is the maximum value from all the maximum spreading vectors of the graduated size class.

Spreading when mortality occurs

When mortality occurs in an element where spreading is occurring, the spreading vectors reset to 0.

Spreading when there are obstructions

At times, obstructions are present in the study area. In the context of a community spreading in a study area, an obstruction is an element that lies in the path of a straight line from centroid to centroid of two elements (Figure).

Figure.  Spreading occurs between centroids of neighboring elements.

When spreading occurs and obstructions are present in the study area, the shortest path between the two elements is computed. This results in the spreading vectors seemingly moving around the obstruction.

Simulation Output

After a simulation is computed with spreading results, the Plots may reflect changes in count and density. Relevant output is generated in the Geometry HDF and the Simulation HDF files. Spreading can also be animated in the Simulation Map.

After computing a simulation with a spreading rule, the Count and Density plots may reflect the effect of spreading for a community. These plots are accessed from the context menu of an alternative in the Simulation tab.

When spreading occurs, the community populates additional elements in the study area. This affects the total count of the community and may be reflected in the Count plot.

As the community’s count increases with spreading across the study area, the density also increases. The Density plot reflects this increase.

Configuring Spatial Output Controls

The Spatial Output Controls, which are accessed from the Project Properties dialog, control whether additional tables are generated in the simulation HDF file after computing a simulation with configured spreading rules.

The Spatial Output Controls has a checkbox for Spreading under the Rules section. By default, this checkbox is unchecked.

Geometry HDF

After successfully computing a simulation with a spreading rule configured, the SpreadingElements and SpreadingNeighbors tables are generated in the Geometry HDF file. These tables help relate the results in the spreading-related tables in the Simulation HDF file to the elements in the study area.  These tables are organized under the folder of the layout used in the computed simulation.

The SpreadingElements table details the number of possible elements to spread to for a given element in the study area. This table also identifies which row in the SpreadingNeighbors table corresponds to the first combination of elements that can be spread from given the element and which element can be spread to.

These pieces of information are organized in the following columns:

• Column 0: this column lists the IDs of each element in the study area.
• Column 1: this column details the row number in the SpreadingNeighbors table related to the element ID of a given row.
• Column 2: this column identifies the number of elements that share edges with a given element.

The SpreadingNeighbors table details source elements and their corresponding destination elements. This table also details the centroid to centroid distance between the source and destination element.

The SpreadingNeighbors table has the following columns:

• From: This column lists the source element ID. Spreading begins from this element.
• To: This column lists the destination element ID. The community spreads to this element.
• Distance: This column details the length of path from centroid to centroid between the From and To This can be greater than the distance between centroids, if another element is obstructing the direct path between the centroids.
• Fraction: This is the fraction of the path from the source element to the destination element that lies within the source element. This determines when spreading switches from the source element to the destination element.
• Line: This column details the path in form of a polyline between the source element and the destination element along which the spreading occurs.

The value in column 1 of the SpreadingElements table refers to the first row in the SpreadingNeighbors table that details the destination elements for the source elements. The number of rows is equivalent to the number of elements that share edges with the source elements. This is the value in column 2 of the SpreadingElements table.

Configuring the Animation Properties

In the Animation Properties, a simulation with a computed spreading rule can be displayed using the Density or Size options in the Model Variable dropdown.

If the SpreadingVectors table is generated in the Simulation HDF file, the option to display the Spreading Vector is available in the Model Variable dropdown.

Animating the Spreading Rule

The Simulation Map displays the spreading of a community across a study area by animating the Density or Size. The spreading vectors may also be animated on the Simulation Map.

To animate the spreading of a community and size class in the Simulation Map using the Density variable, in the Animation Properties:

• Select the Community-Size Class to animate on the Simulation Map.
• Select the Model Variable radio button.
• Select Density in the corresponding dropdown.
• Configure the Tic Interval and Contour Limits as needed.
• Click the Apply

To animate the spreading of a community and size class in the Simulation Map using the Size variable, in the Animation Properties:

• Select the Community-Size Class to animate on the Simulation Map.
• Select the Model Variable radio button.
• Select Size in the corresponding dropdown.
• Configure the Tic Interval and Contour Limits as needed.
• Click the Apply

To animate the spreading vectors in the Simulation Map, in the Animation Properties:

• Select the Community-Size Class to animate on the Simulation Map.
• Select the Model Variable radio button.
• Select the Spreading Vector in the corresponding dropdown.
• Click the Apply