% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/wrangle_data.R
\name{wrangle_gho_rural_urban_data}
\alias{wrangle_gho_rural_urban_data}
\title{Wrangle GHO data with TOTL/RUR/URB dimensions}
\usage{
wrangle_gho_rural_urban_data(
  df,
  source = NULL,
  type = NULL,
  ind = NULL,
  upload_date = NULL,
  scenario = NULL,
  id_cols = c("SpatialDim", "TimeDim"),
  names_from = "Dim1",
  values_from = c("NumericValue", "High", "Low", "DataSourceDim", "Comments", "Date")
)
}
\arguments{
\item{df}{A data frame in GHO format, returned from [ghost:gho_data()]{https://gpw13.github.io/ghost/reference/gho_data.html}.}

\item{source}{Character string of source to be provided to the data frame.
If \code{NULL}, the source column is generated from the GHO's \code{DataSourceDim} column.
If not \code{NULL}, it overrides the source provided by the GHO.}

\item{type}{Character string of type to be provided to the data frame. If
\code{NULL}, the type column is filled with \code{NA_character_}.}

\item{ind}{Character string of the indicator name to be provided to the data frame.
This is a required argument and will raise an error if not provided.
If only a RUR or URB values is available, the indicator name has \verb{_rural} or \verb{_urban}
appended to it in the output data frame.}

\item{upload_date}{Character string indicating on which day the data was last
updated on GHO}

\item{scenario}{(Character) string of scenario to be provided to the data frame.
If \code{NULL}, the scenario is set to \code{NA_character}.}

\item{id_cols}{Character vector of the columns that are the same regardless of
the TOTL/RUR/URB dimension. Used as the argument of the same name in \code{pivot_wider}.}

\item{names_from, values_from}{A pair of character vectors used as the arguments
of the same name in \code{pivot_wider}.}
}
\value{
A data frame
}
\description{
#'\code{wrangle_gho_rural_urban_data()} exapnds the functionality of
\code{\link[=wrangle_gho_data]{wrangle_gho_data()}} by also handling indicators which have
TOTL/RUR/URB values in the \code{Dim1} column of the GHO data response, by first pivoting
the data frame and then selecting only the total, rural, and urban values for a given
(iso3, year) combination (in that order of preference).
}
\details{
It also automatically filters 'mixed' time series â€” i.e., instances where the time series
for a given country contains a combination of TOTL, RUR, and URB values by
keeping the time series associated only with the most commonly occuring of these
options. For example, a time series with URB data from 2000 to 2015 and TOTL data
from 2016 to 2020 will be cutoff at 2015, so that only the URB data is kept.
}
\section{TODO}{

\itemize{
\item Convert to more generic \code{unspool_gho_dim} function which can work with any
other \code{DimType}, and not just TOTL/RUR/URB.
\item Re-write to make it work better with \code{wrangle_gho_data} to avoid the significant amount
of redundant logic. This means that, eventually, users may do
\code{gho_data(.) \%>\% unspool_gho_dim(.) \%>\% wrangle_gho_data(.)}
}
}

\seealso{
Wrangle data functions
\code{\link{add_missing_xmart_rows}()},
\code{\link{get_data_lake_name}()},
\code{\link{get_whdh_path}()},
\code{\link{has_xmart_cols}()},
\code{\link{save_gho_backup_to_whdh}()},
\code{\link{save_wrangled_output}()},
\code{\link{wrangle_gho_data}()},
\code{\link{wrangle_unsd_data}()},
\code{\link{xmart_col_types}()},
\code{\link{xmart_cols}()}
}
\concept{whdh}
