Domains are predefined lists of acceptable values for an attribute in a layer or feature service. Using domains can be helpful for enforcing data integrity and consistency by restricting the values that can be entered into a specific field. A domain consists of labels and corresponding codes. For example, in a hiking trails feature service, a difficulty rating field could use a domain with the following labels (and codes): Easy (1), Moderate (2), and Challenging (3). Learn more about defining domain lists in ArcGIS Online.
When querying a service, domain codes are returned by default, as these are the values that are stored in the service. But there may be times when the label is preferred, like when the data will be used for visualization or user-facing applications. By using encode_field_values() you can replace the codes with labels or add the labels as metadata, giving you flexible options for working with domain-based attributes.
The following example uses a Living Atlas feature service containing field office boundaries for Bureau of Land Management administrative units.
First, it’s helpful to take a look at the metadata for the feature service to understand which fields use domains:
library(arcgis) # Feature service URL field_offices_url <- "https://services2.arcgis.com/FiaPA4ga0iQKduv3/arcgis/rest/services/blm_natl_admu_field_poly_webpub_A_view/FeatureServer/0" # Create a connection to the feature service lyr <- arc_open(field_offices_url) # Extract the domain info from the service metadata domain_info <- lyr$fields$domain # Preview domain values and codes for a field head(domain_info[[8]]$codedValues)
#> name code #> 1 CALIFORNIA, BUREAU OF LAND MANAGEMENT CA000000 #> 2 STILLWATER FIELD OFFICE NVC01000 #> 3 BISHOP FIELD OFFICE CAC07000 #> 4 SALT LAKE FIELD OFFICE UTW01000 #> 5 ARIZONA STRIP DISTRICT OFFICE AZA00000 #> 6 SOUTHWEST DISTRICT OFFICE COS00000
# Read in data from the feature service res <- arc_select( lyr, fields = c("ADM_UNIT_CD", "ADMIN_ST"), geometry = FALSE ) dplyr::glimpse(res)
#> Rows: 125 #> Columns: 2 #> $ ADM_UNIT_CD <chr> "NVB02000", "ORN04000", "CAN06000", "ORV04000", "UTW02000"… #> $ ADMIN_ST <chr> "NV", "OR", "CA", "OR", "UT", "CO", "WY", "MT", "OR", "NV"…
Replacing codes with domain labels
Above, we viewed some domain labels and codes for the administrative unit code field, ADM_UNIT_CD. Let’s replace the existing coded values with their corresponding labels for easier interpretation:
# Replace the domain codes with labels offices_encoded <- encode_field_values(res, lyr, field = "ADM_UNIT_CD")
#> ! ADM_UNIT_CD contains 1 value that is not a valid code: #> "UTC04000"# Updated field values dplyr::glimpse(offices_encoded)#> Rows: 125 #> Columns: 2 #> $ ADM_UNIT_CD <chr> "TONOPAH FIELD OFFICE", "NW OREGON TILLAMOOK FIELD OFFICE"… #> $ ADMIN_ST <chr> "NV", "OR", "CA", "OR", "UT", "CO", "WY", "MT", "OR", "NV"…Replacing codes with descriptive labels can improve readability and make the data more suitable for display in maps or other user-facing applications.
Adding domain labels as metadata
If you prefer to keep the original coded values and simply add the labels as metadata, this is possible using the
labeloption, which assignshavenlabels to each of the existing values. This option is useful for analysis workflows where both the code and label are needed.Below, we add labels to the Administrative State Code field (
ADMIN_ST):# Add domain labels offices_labelled <- encode_field_values(res, lyr, field = "ADMIN_ST", codes = "label") # convert to tibble to see labeling tibble::as_tibble(offices_labelled)#> # A tibble: 125 × 2 #> ADM_UNIT_CD ADMIN_ST #> <chr> <hvn_lbll> #> 1 NVB02000 NV #> 2 ORN04000 OR #> 3 CAN06000 CA #> 4 ORV04000 OR #> 5 UTW02000 UT #> 6 COF03000 CO #> 7 WYR02000 WY #> 8 MTL02000 MT #> 9 ORN02000 OR #> 10 NVL03000 NV #> # ℹ 115 more rows# Check the field haven::is.labelled(offices_labelled$ADMIN_ST)#> [1] TRUE# View labels labelled::val_labels(offices_labelled$ADMIN_ST)#> Alaska Arizona California Colorado Eastern States #> "AK" "AZ" "CA" "CO" "ES" #> Idaho Montana New Mexico Nevada Oregon #> "ID" "MT" "NM" "NV" "OR" #> Utah Wyoming #> "UT" "WY"This approach preserves the original data structure while enhancing interpretability for downstream analysis.