Document and review patchmax psuedo-code

[codyevers]

Here’s the pseudo code for the procedure for everyone’s reference

Create spatial adjcency network

• Create adjacency network object based on feature topology
• Calculate pairwise-distances for each network dyad based on stand centroids
• Flag each node in network as include or exclude based on stand threshold threshold
• Modify distances for each dyad based on
  • Average objective (distance penalty is 10x for dyad with lowest objective when spw = 1)
  • Exclusion (distance penalty is 10x for dyads with excluded member when epw = 1)

Search function

• While patch count <= total project count
  • Build patch for each node_i
    • Calcualte objective score
    • Assign score to node_i
  • Identify node_i with highest patch score (NAs are ignored)
    • (re)Build patch (same as above) at node_i
    • Record patch and stand statistics, assign patch_id to all nodes within patch
    • Remove nodes with patch_id from network return to START

Build function: build_func( node_i )

• Calculate distance matrix for node_i to all other nodes using Djistra’s algorithm
• Sort all nodes in descending order where dist == 0 is node_i
• Mark nodes outside of treatment treshold as excluded
• If excluded...
  • Set area to 0
  • Set objective to 0
  • Set constraint to 0
• Calculate cumulative sum for area
• Select nodes from node_i distance matrix until patch_area
• If secondary constraint provided...
  • Calculate cumulative sum for constraint
  • Set threshold_met to FALSE if constraint limits exceeded
  • Delete nodes from tail of distance matrix until secondary constraint is met
• Flag validity
  • Invalid if length == 0
  • Invalid if patch_area < min_patch_area
  • Invalid if excluded area fraction > threshold_exclusion_limit
• Sum objective for remaining nodes in matrix
• Return patch objective score if valid or NA if invalid

[codyevers]

On January 2nd...

I’ve added the area adjust to the objective score. The summary should still report the objective sum in its original units. There is a message when you build the project that reports the ‘objective/area’.

Sounds like we’re still not on the exact same page for whether this should be hard-coded or optional. Pedro, you suggested that the area always be taken into account, which I came around to agreeing with. Michelle, you are right that if you provide an area weighted value as the objective, patchmax will divide that value once again by area, leading to different results. Not sure how to reconcile this to make sure people use this correctly...

[codyevers]

From Alan on Jan 6th (for the archive):

I agree. Both spm and area adjustments should be left to a data pre-processing option that the user can do in a separate script that we provide or done with the field calculator in arc. These two adjustments are not always needed depending on the data and they should not be imbedded in the code. Its almost better if users don’t do these adjustments to understand the outputs in terms of the raw data.

For background the origins of the area adjustments and spm calculations are from the first BM study before any of you were working with forsys nor pedro. We found that when the Wallowa Whitman mapped polygons they were generally larger in the north part of the forest, and since larger polygons when treated in general produced more volume forsys chose those stands. So I used volume per acre as the objective and then reported attainment as the total volume. Reporting attainment on a per area basis is meaningless, so the objective and attainment needed to be 2 different metrics which at first seemed weird.

As for SPM, when we started using weighted objective functions we found certain combinations of variables could not be blended because one was scaled from 0-1 and the other was scaled from 0-100,000. All of the solutions were weighted to the variable with the larger maximum values. So I calculated the standardized proportion of the mean to equalize the scale of the variables.

The important point is that these adjustments are not always required. For instance raster data have equal area per cell so area adjustment is not needed. Single objective runs do not need SPM, nor do multiobjective runs when the scaling of the variables is more or less the same.
This is the case with the he accell data google is using where the data are raster and the objectives are standardized pillars so they might not need either of these adjustments and having them in the code just confuses their programmers.

Hopefully this can all get resolved so we can get the google people a clean version of forsys and then we can explain how to pre-process Data when needed.

[codyevers]

Based on the message above and after talking with @michelledayusfs, I've removed area weight from patchmax.