SBAS/UsersGuide
Versions & Requirements
SBAS ArcGIS Pro
- ESRI ArcGIS Pro
- ESRI ArcGis Online (AGOL) access for Enterprise data access and sharing (see Local and Enterprise Data Storage)
SBAS ArcGIS Desktop
- ESRI ArcGIS 10.1 - 10.4
- Python comtypes package (tested with 0.6.2 - included with this tool)
- URL: https://pypi.org/project/comtypes/ -- (Previous link http://starship.python.net/crew/theller/comtypes/ no longer works)
- Author: Thomas Heller, theller@ctypes.org
- License: MIT License
- The package must be installed into the local python instance.
- Install does not require admin rights.
- Can be installed by running comtypes-0.6.2\install_comtypes.bat
- Snippets.py, slightly modified code snippets file for accessing ArcObjects via Python. (Included)
- File: snippets.py -- (Previous link http://www.pierssen.com/arcgis/misc.htm no longer works)
- Author: Mark Cederholm
- License: No specific license.
- (Formerly available on http://www.pierssen.com/ and indicated "Free stuff for GIS Developers and Users!")
SBAS Desktop
- SBAS Desktop is a legacy version of SBAS designed to run as a stand-alone program.
- For information on all past (and present) versions of SBAS, see the SBAS main wiki page.
Using SBAS ArcGIS Pro
Installation & Launching SBAS
The SBAS for ArcGIS Pro is designed as an ArcToolbox written in Python 3, and installation requires unzipping the distribution file to a local drive. The zip file can be downloaded from here: https://www.arcgis.com/home/item.html?id=90576370d48f491fbddc7a15bbfb40d7. The zip file includes the toolbox (SBAS_2020.pyt), layer packages (_.lyrx), a settings file (SBAS_settings.txt), and a template geodatabase (SBAS.gdb). The settings file is used by the SBAS tools to easily find the local SBAS database and must stay in the same directory as the toolbox file. To launch SBAS, create a new project in ArcGIS Pro and use “Add a Folder Connection” to add SBAS_2020.pyt to your project in the catalog pane. Within the toolbox are the individual tools used to create a sediment budget (Figure 1; Table 1).
| Topic | Tool Description |
|---|---|
| 00 – Set Local Database | Designates location for SBAS data to be stored |
| 01a – Create SBAS Alternative | Creates a sediment budget |
| 01b – Load SBAS Alternative | Loads an existing sediment budget |
| 01C – Copy SBAS Alternative | Copies an existing sediment budget |
| 02a – Plot GenCade Points | Plots shoreline points from GenCade data |
| 02b – Convert GenCade Points to Budget Features | Converts GenCade data into budget cells and fluxes |
| 03a – Import GIS Features to SBAS Alternative | Imports GIS features into the sediment budget |
| 03b – Transfer Values to SBAS Cell Attributes | Transfers sediment budget values from a different file into the budget alternative |
| 03c – Create Relationship to SBAS Features | Joins data based on spatial relationship |
| 03d – Show Related SBAS Attributes | Create a layer file to hold a relationship between SBAS features and additional attribute data |
| 04a – Load Complementary Data | Loads complementary data |
| 04b – Load Published Sediment Budgets | Loads a sediment budget that is published on USACE AGOL |
| 05a – Start Editing (Add Features) | Starts editing session to create features |
| 05b – Stop Editing (Add Features) | Stops editing session |
| 06 – Recompute Residual | Recalculates residual volume, transport removal, and transport placement |
| 07 – Delete Alternative | Deletes Sediment Budget |
| 08 – Share Sediment Budget Online | Publishes sediment budget to ArcGIS Online |
Creating a Sediment Budget
Set Local Database
Tool 00 - Set Local Database is used to designate a known file locality for the user’s local SBAS database and provides the flexibility to have one or more local SBAS databases. Behind the scenes, this tool is simply writing a string value into the file “SBAS_settings.txt”. Each time SBAS needs to locate the SBAS database in the data processing, it will put the value listed in this file.
Create SBAS Alternative
Sediment budget data are grouped into alternatives, which are representations of one set of assumed conditions for a sediment budget. Creating a new alternative is the first step in building the geometry container to hold littoral cell and flux features. The user has an option to create a micro (<200-meter cell lengths) or macro (>200-meter cell lengths) budget type (Figure 2). Each alternative has its own set of littoral cells (with delta volume, placement/input volume, and removal/output volume) and fluxes. Alternatives may be created to reflect different assumptions about sediment-transport paths/rates and engineering activities, or they may reflect different time periods. Alternatives hold all values applied to littoral cells and fluxes, and the data are written to the alternative table in the local geodatabase.
Tool 01a - Create SBAS Alternative is used to create a new alternative for a sediment budget. Basic information is collected to assist in building metadata for the alternative. The following pieces of data are required:
- a. Budget Type (Micro or Macro)
- b. Alternative Name
- c. Alternative Description
- d. Geographic Area Name or Description
- e. Data From (Epoch)
- f. Date To (Epoch)
- g. Flux Q Units (cubic year/year or cubic meters/year)
- h. Cell Volume Units (cubic Yards or cubic Meters)
There is a checkbox to load a new alternative immediately, which if selected will add three new layers to the Table of Contents. One layer will be named “Fluxes for Alternative Name,” and the other two will be named “Cells for Alternative Name.” One of the cell layers displays the cell boundaries while the other displays the residual volume change for the cell (Figure 3). As different alternatives are created, each is assigned a unique identifier (ID). This value is stored in the “scenarioIDPK” attribute field. When added to the Table of Contents, the SBAS tool pulls the supplied layer files (Cells.lyrx, AllCells.lyrx, and Flux.lyrx) and applies a definition query to the items that filters only on the assigned unique ID for the active alternative.
Load SBAS Alternative
Tool 01b – Load SBAS Alternative is an optional step to load any alternative and its respective feature layers into the Table of Contents. All available alternatives are listed in the drop-down menu that are stored in your local SBAS database, and multiple alternatives can be loaded at the same time.
Copy, Change, and Delete Alternatives
Tool 01c – Copy SBAS Alternative is used to copy any existing alternative into a new alternative. This tool allows the user to reuse feature geometry for a new alternative. The user also has the ability to change specific alternative details such as “Name,” “Description,” “Start,” and “End Date.”
- 1. In the Catalog pane, browse and expand the “SBAS.gdb”.
- 2. Right-click on the alternative table and select “Add to Current Map.”
- 3. In the Table of Contents pane, right-click on the alternative table and select “Open.”
- 4. In the attribute window, click the row/column value to modify and enter any changes.
- 5. Enter any changes, and when finished click the “Save” button on the Edit ribbon.
Sketching SBAS Feature Geometry
Creating new feature geometry in SBAS follows much of the same process inherent in ArcGIS Pro, however in SBAS, the user must first start an “SBAS Edit Session” so geometry is related to the correct alternative.
- 1. To begin launch tool 05a - Start Editing (Add Features)
- 2. A list of all alternative in the Table of Contents will be in the drop-down list. Choose the desired alternative and click "Run".
- 3. Zoom to your area of interest, click on ArcGIS Pro's Edit ribbon, and click on "Create".
- 4. To sketch littoral cells, click on the symbol in front of the "Cells for Alternative Name" layer in the "Create Features" panel. This will expand to show the sketch options. Click on the first icon, which will turn on the sketch tool. Click in the map to drop vertices for your littoral cell polygon. Double-click to complete sketch. For sketching flux cells, select “Fluxes for Alternative Name” layer in the “Create Features” panel and create vertices for a flux line in the direction of flux with the sketch tool. Fluxes may represent a sink for one cell and a source for another, so all fluxes are symbolized the same way and given a positive magnitude and direction.
- 5. When done sketching all of the new littoral cell features, launch tool 05b - Stop Editing (Add Features) to commit changes.
- 6. To modify location of vertices, click on the "Modify" button from ArcGIS Pro's Edit ribbon, then click on "Reshape", then "Edit Vertices." Click on the vertices to move to new location or right click to remove. Save changes when complete.
Importing SBAS Feature Geometry from GenCade Data
GenCade is a one-dimensional numerical model that calculates the shoreline change based on longshore sediment transport rates. After creating and calibrating a GenCade grid, the user can create sediment budget cells and fluxes and run the model. In the GenCade results file (_.prt) under “SBAS OUTPUT,” the results for volume change and rate for the fluxes and cells will be used with SBAS. A GenCade special report (Munger and Frey 2015) provides more information for new users on how to use GenCade, and a technical note (Frey 2015) is available for more detail on incorporating GenCade and SBAS data.
When importing GenCade data, geometry for both “Cells” and “Fluxes” is created. Tools 02a - Plot GenCade Points and 02b - Convert GenCade Points to Budget Features are used for this data transformation. For the data transformation to a sediment budget, the associated GenCade files, _.gen (GenCade control file), _.slo (shoreline position file), _.prt (sediment fluxes file), and _.map(GenCade coverage file) are required. These steps below need to be run only once as the tool will import the littoral cells and fluxes at the same time.
- 1. First run tool 02a - Plot GenCade Points. This will plot the shoreline point locations documented in the _.slo file. The output shapefile is needed for the input into tool 02b - Convert GenCade Points to Budget Features. The starting coordinate, azimuth, and distance between points is collected from the _.slo file. If "Use Only First Date in Point Plot" is selected in the tool, only the first row of the _.slo is used for the plot.
- 2. Next open tool 02b - Convert GenCade Points to Budget Features. The three GenCade files and the newly created GenCade shoreline points will need to be supplied. Set the temporary placeholder feature classes for the “Cells” and “Fluxes”, set the design distant variables, and choose the alternative that will be the home for these features.
Importing SBAS Feature Geometry from Existing Geographic Information System (GIS) Layers
If geographic information system (GIS) layers are already created that represent littoral cells or fluxes, but were created outside of the SBAS toolbox, these features can be imported into SBAS. The steps for importing SBAS Feature Geometry from existing layers are below.
- 1. Using tool 03a - Import GIS Features to SBAS Alternative, browse to an existing feature class or shapefile, then provide field mapping to connect the original field names to the SBAS values.
- 2. If importing littoral cells, the required fields for mapping include the following: Name, Description, Placement Volume, Removal Volume, and Volume Change. If importing flux cells, the required fields for mapping include: “Name,” “Description,” and “Q Value.”
- 3. Check the “Duplicate Geometries OK” checkbox to use the same cells/fluxes for multiple alternatives.
Manually Add SBAS Feature Values
Sediment budget values linked to cell volumes and fluxes can easily be added to geometry as feature attributes. Tables A2 and A3 contain the values available to edit for the littoral cells and fluxes. Within the littoral cell there are three dynamic fields: “residualVolume,” “transportRemoval,” and “transportPlacement.” The values within these fields do not need to be manually updated, as they can be automatically recalculated using tool 06 – Recompute Residual. To manually add feature values:
- 1. From the Edit ribbon, click the “Attributes” button to open the Attribute pane.
- 2. Selected a budget feature (cell or flux) on the map with the Selection Tool. The attribute pane will display the values for the selected feature.
- 3. Click on the value next to the attribute to edit. Enter in the new value.
- 4. When finished, click the “Save” button on the Edit ribbon.
Transfer Values into SBAS Cell Attributes
If sediment budget geometries and values exist outside of your local SBAS database in a feature class with identical geometry, the attributes can be transferred into the selected Alternative using tool 03b – Transfer Values to SBAS Cell Attributes. To use this tool, the geometries in both datasets must match. All values from the input feature class will be used to update the littoral cell layer, and a record of all transferred values will be listed in the Results Window. Tool 06 – Recompute Residual does not need to be run as the residual is automatically recalculated.
Create Relationship to SBAS Features
Additional attribute data may be stored outside of the SBAS local database in feature classes. Contents from supplemental databases can be related to SBAS features using tool 03c – Create Relationship to SBAS Features. This tool uses spatial and nonspatial relationships to determine how to connect the data attributes to the sediment budget. If there are feature geometry and values created outside of the SBAS toolbox, this tool will create a spatial relationship to join the datasets together. This tool should be used when a table join cannot easily be performed, such as when there is no consistent field between the tables that can be referenced for the join. This tool does not support Grouped Layers.
Load Complementary Data & Published Sediment Budgets
SBAS is configured to work with sediment budgets and complementary data that have been published online (Dunkin et al. 2020). Use tool 04a – Load Complementary Data to connect to online content (map services or feature services) that have been appropriately tagged in ArcGIS Online (AGOL) item descriptions or published through the SBAS 2020 toolbox (see tool 08 – Share Sediment Budget Online).
Users with an AGOL account can request access to the SBAS ArcGIS Hub (https://sbas-usace.hub.arcgis.com) to publish sediment budgets online. Using tool 08 – Share Sediment Budget Online, budgets will be published as a feature web service to the SBAS Hub. Extraneous datasets need to be removed from the Table of Contents, as the tool includes all contents in the web service. Content with multiple display options for a single dataset need to be reduced to one visualization per dataset. When publishing a budget, consider the following:
- •Any existing web service with the same name will be overwritten.
- •If more than one alternative is loaded in the Table of Contents, all alternatives will be combined into a single feature service but as separate layers.
- •Do not publish any datasets containing personally identifiable information or other sensitive information.
- •Do not publish datasets that are already available online.
Definitions and Descriptions
| Term | Definition |
|---|---|
| Alternative | Representation of a sediment budget. Contains fluxes, cells, and associated values. |
| Attribute | Specific information related to a feature layer |
| Attribute Table | Table that stores the attributes related to a feature layer |
| Confidence | The certainty level that the values assigned to littoral cells and fluxes are accurate |
| Feature | A point, line, or polygon in a coverage, shapefile, or geodatabase feature class |
| Feature Layer | A collection of similar features and their associated properties |
| Flux | The movement of sediment into or out of a littoral cell. Flux features are a representation of the input and output of sediment into a littoral cell. Each cell requires both eastward and westward transport rates |
| Littoral Cell | A delineated area that acts as a source or sink of sediment. Littoral Cell features are collection of information describing similar physical, biological, and cultural characteristics within a particular area along a river, lake, sea, or ocean |
| Macro Budget | A sediment budget for a region; it may consist of multiple micro budgets |
| Micro Budget | A sediment budget for a specific local area |
| Sediment Budget | A measure of sediment (usually sand) “sources” (inputs), “sinks” (outputs), and net change within a specified “control volume” (a cell or series of connecting cells) over a given period of time. |
| Shapefile/Feature Class | A vector data storage format for storing the shape, location, and attributes of geographic features. A shapefile is stored in a set of related files and contains one feature class. |
| Sink | The destination of sediment that is moved from its original location. |
| Source | The point of origin of sediment that is moved to a different location |
| 06 – Recompute Residual | Recalculates residual volume, transport removal, and transport placement |
| Field Name | Field Type | Character Limit (if applicable) | Field Description |
|---|---|---|---|
| sedimentTransportDirectionIDPK | Text | 50 | Primary Key. This value is auto-generated by SBAS and provides a unique identifier for each flux |
| sdsFeatureName | Text | 50 | Name or label of the flux |
| sdsFeatureDescription | Text | 255 | Description of the flux |
| scenarioIDFK | Text | 50 | Foreign Key. Value to the relative alternative (or scenario) |
| qValue | Double | - | Volume of sediment moving in or out of cell |
| transportUom | Text | 50 | Units of measure for sediment transport rates. Cubic yards/year or cubic meters/year |
| alternativeLabel | Text | 50 | Name of alternative |
Points of Contact
Main POC: Sean McGill
Email: Sean.P.McGill@usace.army.mil
Secondary POC: Katie Brutsche
Email: Katherine.E.Brutsche@usace.army.mil
Technical Issues: Rose Dopsovic
Email: Rose.Dopsovic@usace.army.mil