Consolidate text between ARGS SPEC and UG (part 1 of 3) #604

emlys · 2021-08-03T22:53:07Z

Description

First part of #567.

Carbon
Coastal Blue Carbon
Coastal Blue Carbon Preprocessor
Coastal Vulnerability
Crop Production Percentile
Crop Production Regression
DelineateIt

Checklist

~~- [ ] Updated HISTORY.rst (if these changes are user-facing)~~
~~- [ ] Updated the user's guide (if needed)~~

…/models-A-D

…task/567/models-A-D

src/natcap/invest/spec_utils.py

dcdenu4 · 2021-08-26T11:42:00Z

src/natcap/invest/carbon.py

-            "name": "Calculate Sequestration"
+                "Enable sequestration analysis. This requires inputs "
+                "of land use/land cover maps for both current and future "
+                "scenarios. ") + REQUIRED_IF_SELECTED % (


I appreciate trying to unify the language for these common phrases. Is there a code style preference of concatenation like you have here or using f strings like above on line 39? Or, whatever looks most readable?

I was trying to use f strings as much as possible but this one wouldn't all fit in one line

dcdenu4 · 2021-08-26T11:44:32Z

src/natcap/invest/carbon.py

+                "selected, this should be the reference, or baseline, future "
+                "scenario against which to compare the REDD policy scenario. "
+                f"{REQUIRED_IF_SELECTED % 'calculate sequestration'}"),
+            "name": "future land use/land cover"


I almost wonder if we should have a LULC constant similar to the others for land use/ land cover. I'm always writing that in different ways.

Maybe because capitalization could make this tricky if it's going as the first thing in a sentence, we could have a document with commonly used terms to reference when writing new models. Sounds a bit tedious, but I'd love to not have to think about whether I should write: LULC, or land use/land cover or land use land cover, etc...

I think I prefer a styleguide as the solution to this problem.

I almost wonder if we should have a LULC constant similar to the others

I like this

One advantage of a constant over a style guide is reducing repeated text - will reduce the number of words we need to get translated.

Thinking about this more, it probably won't help with translation. We can swap out translated text at the paragraph level, and probably sentences, but words/phrases need to be translated in context. So the benefit of using a constant is really just for consistency.

dcdenu4 · 2021-08-26T11:56:27Z

src/natcap/invest/carbon.py

-                "A GDAL-supported raster representing the land-cover of the "
-                "current scenario."),
-            "name": "Current Land Use/Land Cover"
+                "A map of land cover for the current scenario. "


Should land cover be land use/land cover as you've used consistently below? I also might just be going too far with thinking how consistent these should be...

I'm going with LULC everywhere for now

dcdenu4 · 2021-08-26T11:58:11Z

src/natcap/invest/carbon.py

+                "lucode": {
+                    "type": "integer",
+                    "about": (
+                        "Land use/land cover code. Every value in the LULC "


Should we use LULC here? I think it's the first time it's been used to describe land use/land cover. Again, I'm probably taking this too far, haha

Following the 'spell out the first time' rule in this context may not be possible because the order of displaying these strings in the UG is not guaranteed to be the same. I think for common acronyms (LULC, DEM, AOI, TFA) it should be ok to define them only once for the whole user's guide (like on the data sources page). But also, sometimes it's helpful to write out.

At least for me, TFA is not like those others in terms of the recognizability of the acronym.

src/natcap/invest/carbon.py

dcdenu4 · 2021-08-26T12:03:14Z

src/natcap/invest/carbon.py

-            "name": "Annual Rate of Change in Price of Carbon"
+                "The annual increase of the price of carbon. "
+                f"{REQUIRED_IF_SELECTED % 'run valuation model'}"),
+            "name": "annual price change"


I'm not sure this name or the about section get at this being a rate of change versus absolute change.

I changed this to "The relative annual increase". Hopefully that plus the type (ratio) will make it clear enough?

dcdenu4 · 2021-08-26T12:04:15Z

src/natcap/invest/carbon.py

-_TMP_BASE_FILES = {
-    'aligned_lulc_cur_path': 'aligned_lulc_cur.tif',
-    'aligned_lulc_fut_path': 'aligned_lulc_fut.tif',
-    'aligned_lulc_redd_path': 'aligned_lulc_redd.tif',
-}
-


Were these files unused?

Actually I was wrong about this, not sure why I removed it.

dcdenu4 · 2021-08-26T12:11:37Z

src/natcap/invest/coastal_blue_carbon/coastal_blue_carbon.py

        },
        "do_economic_analysis": {
-            "name": "Calculate Net Present Value of Sequestered Carbon",
+            "name": "Do Valuation",


I think this name should more reflect the valuation being done at the cost of being a little wordy. Maybe I just don't like the Do part. Calculate Valuation, Run Valuation...

Changed to Run Valuation

dcdenu4 · 2021-08-26T12:15:27Z

src/natcap/invest/coastal_blue_carbon/coastal_blue_carbon.py

+                "The price of CO2E at the baseline year. Required if Do "
+                "Valuation is selected and Use Price Table is not selected."),


Should this use the REQUIRED_IF_SELECTED?

f"{REQUIRED_IF_SELECTED % 'Do Valuation'} and Use Price Table is not selected".

Right now the REQUIRED_IF_SELECTED is a standalone sentence ending with a period, so it wouldn't work exactly here.

dcdenu4 · 2021-08-26T12:40:53Z

tests/test_args_specs.py

+                if any(l.isupper() for l in arg['name']):
+                    print(arg['name'])


Was this for debug purposes?

yea, I was making sure to lowercase all the names. Removed this.

dcdenu4

Hey @emlys , this is looking great. Also a shout out to whoever is updating the Args Spec wiki portion with these changes / ideas in mind. My first thought was, we should make sure to get this down in the wiki, and it already looks like it's there.

A few things came to mind when reviewing.

Do we have formal guidelines on LULC vs land use/land cover vs land cover?
How do others feel about the REQUIRED_IF_SELECTED helper for consistent phrasing? I think I like this approach but do think the only benefit is consistency, since it doesn't really shorten anything and is more syntax onerous.
Side-Note: Should we update the args section of the wiki to better define what information should go in that docstring?

davemfish

Thanks for all this work @emlys ! I reviewed all the changes, but with most attention to CV.

I see there's also conflicts, probably from the recent PR you and I did? #623

davemfish · 2021-08-26T16:15:56Z

src/natcap/invest/carbon.py

+                "selected, this should be the reference, or baseline, future "
+                "scenario against which to compare the REDD policy scenario. "
+                f"{REQUIRED_IF_SELECTED % 'calculate sequestration'}"),
+            "name": "future land use/land cover"


I think I prefer a styleguide as the solution to this problem.

davemfish · 2021-08-26T16:33:34Z

src/natcap/invest/coastal_blue_carbon/coastal_blue_carbon.py

+                "Annual increase in the price of CO2E. Required if Do "
+                "Valuation is selected and Use Price Table is not selected.")


I can imagine that when editing a bulk of these it came in handy. But going forward, adding one or two new specs 6 months or a year from now, I think it will be easier for me to write the whole sentence here. Also easier to verify that it's correct grammar.

I don't feel too strongly so I'm okay with leaving these in. I'm just not sure I'd prefer to use them myself in the future.

davemfish · 2021-08-26T16:39:53Z