Skip to contents

Expand a reference data.frame containing N hierarchical columns to an N-level reference data.frame

Source: R/ref_expand.R
ref_expand.Rd

For example, a municipality-level reference data.frame might contain three hierarchical columns — country, state, and municipality — but nonetheless only reflect the municipality level in that all rows represent a unique municipality. The lower-resolution levels (state, country) are implied but not explicitly represented as unique rows. If we wish to allow matches to the lower-resolution levels, we need additional rows specific to these levels.

This function takes a reference data.frame with N hierarchical columns, and adds rows for each unique combination of each level that is not currently explicitly represented.

Usage

ref_expand(ref, pattern, by, lowest_level = 1L)

Arguments

ref

data.frame containing hierarchical columns with reference data

pattern

regex pattern to match the names of the hierarchical columns in ref (supply either pattern or by)

by

vector giving the names of the hierarchical columns in ref (supply either pattern or by)

lowest_level

integer representing the lowest-resolution level (defaults to 1)

Value

A data.frame created by expanding ref to all implied hierarchical levels

Examples

# subset example reference df to the admin-2 level
ne_ref_adm2 <- ne_ref[!is.na(ne_ref$adm2),]

# expand back to all levels
ref_expand(ne_ref_adm2, pattern = "adm", lowest_level = 0)
#>    level adm0         adm1         adm2
#> 1      0  CAN         <NA>         <NA>
#> 2      0  USA         <NA>         <NA>
#> 3      1  CAN      Ontario         <NA>
#> 4      1  USA   New Jersey         <NA>
#> 5      1  USA     New York         <NA>
#> 6      1  USA Pennsylvania         <NA>
#> 7      2  CAN      Ontario       Durham
#> 8      2  CAN      Ontario       Halton
#> 9      2  CAN      Ontario         Peel
#> 10     2  CAN      Ontario      Toronto
#> 11     2  CAN      Ontario         York
#> 12     2  USA   New Jersey       Bergen
#> 13     2  USA   New Jersey        Essex
#> 14     2  USA   New Jersey       Hudson
#> 15     2  USA   New Jersey    Middlesex
#> 16     2  USA   New Jersey     Monmouth
#> 17     2  USA     New York    Jefferson
#> 18     2  USA     New York        Bronx
#> 19     2  USA     New York        Kings
#> 20     2  USA     New York       Nassau
#> 21     2  USA     New York     New York
#> 22     2  USA     New York       Queens
#> 23     2  USA     New York      Suffolk
#> 24     2  USA Pennsylvania    Allegheny
#> 25     2  USA Pennsylvania        Bucks
#> 26     2  USA Pennsylvania      Chester
#> 27     2  USA Pennsylvania     Delaware
#> 28     2  USA Pennsylvania    Jefferson
#> 29     2  USA Pennsylvania    Lancaster
#> 30     2  USA Pennsylvania Philadelphia
#> 31     2  USA Pennsylvania         York