Package 'mrdrivers'

Title: Create GDP and Population Scenarios
Description: Create GDP and population scenarios This package constructs the GDP and population scenarios used as drivers in both the REMIND and MAgPIE models.
Authors: Johannes Koch [aut, cre], Bjoern Soergel [aut], Deborra Leip [aut], Falk Benke [aut], Jan Philipp Dietrich [aut]
Maintainer: Johannes Koch <[email protected]>
License: LGPL (>= 3)
Version: 3.0.1
Built: 2024-10-11 14:15:18 UTC
Source: https://github.com/pik-piam/mrdrivers

Help Index

Get GDP and GDP per capita scenarios

Description

Like all scenarios in mrdrivers, the GDP and GDP per capita scenarios are the result of a harmonization exercise between past data and future projections. Together with the corresponding population scenarios (see calcPopulation()) they comprise a consistent set of scenarios.

By default the following scenarios are returned:

  • the SSPs, i.e. SSP1-5

  • the SDPs, i.e. SDP, SDP_EI, SDP_RC, and SDP_MC

  • SSP2EU

See the vignette: vignette("scenarios") for scenario options, definitions and references.

Usage

calcGDP(
  scenario = c("SSPs", "SDPs", "SSP2EU"),
  unit = "constant 2017 Int$PPP",
  average2020 = TRUE,
  ...
)

calcGDPpc(
  scenario = c("SSPs", "SDPs", "SSP2EU"),
  unit = "constant 2017 Int$PPP",
  average2020 = TRUE,
  ...
)

Arguments

scenario

A string (or vector of strings) designating the scenario(s) to be returned. Use toolGetScenarioDefinition() to learn what scenarios are available.
unit

A string specifying the unit of GDP. Can be either:

  • "constant 2017 Int$PPP" (default): Scenarios are constructed in constant 2017 Int$PPP.

  • "constant 2017 US$MER": Scenarios are constructed in constant 2017 Int$PPP and then converted with GDPuc::toolConvertGDP().

In all cases, GDP is returned in millions.
average2020

If TRUE (default), then the 2020 value is replaced by the 2018-2022 average. To be consistent, the yearly resolution is decreased to 5 year intervals.
...

Arguments passed on to calcDriver(), of which "extension2150" and "naming" are most often of interest. Other calcDriver() arguments are used for scenario fine-tuning and by package developers.

Value

magpie object with the requested output data either on country or on regional level depending on the choice of argument "aggregate" or a list of information if supplementary is set to TRUE.

See Also

Examples

## Not run: 
# Return default scenarios
calcOutput("GDP")
calcOutput("GDPpc")

# Return only the SSP2EU GDP scenario
calcOutput("GDP", scenario = "SSP2EU")

## End(Not run)

## Not run: 
calcOutput("GDPpc")

## End(Not run)

Get population and labour scenarios

Description

Like all scenarios in mrdrivers, the Population, Labour and Urban population share scenarios are the result of a harmonization exercise between past data and future projections.

By default the following scenarios are returned:

  • the SSPs, i.e. SSP1-5

  • the SDPs, i.e. SDP, SDP_EI, SDP_RC, and SDP_MC

  • SSP2EU

See the vignette: vignette("scenarios") for scenario options, definitions and references.

Usage

calcPopulation(scenario = c("SSPs", "SDPs", "SSP2EU"), ...)

calcLabour(scenario = c("SSPs", "SDPs", "SSP2EU"), ...)

calcUrban(scenario = c("SSPs", "SDPs", "SSP2EU"), asShare = TRUE, ...)

Arguments

scenario

A string (or vector of strings) designating the scenario(s) to be returned. Use toolGetScenarioDefinition() to learn what scenarios are available.
...

Arguments passed on to calcDriver(), of which "extension2150" and "naming" are most often of interest. Other calcDriver() arguments are used for scenario fine-tuning and by package developers.
asShare

If TRUE (default) urban population shares are returned. If FALSE, then urban population in millions is returned.

Value

magpie object with the requested output data either on country or on regional level depending on the choice of argument "aggregate" or a list of information if supplementary is set to TRUE.

See Also

Examples

## Not run: 
# Return the default scenarios
calcOutput("Population")

# Return the SSP2EU scenario
calcOutput("Population", scenario = "SSP2EU")

# Return the ISIMIP SSP scenarios
calcOutput("Population", scenario = "ISIMIP", extension2150 = "none", aggregate = FALSE)

## End(Not run)
## Not run: 
calcOutput("Labour")

## End(Not run)
## Not run: 
calcOutput("Urban")

## End(Not run)

MER over PPP ratio

Description

Get a conversion factor to convert GDP in constant 2017 Int$PPP into constant 2017 US$MER. Use the when argument to switch the year of the conversion factor. Source = WDI.

Usage

calcRatioPPP2MER(when = 2017)

Arguments

when

