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: 7.1.0
Built: 2025-02-20 14:22:17 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.

The scenario argument is used to designate the scenario(s) to be returned. Currently available GDP scenarios are: SSPs, SSP1, SSP2, SSP3, SSP4, SSP5, SDPs, ISIMIP, SSP2IndiaDEAs, SSP2IndiaMedium, SSP2IndiaHigh. See the vignette: vignette("scenarios") and/or toolGetScenarioDefinition() for more information, scenario options, definitions and references.

Usage

calcGDP(
  scenario,
  unit = toolGetUnitDollar(inPPP = TRUE),
  average2020 = TRUE,
  ...
)

calcGDPpc(
  scenario,
  unit = toolGetUnitDollar(inPPP = TRUE),
  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

extension2150

A string specifying if/how the scenarios should be extended until 2150. Can be either:

  • "bezier" (default): A bezier curve extension that leads to a smooth flattening of the scenario: the slope in the last year of the scenario is halved by 2150. Currently only works for scenarios with 2100 as their last year.

  • "constant": The last value of the scenarios is taken as constant until 2150.

  • "none": No extension.

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 all SSP scenarios
calcOutput("GDP", scenario = "SSPs")

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

# Return the SSP and SDP GDPpc scenarios
calcOutput("GDP", scenario = c("SSPs", "SDPs"))

## 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.

The scenario argument is used to designate the scenario(s) to be returned. Currently available Population scenarios are: SSPs, SSP1, SSP2, SSP3, SSP4, SSP5, SDPs, ISIMIP, SSP2IndiaDEAs, SSP2IndiaMedium, SSP2IndiaHigh. See the vignette: vignette("scenarios") and/or toolGetScenarioDefinition() for more information, scenario options, definitions and references.

Usage

calcPopulation(scenario, ...)

calcLabour(scenario, ...)

calcUrban(scenario, 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

extension2150

A string specifying if/how the scenarios should be extended until 2150. Can be either:

  • "bezier" (default): A bezier curve extension that leads to a smooth flattening of the scenario: the slope in the last year of the scenario is halved by 2150. Currently only works for scenarios with 2100 as their last year.

  • "constant": The last value of the scenarios is taken as constant until 2150.

  • "none": No extension.

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 all SSP scenarios
calcOutput("Population", scenario = "SSPs")

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

# Return the SSP and SDP Labour scenarios
calcOutput("Population", scenario = c("SSPs", "SDPs"))

## End(Not run)
## Not run: 
calcOutput("Labour", scenario = "SSPs")

## End(Not run)
## Not run: 
calcOutput("Urban", scenario = "SSPs")

## End(Not run)

Read-in data from the International Monetary Fund's (IMF) Economic Outlook

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 data from the James et al. (2012) 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.

Usage

downloadJames()

readJames(subtype)

convertJames(x, subtype)

Arguments

subtype

String indicating the data series
x

MAgPIE object returned by readJames

Details

The data is in Annex 3.

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("James", subtype = "gdppc")
# Or more explicitly:
readSource("James", subtype = "WB_USD05_PPP_pc")

## 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 dataset that gets data from a variety of sources (e.g. CIA World Factbook, Insee, BEA, PRISM, and Woldometers).

Usage

downloadMissingIslands()

readMissingIslands(subtype)

convertMissingIslands(x, subtype)

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")

## End(Not run)

Read-in data from the World Bank's Population Estimates And Projections (PEAP)

Description

Read-in an xlsx file from the World Bank's Population Estimates And Projections (PEAP) The PEAP data cannot 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-in data from the United Nations Population Division (UN_PopDiv) database

Description

Read-in UN population data.

Usage

downloadUN_PopDiv()

readUN_PopDiv(subtype, subset = "estimates")

convertUN_PopDiv(x)

Arguments

subtype

Either "pop" or "lab".
subset

Either "estimates" or "medium".
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-in data from the World Bank's World Development Indicator (WDI) database.

Description

Download, read-in 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:

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

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

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

  • "gdp" or "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 is not 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 = "pop")

## End(Not run)

Read-in data from India's Department of Economic Affairs (DEA)

Description

Read-in DEA data as magclass object

Usage

readIndiaDEA()

convertIndiaDEA(x, subtype = "all", subset = c("baseline", "optimistic"))

downloadIndiaDEA()

Arguments

x

MAgPIE object returned from readIndiaDEA
subtype

A string, either "all", "gdppc", "pop"
subset

A vector of strings designating the scenarios. Defaults to c("baseline", "optimistic").

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("IndiaDEA", subtype = "gdppc")

## End(Not run)

Read-in data from the Shared Socioeconomic Pathways (SSP)

Description

Read-in SSP data and store as magclass object. Filter for subtype and subset in the convert function to use common read cache (speeds up the computations).

Usage

readSSP()

convertSSP(
  x,
  subtype = "all",
  subset = c("SSP1", "SSP2", "SSP3", "SSP4", "SSP5")
)

downloadSSP()

Arguments

x

MAgPIE object returned from readSSP
subtype

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

A vector of strings designating the scenarios. Defaults to c("SSP1", "SSP2", "SSP3", "SSP4", "SSP5"). "Historical Reference" is also available as a scenario.

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,

  • substituting NAs, see the "substituteNAsWith" argument,

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

  • 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.

Examples

## Not run: 
toolGeneralConvert(x)

## End(Not run)

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,
  getGroupShortcuts = 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.
getGroupShortcuts

TRUE or FALSE (default). If TRUE then return list of scenario group shortcuts.

Value

A tibble with the driver and scenario information.

Examples

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

Get default monetary unit used in the rd3mod input data pipeline

Description

toolGetUnitDollar returns default unit used for monetary values. Currently: constant 2017 US$MER.

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, currently constant 2017 US$MER.

Examples

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

Tool to harmonize future data to past data, without modifying the future data

Description

Like all harmonization tools in mrdrivers, toolHarmonizeFuture 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 'future', in the years of 'future'. After that the harmonized time-series depends on the 'method' argument chosen.

Usage

toolHarmonizeFuture(past, future, method = "level")

Arguments

past

A magpie object.
future

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

A string defining the harmonization method:

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

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

Value

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

Dimensions of 'past' and 'future'

If the 'past' 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 past. The same 'future' object is used in every case - hence the requirement that 'future' only have one scenario/datatype.

Examples

## Not run: 
toolHarmonizePast(past, future)

## End(Not run)

Tool to harmonize future data to past data, without modifying the past data

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.

Examples

## Not run: 
toolHarmonizePast(past, future)

## End(Not run)

Replace group shortcuts with individual scenarios

Description

Some scenarios can be referred to as a group, e.g. as "SSPs". In some cases however the individual scenarios of that group are wanted explicitly. This function replaces the group-shortcuts with the names of the scenarios in that group.

Current available groups are: SSPs, SSP2IndiaDEAs

Usage

toolReplaceShortcuts(scenario)

Arguments

scenario

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

Value

The modified scenario argument, with the group-names replaced.

See Also

toolGetScenarioDefinition() for scenario options and definitions. Set getGroupShortcuts to TRUE to return the available shortcuts: toolGetScenarioDefinition(getGroupShortcuts = TRUE).

Examples

toolReplaceShortcuts("SSPs")