Class CompartmentBuilder

java.lang.Object
ca.spatial.compartment.CompartmentBuilder

public final class CompartmentBuilder extends Object
This class will run an allocation process to combine hexgaon cells in to larger compartments. The process to aggregate compartments is guided by terms in an objective function.

Typically the process starts by reading in a polygon dataset and sampling hexagons on the fly (see the buildHexagons(ca.spatial.table.GeoRelationalStore, java.lang.String, java.lang.String, ca.spatial.table.GeoRelationalStore, java.lang.String, int, java.lang.String, int) static method. The size of the hexagons are specified by the sideLength parameter, and hexagon attributes are sampled from the input polygon under the centroid of the hexagon.

The hexagon building process accepts a parameter specifying hexagons to exclude from compartment building. In addition a parameter specifies the codes that define zones on the landscape that compartments cannot span across. The expression is evaluated for each hexagon, and only the cells that have identical codes are eligible to join together to create compartments. The zone expression is of arbitrary complexity and may include a number of database columns.

The compartment building process may also respect linear features representing hard compartment boundaries.

After instantiating the CompartmentBuilder, add targets using the addCompartmentCountTarget(java.lang.String), addParcelSumTarget(java.lang.String, java.lang.String, java.lang.String), addParcelStdevTarget(java.lang.String, java.lang.String, java.lang.String) and addShapeTarget(java.lang.String) methods. These methods return Tally objects which can be used to set weights and target levels.

The allocation process is initiated with the increaseIterationCount(long) method followed by the resume() method. The process will run for the specified number of iterations, or until the suspend() method is called. After the allocation completes the requested number or iterations the increaseIterationCount(long) and resume() methods may be called again to continue the process.

As the process runs progress may be tracked by watching and adjusting the target table. Open the target table with the following command:

 cb.showControlPanel();
 

The GeoRelationalStore representing the hexagons and the current solution can be displayed using the following command:

 cb.addParcelsToMap(layers);
 

Adjust parameters and continue to run the model as required. After the allocation is satisfactory then use the "Convert to shapefile" or saveDissolvedCompartments(java.lang.String) method to save the results.

The CompartmentBuilderWizard provides easy steps to run this tool.

See Also:
CompartmentBuilderWizard
  • Constructor Details

  • Method Details

    • buildHexagons

      public static CompartmentBuilder buildHexagons(GeoRelationalStore as, String areaColumn, String reselectColumn, GeoRelationalStore barriers, String reselBarriers, int sideLength, String zoneColumn, int period)
      Initialize the compartment Builder by building hexagons from a polygon dataset.

      Typical usage:

       cb = CompartmentBuilder.buildHexagons(as,
         "area()/10000",
         "true",
         barriers,
         "true",
         100,
         "LMU_AB");
       
      Parameters:
      as - the input polygon dataset
      areaColumn - the expression to use to calculate hexgon area
      reselectColumn - an expression to select hexagons to exclude from the compartment building process
      barriers - features that represent lines the compartments cannot cross. If null then linear barriers will not be used.
      reselBarriers - the expression used to select lines that for barriers
      sideLength - the length of the side of the hexagon
      zoneColumn - an expression that specifies zones that compartments cannot cross
      period - the planning period in which to evaluate the expressions
    • getTargetTable

      public AttributeStore getTargetTable()
    • getCompartmentTableSnapshot

      public AttributeStore getCompartmentTableSnapshot()
    • getJoinedTable

      public GeoRelationalStore getJoinedTable()
    • getParcelTable

      public AttributeStore getParcelTable()
    • saveDissolvedCompartments

      public void saveDissolvedCompartments(String path)
      Dissolve the compartments and save them to the specified location
    • showControlPanel

      public void showControlPanel()
      Show the control panel
    • addParcelsToMap

      public void addParcelsToMap(LayerList layers)
    • addCompartmentCountTarget

      public Tally addCompartmentCountTarget(String zonePattern)
      Add a target for the number of compartments in the zone
      Parameters:
      zonePattern - a regular expression that defines the parcels used to make compartments. Compartments cannot include parcels not matched by the zone expression.
      Returns:
      a Tally object on which targets can be set.
    • addParcelSumTarget

      public Tally addParcelSumTarget(String zonePattern, String expression, String reselect)
      Add a target for the sum of parcel values in the compartment, using a reselection expression to limit the parcels used in the calculation. Parcels that are excluded from the calculation may still be joined in to the compartment.
      Parameters:
      zonePattern - a regular expression that defines the parcels used to make compartments. Compartments cannot include parcels not matched by the zone expression.
      expression - a numeric expression that will be evaluated to determine the value to sum in each parcel
      reselect - a boolean expression that will be evaluated to determine if the parcel value will be included in the tally
      Returns:
      a Tally object on which targets can be set.
    • addParcelStdevTarget

      public Tally addParcelStdevTarget(String zonePattern, String expression, String reselect)
      Add a target for the standard deviation of parcel values in the compartment, using a reselection expression to limit the parcels used in the calculation. Parcels that are excluded from the calculation may still be joined in to the compartment.
      Parameters:
      zonePattern - a regular expression that defines the parcels used to make compartments. Compartments cannot include parcels not matched by the zone expression.
      expression - a numeric expression that will be evaluated to determine the value from each parcel to calculate standard deviation
      reselect - a boolean expression that will be evaluated to determine if the parcel value will be included in the tally
      Returns:
      a Tally object on which targets can be set.
    • addShapeTarget

      public Tally addShapeTarget(String zonePattern)
      Add a target for the shape of the compartment. Shape is determined by the edge to area ratio, as compared to the edge to area ratio of a circle. A circular copartment would have a shape value of 1. A dendritic polygon would have a higher value.
      Parameters:
      zonePattern - a regular expression that defines the parcels used to make compartments. Compartments cannot include parcels not matched by the zone expression.
      Returns:
      a Tally object on which targets can be set.
    • loadTargets

      public void loadTargets(String targets)
    • saveTargets

      public void saveTargets(String targets)
    • resetParcelValues

      public CompartmentBuilder resetParcelValues()
      Set the parcel values as required by each of the tallys. Do this after setting up the tallys and then the data is loaded in memory for quick access. This will only do the minimum of work required, so it is safe to always call before starting allocate
    • resetAllocation

      public CompartmentBuilder resetAllocation()
      Reset the allocation to only one parcel per compartment
    • assess

      public double assess()
      Calculate the cost of the current allocation
    • increaseIterationCount

      public Thread increaseIterationCount(long iterations)
      Add additional iterations to the termination limit, start the thread and put it into a suspended state. A call to resume() is required to start the alloction.
    • stop

      public boolean stop()
      Gracefully stop the allocation thread in an orderly fashion.
    • resume

      public void resume()
      Clear the suspend flag and notify all waiters that the condition has changed.
    • suspend

      public void suspend()
      Suspend execution, and then wait until the allocation thread notices that the suspension has occured.