An integer (defaults to 2017) specifying the year of the PPP2MER factor.

Value

magpie object with the requested output data either on country or on regional level depending on the choice of argument "aggregate" or a list of information if supplementary is set to TRUE.

See Also

madrat::calcOutput()

Examples

## Not run: 
calcOutput("RatioPPP2MER")

## End(Not run)

Read Eurostat Population and GDP data

Description

Download, read and convert Eurostat population and GDP data.

Usage

downloadEurostatPopGDP(subtype)

readEurostatPopGDP(subtype)

convertEurostatPopGDP(x, subtype)

Arguments

subtype

A string. Available subtypes are:

  • "population": Population, ref demo_gind

  • "population_projections": Population projections, ref proj_19np

  • "GDP": GDP, ref nama_10_gdp

  • "GDPgr_projections_short": Projected GDP growth rates, 2023 forecast.

  • "GDPgr_projections_long":

x

MAgPIE object returned by readEurostatPopGDP

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource() and madrat::downloadSource()

Examples

## Not run: 
readSource("EurostatPopGDP", subtype = "population")

## End(Not run)

Read IMF

Description

Read-in data from the IMF's World Economic Outlook. Currently reading GDP per capita and current account balance data.

Usage

downloadIMF()

readIMF()

convertIMF(x, subtype = "all")

Arguments

x

MAgPIE object returned by readIMF
subtype

Use to filter the IMF data

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource() and madrat::downloadSource()

Examples

## Not run: 
readSource("IMF")

## End(Not run)

Read in the "Missing Islands" dataset

Description

Read in gdp or population data for minor islands (not included in big inventories) from a custom made data set that gets data from a variety of sources (e.g. CIA World Factbook, Insee, BEA, PRISM, and Woldometers).

Usage

downloadMissingIslands()

readMissingIslands(subtype)

convertMissingIslands(x)

Arguments

subtype

pop for population, or gdp for gdp
x

MAgPIE object returned by readMissingIslands

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource() and madrat::downloadSource()

Examples

## Not run: 
readSource("MissingIslands", subtype = "pop", convert = FALSE)

## End(Not run)

Read Population Estimates And Projections from the World Bank

Description

Read-in xlsx file from the World Bank's Population Estimates And Projections (PEAP) The PEAP data can't seemed to be accessed by the WDI::WDI package nor the World Bank's API directly. Manual download required from https://databank.worldbank.org/source/population-estimates-and-projections#

Usage

downloadPEAP()

readPEAP()

convertPEAP(x)

Arguments

x

MAgPIE object returned by readPEAP

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource() and madrat::downloadSource()

Read UN Population Division Data

Description

Read past UN population data.

Usage

downloadUN_PopDiv()

readUN_PopDiv(subtype = "estimates")

convertUN_PopDiv(x)

Arguments

subtype

String indicating version and sheet
x

MAgPIE object returned from readUN_PopDiv

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource() and madrat::downloadSource()

Read WDI data

Description

Download, read and convert WDI (World development indicators) data.

Usage

downloadWDI()

readWDI(subtype)

convertWDI(x, subtype)

Arguments

subtype

A string. Type of WDI data that should be read. Use the World Bank indicator abbreviation. Available subtypes are:

  • "SP.POP.TOTL": Population, total

  • "SP.POP.1564.TO": Working age population (15-64 years old)

  • "SP.URB.TOTL.IN.ZS": Urban Population (% of total)

  • "NY.GDP.MKTP.PP.KD": GDP,PPP (constant 2017 international Dollar)

  • "NV.AGR.TOTL.KD": Ag GDP, MER, (2010 US$)

  • "PA.NUS.PPPC.RF": Price level ratio of PPP conversion factor (GDP) to market exchange rate

  • "AG.SRF.TOTL.K2": Surface area (in square kms)

x

MAgPIE object returned by readWDI

Details

The workflow to update the WDI data is the following: call the download function manually, and rename the new WDI.rds file including the download date. Then change the file_name that is read by readWDI. This ensures, that the past data isn't changed between users.

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource() and madrat::downloadSource()

Examples

## Not run: 
readSource("WDI", subtype = "SP.POP.TOTL")

## End(Not run)

Read James 2019 updated dataset

Description

Read-in GDP per-capita data from the publication James, Spencer L., Paul Gubbins, Christopher JL Murray, and Emmanuela Gakidou. 2012. "Developing a Comprehensive Time Series of GDP per Capita for 210 Countries from 1950 to 2015." Population Health Metrics 10 (1): 12. doi:10.1186/1478-7954-10-12. from a .csv file to a magclass object

Usage

readJames2019(subtype)

convertJames2019(x, subtype)

Arguments

subtype

String indicating the data series
x

MAgPIE object returned by readJames2019

Details

2019 dataset from personal communication w/ B Bodirsky

Value

GDP per capita in USD05 in PPP or MER as magpie object

