Document soil units

[infotroph]

The PEcAn standard approach to passing soil information is to pass a soil_physics input that provides paths to (an ensemble of) netCDFs. Like the met files, these are intended to be usable by all models and contain a standard set of variables with their names and units following biogeochemistry conventions.

The current de facto standard is set by the PEcAn.data.land::soil_params() function, which populates a set of physical and hydraulic parameters via pedotransfer function from basic texture information. We should:

• Audit the existing names and units for alignment with standard biogeochemical usage
• Make sure all are listed in PEcAn.utils::standard_vars
• Add a book section that lists all the variables expected in a soil_physics file and states whether each is mandatory or optional and which PEcAn tools can help estimate it when no direct measurement is available

Not in scope for this issue: At least some models also support the concept of a "soil PFT" that specifies distributions for model-specific parameters which vary by soil type. Because they follow model-specific naming and unit conventions, documenting these is a separate task.

[ayushman1210]

Hi @infotroph,
The plan would be to audit the variables produced by soil_params(), align names/units with biogeochem conventions, register them in standard_vars, and add a short book section documenting the soil_physics inputs clearly distinguishing a minimal required set from optional variables that can be model or data-dependent.
If that scope looks OK, would you mind assigning this issue to me?
thanks !!

[infotroph]

Huh. Turns out we have a PEcAn.data.land::soil.units() that appears to contain all the soil_params variables. Need to think about how that fits in and whether documentation should copy from it or point to it.

[infotroph]

@ayushman1210 You're welcome to work on this, but be aware that documentation work requires a fair amount of familiarity with the system and what I wrote may not be a complete list of the work needed to close the issue. Since I missed the existence of soil.units in the original description, seems wise to add a step of checking for documentation that already exists elsewhere and could be made more visible.

[infotroph]

• Define and enforce whether soil_depth is referenced to the top, middle, or bottom of the layer. At the moment we save the top depth from gSSURGO but bottom depth from SoilGrids. Sipnet assumes it is bottom depth; other models not yet checked.
• Confirm that existing code aligns with the defined standard. I know I recently saw some nc files whose depth unit was listed as meters but contained values definitely in cm, but have not yet tracked down which line of code created them.

[ashum9]

Hi @infotroph,
Thanks for the clear outlin this will make soil_physics more consistent and easier to use.
I'd tackle:

Auditing soil_params() vars for biogeochem name/unit alignment.
Registering them in standard_vars.
Adding a book section listing expected soil_physics vars (mandatory vs. optional), with PEcAn estimation tools.

Plus, from your notes:

Integrate existing docs like soil.units() for better visibility.
Standardize soil_depth (top/mid/bottom?) across sources and models.
Fix code for unit consistency in nc files.

I can dedicate time to the audit and documentation updates and would love to contribute. Please assign this issue to me.
Thanks!

[infotroph]

Further detail on top vs bottom depth, copied here from comments on #3643: extract_soil_gssurgo treats depth as being to the top of the layer, but everything else I've found is to the bottom or unstated:

• standard_vars.csv is explicit that depth means to bottom
• The SoilGrids tools use bottom depth when one number is needed, but also are good about keeping labels with explicit top and bottom depths in most places.
• soil.units does not say.
• soil2netcdf doesn't state either way (nor do any internals care), but its example uses bottom depth
• write.config.SIPNET explicitly treats depths as bottom of layer
• My currently open PR Rothc: Soil file support + read options from settings file #3788 will make RothC assume depths as bottom of layer if nobody stops me first 😈. Working on that is what made me notice the difference from how the gSSURGO function works.