New market_description

[maurolepore]

Relates to https://github.com/2DegreesInvesting/r2dii.analysis/pull/10#issuecomment-566047068
Closes #24
Thanks @vintented

[maurolepore]

@vintented,

I see that the description of market is remarkably similar to that of portfolio, and that both have the alias "equity".

I also see that both datasets have the same column names:

setdiff(
  names(r2dii.analysis::portfolio),
  names(r2dii.analysis::market)
)
#> character(0)

setdiff(
  names(r2dii.analysis::market),
  names(r2dii.analysis::portfolio)
)
#> character(0)

^{Created on 2019-12-18 by the reprex package (v0.3.0.9001)}

Should we document both datasets together? If so, how would you adapt the description to clarify the difference between the two datasets?

[vintented]

@maurolepore

The only difference between the portfolio and market is that the market is used as a benchmark. So, in theory, you could upload any two portfolios and use one of them as the benchmark.

We still probably want two portfolios because the values will be different between the two. @2diiKlaus maybe has some suggestions as well.

[2diiKlaus]

Market and portfolio are 2 different things and we need to keep them separate.

Furthermore, there are several other things that need to be considered. Thus my response will be rather long:
Sample data needs to exist

• at several stages of the code, i.e. we need a portfolio_input file, a portfolio_mapped file and a portfolio_result file (in this case here we are talking about the portfolio_result file)

• for different classes of datasets, even though market and portfolio look very similar they are different in terms of their usage and where they come from:

Usage As Vincent said:
The Market (which is actually an imprecise description and should be called Corporate_Economy instead!) is a benchmark (there are other benchmarks as well, such as the economy (based on the IEA), indices, an average of the peer portfolios, etc.). Thus the class is rather a benchmark and the tool will have those datasets as something we (2dii) prepares

The Portfolio is the dataset that is analysed and compared to one or more benchmarks. It is input by the user of our tools and thus not intrinsic to our tools. Portfolios can range from "bank's loanbook" over "Equity portfolios" to "mixed portfolio".

The market and the aligned market will be added to the portfolio as one of the benchmarks, BUT the market will not be a unique market, it is a market that reflects the portfolio specific regional allocation. e.g. a portfolio solely active in the OECD will be compared to the OECD market as a benchmark while a portfolio active in 2 regions 50%-50% will be compared to a weighted market (1 to 1) of those regions.

We thus have a matrix of datasets. I will prepare an excel table and copy it here to provide a better overview.

In the case of the SDA analysis: the global market (equity, corporate economy, or bond market depending on the input type) is the only benchmark that can be used as it doesn't make sense to use any other benchmark for this convergence metric (the metric itself says every actor should converge at a target year where the aligned market will need to be).

[2diiKlaus]

#' Description of market datasets
#'
#' Type of data: Benchmark
#' Market type: Listed equity market
#' Status: PACTA results dataset
#'
#' Markets reflect the investable universe specific to the financial instrument (such as equity, bonds, #' loans) of the portfolio used in the analysis
#' Markets are used as a benchmark to compare the portfolio to understand the positioning within
#' the investable universe.
#' The PACTA results dataset of the market includes the technology & sector exposure of the market #' to the climate-relative sectors assessed in the PACTA tool in terms of monatory value as well as
#' production capacity and the alignment of the production profiles with different climate scenarios
#' The dataset includes sector level emissions factors (per unit of production) associated with the
#' market's relative exposure to the climate-relevant technology
#'
#' @name market_portfolio_description
#' @Seealso [data_dictionary]
#' @family generic datasets
#' @examples
#' library(dplyr)
#'
#' data_dictionary() %>%
#' filter(dataset == "market_portfolio")
NULL

@maurolepore I just adjusted the first part and not the part with @name etc.
@vintented Maybe also good for you to check it and provide feedback if this is clear

I also integrated the type, market type (as there are several markets) and status to reflect to position in the code process.

[vintented]

@2diiKlaus is clear to me!

[maurolepore]

I see lot's of good information and I see it's clear to @vintented.

@vintented, can you help me extract actionable steps? Here are my questions:

.

#25 adds the new datasets portfolio_demo and market_demo, but @2diiKlaus said that "Market ... should be called Corporate_Economy" (#26 (comment)).

1. Should I rename market_demo to corporate_economy_demo before I merge New portfolio_description #25?

.

@2diiKlaus said that "Sample data needs to exist ... at several stages of the code [and] for different classes of datasets ... We thus have a matrix of datasets ... " (#26 (comment)):

2. Should we open a separate issue to ensure we don't forget to create all these datasets?

.

#26 (comment) contains what seems valuable information.

3. Should New market_description #26 (comment) become formal documentation of some kind (e.g. the #' @details section of market_portfolio_description, or an article on the website of r2dii.dataraw.)?

.

#26 (comment) documents market_description.

4.1. Does this confirm that market_description and portfolio_description should be merged into this single piece of documentation?

4.2. Does #26 (comment) replace what @vintented shared before (currently at R/portfolio_description.R in #25 )?

[2diiKlaus]

Should I rename market_demo to corporate_economy_demo before I merge #25?

yes please

Should we open a separate issue to ensure we don't forget to create all these datasets?

yes sounds like a very good idea!

Should #26 (comment) become formal documentation of some kind (e.g. the #' @details section of market_portfolio_description, or an article on the website of r2dii.dataraw.)?

I would be fine with this. Probably needs a bit of polishing, but can form the basis!

4.1. Does this confirm that market_description and portfolio_description should be merged into this single piece of documentation?

not sure about it, as users might get confused (especially non 2dii users but also 2dii internal users). I would be fine with it as long as the descriptions is very clear about the differences. But I think it might be better to keep them separate - not sure as said. maybe @vintented can reflect on the fact how "newer" employees see it and if the difference is clear to them even if we just have a single documentation?!