Documentation items

[jrising]

I'm including these as a single list, but feel free to split them into multiple issues if anything here is more involved.

README:

• Make it clear that this is an internal tool (I guess it's private anyway, but good to be explicit about it), and meant to be run on RCC with the data there.
• pipeline documentation and parameters documentation are a broken links.

Documentation:

• In addition to the simple equation here, people need to know the equation for "projections with uncertainty", since that is the one we want people to actually use. That one is $M_{itk} = (\hat\alpha_{ik} T_t + \hat\beta_{ik} T_t^2) Y_{it}^{\hat\gamma_k} + \hat\theta_{ik} T_t Y_{it}^{\hat\gamma_k} + \hat\phi_{kit}$
• I suggest we switch from $M_{it}$ to $D_{it}$ throughout.
• Do you have the material in "User interface" from the dropbox paper anywhere in the documentation? Most users will be most concerned about that.
• We need to say at the top what this is all about. Something like:

Flexible Damage Functions are statistical emulators of the high-resolution CIL projects, which can be incorporated into other models to project climate impacts and damages. These damage functions map global or national temperature and national income levels to impact levels. This is useful to estimate impacts along new socioeconomic and climate scenarios and for models for which income and/or temperature are endogenous.

• Can we split the documentation up into "user" and "developer" documentation? Like as subheadings on the first page? Then the user documentation might start with:

The links below describe how to use and interpret the Flexible Damage Function parameter files.

• I think the current intro text, "FlexDamage fits region-specific damage functions" needs a somewhat different introduction. That is, this documentation currently describes the tool, when for most people we want it to describe the product. In the developer documentation, I would start things out by re-introduction things: The links below describe FlexDamage, CIL's tool for creating Flexible Damage Functions..

Sector Reports:

• The table under 0.1 is confusing, because it does not provide statistics for the whole sector. This is currently a table of the gamma analysis. I think you should just merge it with the table under section 1.1.
• Are you going to add the different specification part of "Gamma Estimates Under Different Specifications"? As it currently stands, the "Gamma Robustness (Sensitivity Analysis)" section is mislabeled, since this is really just the single gamma result.
• Make sure we include units, and more broadly what is described. So, for example, we might have different damage functions for: "Change in cassava yields (log change in yields) under full adaptation", "Change in total calories produced by region (calories per year) under full adaptation", "Market valuation of agricultural damages including adaptation costs (2015 USD per year)."
• You have all of the damage function parameters, labeled as things like zeta in Table 2, but these aren't fully defined. Having the full projection equation will help with that.
• I mentioned that we want to drop the convexity analysis section when there is a constraint on the second-order term.
• The worst offender graph shows just the curves. That's not very useful without comparing it to the raw data. I think you should just show 1-2 worst offenders on a graph with their data.

Looking good!