adding geomorphon proportions by soil series to fetchOSD()

[dylanbeaudette]

This PR makes available soil series -- geomorphon summaries (area-weighted proportions) available via fetchOSD().

SoilWeb now maintains a snapshot of soil series -- geomorphon cross-tabulation, updated each SSURGO refresh cycle. Currently, this is only available for CONUS and at 30m resolution as defined by the current gSSURGO snapshot.

Geomorphons were derived from a 30m CONUS DEM, using GRASS GIS and the following:

r.geomorphon --o dem=elev30_int forms=forms30 search=75 skip=5 flat=1.718

Pixel-wise cross-tabulation at 30m resolution was performed using r.stats from GRASS GIS.

I plan to document these data and methods soon.

EDIT: This PR will also include a basic vignette outlining the purpose, background, and status of all functions and data sources which depend on SoilWeb. As @brownag pointed out, there are many details hidden behind functions like fetchOSD() that could use an explanation within soilDB.

[brownag]

This appears to work as expected.

I think that making process steps metadata available is important for these less straightforward DEM derivatives like geomorphons... and also we should be defining what geomorphons are and citing the original paper and GRASS implementation.

e.g.

Jasiewicz J, Stepinski T (2013). "Geomorphons - a pattern recognition
approach to classification and mapping of landforms."
Geomorphology, 182, 147-156. doi:10.1016/j.geomorph.2012.11.005
https://doi.org/10.1016/j.geomorph.2012.11.005.

Jasiewicz J, Stepinski T, GRASS Development Team (2024). Geographic
Resources Analysis Support System (GRASS) Software, Version 8.3.
Open Source Geospatial Foundation, USA. r.geomorphon module,
https://grass.osgeo.org/grass-stable/manuals/r.geomorphon.html.

This is especially important if you are recommending folks use the summaries for anything more than a simple comparison of the signatures between series--users don't have the benefit of looking at the spatial derivative itself, just the summary, which makes it a bit of a black box.

The proportions are going to be sensitive to the specific parameters and DEM source/resolution/processing you used, as well as all of the other assumptions that come with making "series level" summaries from SSURGO geometries. I am not sure that is a soilDB problem though, it is more of a SoilWeb matter... the official documentation on SoilWeb (once it exists) can just be linked from the soilDB docs.

[dylanbeaudette]

Thanks for testing.

See my last sentence above: I plan to document these data and methods soon. I'll be sure to ask for help when it comes to describing and citing methods / software that I've used for over a decade.

On a more serious note, I'd like to add a new vignette to soilDB which documents the purpose, background, and status of all SoilWeb related functions and data sources. This PR is a fine place to do that.

[dylanbeaudette]

I'm nearly finished with this vignette. It is quite long, and requires a number of soilDB functions to successfully query APIs. Not entirely sure if the logic in the top R chunks are sufficient to: protect against connectivity issues with CRAN servers -- APIs.

Ideally, this vignette would only be viewed on the GH website and not via CRAN-hosted copy.

[dylanbeaudette]

Let me know if the new vignette needs additional tweaks to avoid CRAN-related errors. I'd prefer that it only be fully built via pkgdown for the GH website.

[brownag]

There will be no CRAN related errors since you are using R_SOILDB_SKIP_LONG_EXAMPLES environment variable, but this also means the code will not be run except in environments where this env var is set to FALSE (only on our GH pages build)

Since it is a vignette, it will be visible on the CRAN site, r-universe, and to users calling vignette(package="soilDB") without any of the code running or output generated. It is best to write the vignette with that in mind.

If you do not want it to be part of the package or visible on CRAN, we can add articles that are not vignettes to the GH site, but that is a different process and it is not a vignette, strictly speaking. If that is what you want, I do not see the benefit of having it in the package repository, it would be fine to just link to custom-built HTML at https://ncss-tech.github.io/AQP/soilDB from the github site.

I also would prefer to not have igraph used for anything in this if it is a vignette. Though it appears to pass checks, if you are calling requireNamespace("igraph") in a vignette, igraph should be in suggests. And I do not want to add igraph to suggests.

My recommendation in general is to focus on the data structures returned, and not on the visualization of them. The narrative should make sense with or without the code executed and knitted into the output.

[brownag]

Initial review comments

[dylanbeaudette]

There will be no CRAN related errors since you are using R_SOILDB_SKIP_LONG_EXAMPLES environment variable, but this also means the code will not be run except in environments where this env var is set to FALSE (only on our GH pages build)

Stepping back a moment. I agree that a vignette is probably the right type of document, however, fully documenting these data requires that fetchOSD() is able to run without error. It seems like most calls to web services in tests, examples, and vignettes are prone to triggering CRAN errors.

Any suggestions?

[brownag]

There will be no CRAN related errors since you are using R_SOILDB_SKIP_LONG_EXAMPLES environment variable, but this also means the code will not be run except in environments where this env var is set to FALSE (only on our GH pages build)

Stepping back a moment. I agree that a vignette is probably the right type of document, however, fully documenting these data requires that fetchOSD() is able to run without error. It seems like most calls to web services in tests, examples, and vignettes are prone to triggering CRAN errors.

Any suggestions?

My suggestion is that you explain the result structure, without explaining specifics of the actual result of code being run. It will not cause issues with CRAN because you are setting eval=FALSE on CRAN.

[dylanbeaudette]

I'll think about this a little more. I'm considering a manual page and more complete description as an article in vignettes/articles or similar. The constraints of CRAN-friendly vignettes are annoying.

[dylanbeaudette]

I'll think about this a little more. I'm considering a manual page and more complete description as an article in vignettes/articles or similar. The constraints of CRAN-friendly vignettes are annoying.

On second thought, I'm going to use the conditional evaluation in the setup block of the Rmd to keep a bare-bones version on CRAN and local R package documentation. The more interesting version on the soilDB website will contain output from code blocks. I'm done with the new documentation, and will merge after checks are completed.