specify categorical raster details in definitions file

[dylanbeaudette]

Building off of #28...

  categorical=list(
    `Geomorphon Landforms`=list(
       data='L:/Geodata/DEM_derived/forms10.tif',
        legend=list(
          levels=1:10,
          labels=c('flat', 'summit', 'ridge', 'shoulder', 'spur', 'slope', 'hollow', 'footslope', 'valley', 'depression')
        )
     ),
  ...
 )

[dylanbeaudette]

Great idea by @brownag: reports include a cats.R (or similarly named) file that specifies:

1. codes, names, ordering, colors for the "baseline" set of categorical data
2. reasonable defaults for any user-supplied categorical data
3. template for adding your own, custom codes, names, ordering, colors

[brownag]

I have a prototype set up to produce summary plots, tables and spatial output for arbitrary categorical datasets. The prototype is based on the map unit summary report from region 2. The report itself is still rough, but watch for a big commit (will update these posts with commit hashcode) in the next few days.

For now, here is a proposed list-based template for the categoricals. I'm keeping it in a "categorical_definitions.R" file... but pretty ambivalent about the name. Open to thoughts/suggestions about additional required or optional components for these definitions. Also room for dataset-specific toggling of report components. Let me know what you think.

categorical.defs[['curvature']] <- list(header="Slope Shape (Curvature) Summary",
                                        description="Curvature classes were generated using a 5x5 moving window and a regional 30m or 10m integer DEM. The precision may be limited, so use with caution. See instructions for using your own (higher resolution) curvature classification raster. The conventions used here are \"C\" = concave, \"L\" = linear, and \"V\" = convex; \"down slope\" / \"across slope\". Window size has a significant impact on reported curvature classes; larger windows = more generalization. Curvature class and colors are aligned with an idealized *shedding* &rarr; *accumulating* hydrologic gradient.",
                                        usage="Use the graphical summary to identify patterns, then consult the tabular representation for specifics.\n* ",
                                        decimals=2,
                                        levels = c(33, 32, 23, 31, 22, 21, 13, 12, 11), 
                                        labels = c('VV', 'LV', 'VL', 'CV', 'LL', 'CL', 'VC', 'LC', 'CC'),
                                        colors=brewer.pal(9, 'Spectral'),
                                        keep.all.classes=TRUE)

categorical.defs[['geomorphon']] <- list(header="Geomorphon Landform Classification",
                                         description="Proportion of samples within each map unit that correspond to 1 of 10 possible landform positions, as generated via [geomorphon](https://grass.osgeo.org/grass70/manuals/addons/r.geomorphon.html) algorithm. Landform classification by [this method](http://dx.doi.org/10.1016/j.geomorph.2012.11.005) is scale-invariant and is therefore not affected by computational window size selection. Landform class labels and colors are aligned with an idealized *shedding* &rarr; *accumulating* hydrologic gradient. \"Flat\" is based on a 3% slope threshold.Map units are organized (in the figure) according to the similarity, computed from proportions of each landform position. The [dendrogram](http://ncss-tech.github.io/stats_for_soil_survey/chapter_5.html) on the right side of the figure describes relative similarity. \"Lower branch height\" (e.g. closer to the right-hand side of the figure) denotes more similar landform positions.",
                                         usage="Use the graphical summary to identify patterns, then consult the tabular representation for specifics.",
                                         decimals=2,
                                         levels=1:10, 
                                         labels = c('flat', 'summit', 'ridge', 'shoulder', 'spur', 'slope', 'hollow', 'footslope', 'valley', 'depression'),
                                         colors=c('grey', brewer.pal(9, 'Spectral')),
                                         keep.all.classes=TRUE)