Functions

  • convertJames2019(): convert function

See Also

madrat::readSource() and madrat::downloadSource()

Examples

## Not run: 
readSource("James2019", subtype = "IHME_USD05_PPP_pc")

## End(Not run)

Read SSP

Description

Read-in an SSP data as magclass object

Usage

readSSP()

downloadSSP()

convertSSP(x, subtype = "all")

Arguments

x

MAgPIE object returned from readSSP
subtype

A string, either "all", "gdp", "pop", "lab", "urb"

Value

The read-in data, usually a magpie object. If supplementary is TRUE a list including the data and metadata is returned instead. The temporal and data dimensionality should match the source data. The spatial dimension should either match the source data or, if the convert argument is set to TRUE, should be on ISO code country level.

See Also

madrat::readSource()

Examples

## Not run: 
readSource("SSP", subtype = "gdp")

## End(Not run)

Tool used to consolidate the most common "convert" operations

Description

The most important and common "convert" operations are:

  • removing undefined countries,

  • using default set names "iso3c", "year", and "variable",

  • substituting NAs, see the "substituteNAsWith" argument,

  • fill in countries,

  • sort in chronological order.

Usage

toolGeneralConvert(
  x,
  useDefaultSetNames = TRUE,
  countryFillWith = 0,
  substituteNAsWith = 0,
  warn = TRUE,
  note = TRUE,
  ...
)

Arguments

x

A magpie object.
useDefaultSetNames

TRUE or FALSE.
countryFillWith
substituteNAsWith
warn

TRUE or FALSE.
note

TRUE or FALSE.
...

Arguments passed on to madrat::toolCountryFill()

Value

A magpie object.

Get information on available scenarios

Description

toolGetScenarioDefinition can be used to figure out which scenarios are made available by mrdrivers, and how they are constructed, i.e. what past data, future data and harmonization methods are used.

Usage

toolGetScenarioDefinition(driver = NULL, scen = NULL, aslist = FALSE)

Arguments

driver

NULL or a character vector designating the driver for which information is to be returned. If NULL, information for all drivers is returned. Available drivers are:

  • GDP

  • Population

  • GDPpc

  • Labour

  • Urban

scen

NULL or a character vector designating the scenario for which information is to be returned. If NULL, information for all scenarios is returned.
aslist

TRUE or FALSE (default). If TRUE then the pastData, futureData and harmonization strings are returned as a list.

Value

A tibble with the driver and scenario information.

Examples

toolGetScenarioDefinition()
toolGetScenarioDefinition(driver = "GDP")
toolGetScenarioDefinition(scen = "SSP2EU")
toolGetScenarioDefinition(driver = "Population", scen = "SSPs", aslist = TRUE)

Get monetary unit

Description

toolGetUnitDollar returns unit used for monetary values.

Usage

toolGetUnitDollar(returnOnlyBase = FALSE, inPPP = FALSE)

Arguments

returnOnlyBase

TRUE or FALSE (default). If true only the base year is returned (as string).
inPPP

TRUE or FALSE (default). If TRUE the the string ends in 'Int$PPP', instead of 'Int$MER'.

Value

A string with the monetary unit: 'constant 2017 US$MER'.

Examples

toolGetUnitDollar()
toolGetUnitDollar(inPPP = TRUE)
toolGetUnitDollar(returnOnlyBase = TRUE)

Harmonization tool Past

Description

Like all harmonization tools in mrdrivers, toolHarmonizePast takes two magpie objects, 'past' and 'future', and returns a single magpie object, i.e. the harmonized time-series. In this case, the harmonized time-series is always equal to 'past', in the years of 'past'. After that the harmonized time-series depends on the 'method' argument chosen.

Usage

toolHarmonizePast(past, future, method = "level", yEnd = 2100)

Arguments

past

A magpie object with only one scenario/datatype, i.e. the length of the third dimension should be 1.
future

A magpie object.
method

A string defining the harmonization method:

  • "level": the harmonized time-series is exactly equal to 'future' in the years after the last year of 'past'.

  • "growth": the harmonized time-series follows the same growth rates as 'future', in the years after the last year of 'past'.

  • "transition": the harmonized time-series transitions to 'future' by the year 'yEnd'. After yEnd, the harmonized time-series is equal to 'future'. In the transition phase, a share of the absolute difference between past' and future' in the last year of past' is added to future. This share starts at 1 in the last year of 'past' and decreases linearly to 0 by yEnd.

yEnd

Additional input for "transition" method. Year by which the transition period is completed.

Value

A magpie object with the same dimensions as 'future'.

Dimensions of 'past' and 'future'

If the 'future' object has multiple scenarios/datatypes, i.e. the length of the third dimension is larger than 1, then the a harmonized time-series is created for every scenario/datatype in future. The same 'past' object is used in every case - hence the requirement that 'past' only have one scenario/datatype.