Benchmark metrics: Explain what these values are in more detail

RMI-PACTA / r2dii.analysis

Tools to Calculate Climate Targets for Financial Portfolios

https://rmi-pacta.github.io/r2dii.analysis

Other

12 stars 8 forks source link

Benchmark metrics: Explain what these values are in more detail #105

Open maurolepore opened 4 years ago

maurolepore commented 4 years ago

(Extracted from https://github.com/2DegreesInvesting/r2dii.analysis/pull/104#issue-435751759)

[Regarding] the benchmark output of target_market_share() (...) I think that these metric names are evocative and descriptive, however I think it would make sense to explain what these values are in a little more detail, where do you think the best place to host this is? I think we had briefly discussed the idea of a data_dictionary for the output, maybe this is the time to start thinking about that? -- @jdhoffa

AB#9905

maurolepore commented 4 years ago

If what we need to document is the output of ...

... a single function, I would document it in the @retrurn section of that function.
... multiple functions, I would consider documenting the multiple functions together (e.g. via @rdname); or document them separately but DRY the shared elements of @return via @template, or as we did with r2dii.match/vignettes/_validate-matches.md (that is #' @includeRmd vignettes/_validate-matches.md).

Instead of what I wrote above, it would be nice to document the output of all functions in a data_dictionary -- as we do in r2dii.data -- but this seems beyond the first release.

maurolepore commented 4 years ago

@jdhoffa is this something we plan before or after the initial release?

jdhoffa commented 4 years ago

I would say after actually, or at least after the internal review from colleagues to ensure our metric names are adequate and make sense

jdhoffa commented 3 years ago

Relates to #269