categorical.defs[['nlcd']] <- list(header="National Land Cover Dataset (NLCD)",
                                   description="These values are from the [2011 NLCD](https://www.mrlc.gov/nlcd2011.php) (30m) database.",
                                   usage="Use the graphical summary to identify patterns, then consult the tabular representation for specifics.",
                                   decimals=2,
                                   levels = c(0L, 11L, 12L, 21L, 22L, 23L, 24L, 31L, 41L, 42L, 43L, 51L, 52L, 71L, 72L, 73L, 74L, 81L, 82L, 90L, 95L), 
                                   labels = c("nodata", "Open Water", "Perennial Ice/Snow", "Developed, Open Space", 
                                              "Developed, Low Intensity", "Developed, Medium Intensity", "Developed, High Intensity", 
                                              "Barren Land (Rock/Sand/Clay)", "Deciduous Forest", "Evergreen Forest", 
                                              "Mixed Forest", "Dwarf Scrub", "Shrub/Scrub", "Grassland/Herbaceous", 
                                              "Sedge/Herbaceous", "Lichens", "Moss", "Pasture/Hay", "Cultivated Crops", 
                                              "Woody Wetlands", "Emergent Herbaceous Wetlands"),
                                   colors = c("#000000",  "#476BA0", "#D1DDF9", "#DDC9C9", "#D89382", "#ED0000", "#AA0000", 
                                              "#B2ADA3", "#68AA63", "#1C6330", "#B5C98E", "#A58C30", "#CCBA7C", 
                                              "#E2E2C1", "#C9C977", "#99C147", "#77AD93", "#DBD83D", "#AA7028", 
                                              "#BAD8EA", "#70A3BA"))

categorical.defs[['mesic thermic']] <- list(header="Soil Temperature Regime Uncertainty (Mesic/Thermic)",
                                   description="Areas with an uncertain soil temperature regime occur where the confidence interval for modeled mean annual soil temperature overlaps mesic/thermic break of 15&deg; C.",
                                   usage="Use this layer to identify the map units occuring where soil temperature regime cannot be definitively assigned.",
                                   decimals=2,
                                   levels = c(1,0), 
                                   labels = c("uncertain","certain"),
                                   colors = brewer.pal(3, 'Spectral')[1:2])

categorical.defs[['R105']] <- list(header="R105/106-ness Index",
                                            description="This layer aggregates slope, curvature and aspect data to determine how many of the required abiotic factor criteria are met for the fire-dominated chaparral ecological sites (18XIR105 and 18XIR106). These two ecological sites differ in climatic characteristics (R105 is mesic to borderline thermic) but both require slopes >30%, convex curvature and south-facing aspect.",
                                            usage="The numeric values in class names correspond to the number of abiotic factor criteria met (out of a total of 3). At least two of the criteria need to be met in order to support the R105/106 ecosite assignment based on the soil propertiesa (typically shallower, fraggy/rocky or both) and existing vegetation.  The proportions in the bar chart show the relative abundance of samples meeting that number of criteria within each map unit. ",
                                            decimals=2,
                                            levels = c(0,1,2,3), 
                                            labels = c("0","1","2","3"),
                                            colors = brewer.pal(4, 'Spectral'))

### TEMPLATE
# categorical.defs[['%%%PATTERN%%%']] <- list(header="%%%HEADER%%%",
#                                    description="%%%DESCRIPTION%%%",  
#                                    usage="%%%USAGE%%%",
#                                    levels = %%%LEVELS%%%, 
#                                    labels = %%%LABELS%%%,
#                                    colors = %%%COLORS%%%,
#                                    decimals = %%%DECIMALS%%%)
## replace %%%PATTERN%%% with a regular expression that uniquely matches the categorical raster dataset name from the config file
## replace %%%HEADER%%% with the text to be used as header for plot and table in this dataset. will be a 3rd level header (preceded by ###) in markdown
## replace %%%DESCRIPTION%%% with a text description of the dataset, method used to obtain, label meanings, assumptions, supplemental info/links etc.
## replace %%%USAGE%%% brief text description of how to interpret/compare the output
## replace %%%DECIMALS%%% with the number of decimals you would like to truncate table proportions to (default = 2)

##The following three definitions are specified as vectors and are intended to be 1:1 with one another or length 1
## replace %%%LEVELS%%% numeric vector corresponding to the unique values from raster (e.g. from unique(dat$values))
## replace %%%LABELS%%% character vector describing the numeric value. order matches the numeric values of LEVELS.
## replace %%%COLORS%%% character vector hexadecimal or other suitable color specification (e.g. integers, color.brewer()), same order as above

### OPTIONAL
## NOTE: to add an optional element be sure to add a comma to the categorical metadata definition list
###
## keep.all.classes=TRUE 
##
#### keep.all.classes will prevent the removal of un-used classes from the legend and tabular output

[brownag]

See cd0f02bb256ae543b6830e5e43f606f61f47db99 in branch MUSumCat

[brownag]

Continuation of the applications of proposed categorical definition template in #53