Add nodes to an existing hierarchy

Description

This function allows to add nodes (levels) to an existing nested hierarchy.

Usage

hier_add(tree, root, nodes)

Arguments

Examples

h <- hier_create(root = "Total",  nodes = LETTERS[1:3])
h <- hier_add(h, root = "A", nodes = c("a1", "a5"))
hier_display(h)

Create/Modify hierarchies interactively

Description

This function starts the interactive shiny-app to (optionally) create and/or modify a nested hierarchy. It is possible to supply a character vector from which the hierarchy can be interactively built. Once this has been done, it is possible to modify and export the resulting hierarchy.

Usage

hier_app(x = hier_create(), ...)

Arguments

Details

Another option is to supply an already existing hierarchy object. In this case, it is possible to modify the existing object in the app.

Value

The app can return a hierarchy object (either a data.frame or a tree-based object)

Examples

## Not run: 
# start with an empty hierarchy
res <- hier_app()

# start with a character vector that is used to
build the hierarchy
codes <- c("11", "12", "21", "22", "23", "31", "32")
res <- hier_app(codes); print(res)

## End(Not run)

Default-Codes

Description

hier_codes() returns the standardized codes for the nodes of a tree.

Usage

hier_codes(tree)

Arguments

Value

a named character vector with names being the node-names and the values the standardized codes

Examples

h <- hier_create(root = "Total", nodes = LETTERS[1:3])
h <- hier_add(h, root = "A", nodes = c("a1", "a5"))
hier_codes(h)

Compute a nested hierarchy

Description

This function allows to compute a nested hierarchy from an character vector or a (named) list.

Usage

hier_compute(inp, dim_spec = NULL, root = NULL, method = "len", as = "network")

Arguments

Value

a hierarchical data structure depending on choice of argument as

Examples

## Example Regional Codes (NUTS)
# digits 1-2 (len=2, endpos=2) --> level 1
# digit 3 (len=1, endpos=3) --> level 2
# digits 4-5 (len=2, endpos=5) -> level 3

# all strings have equal length but total is not encoded in these values
geo_m <- c(
  "01051", "01053", "01054", "01055",
  "01056", "01057", "01058", "01059", "01060",
  "01061", "01062",
  "02000",
  "03151", "03152", "03153", "03154", "03155", "03156", "03157", "03158",
  "03251", "03252", "03254", "03255", "03256", "03257",
  "03351", "03352", "03353", "03354", "03355",
  "03356", "03357", "03358", "03359",
  "03360", "03361",
  "03451", "03452", "03453", "03454", "03455", "03456",
  "10155")

a <- hier_compute(
  inp = geo_m,
  dim_spec = c(2, 3, 5),
  root = "Tot",
  method = "endpos"
)
b <- hier_compute(
  inp = geo_m,
  dim_spec = c(2, 1, 2),
  root = "Tot",
  method = "len"
)
identical(
  hier_convert(a, as = "df"),
  hier_convert(b, as = "df")
)

# total is contained in the first 3 positions of the input values
# --> we need to set name of the overall total (argument "root")
# to NULL (the default)
geo_m_with_tot <- paste0("Tot", geo_m)
a <- hier_compute(
  inp = geo_m_with_tot,
  dim_spec = c(3, 2, 1, 2),
  method = "len"
)
b <- hier_compute(
  inp = geo_m_with_tot,
  dim_spec = c(3, 5, 6, 8),
  method = "endpos"
)
identical(a, b)

# example where inputs have unequal length
# the overall total is not included in input vector
yae_h <- c(
  "1.1.1.", "1.1.2.",
  "1.2.1.", "1.2.2.", "1.2.3.", "1.2.4.", "1.2.5.", "1.3.1.",
  "1.3.2.", "1.3.3.", "1.3.4.", "1.3.5.",
  "1.4.1.", "1.4.2.", "1.4.3.", "1.4.4.", "1.4.5.",
  "1.5.", "1.6.", "1.7.", "1.8.", "1.9.", "2.", "3.")

a <- hier_compute(
  inp = yae_h,
  dim_spec = c(2, 4, 6),
  root = "Tot",
  method = "endpos"
)
b <- hier_compute(
  inp = yae_h,
  dim_spec = c(2, 2, 2),
  root = "Tot",
  method = "len"
)
identical(
  hier_convert(a, as = "df"),
  hier_convert(b, as = "df")
)

# Same example, but overall total is contained in the first 3 positions
# of the input values --> argument "root" needs to be
# set to NULL (the default)
yae_h_with_tot <- paste0("Tot", yae_h)
a <- hier_compute(
  inp = yae_h_with_tot,
  dim_spec = c(3, 2, 2, 2),
  method = "len",
)
b <- hier_compute(
  inp = yae_h_with_tot,
  dim_spec = c(3, 5, 7, 9),
  method = "endpos"
)
identical(a, b)

# An example using a list as input (same as above)
# Hierarchy: digits 1-2 (nuts1), digit 3 (nut2), digits 4-5 (nuts3)
# The order of the list-elements is not important but the
# names of input-list correspond to (subtotal/level) names
geo_ll <- list()
geo_ll[["Total"]] <- c("01", "02", "03", "10")
geo_ll[["010"]]   <- c(
  "01051", "01053", "01054", "01055",
  "01056", "01057", "01058", "01059",
  "01060", "01061", "01062"
)
geo_ll[["031"]]   <- c(
  "03151", "03152", "03153", "03154",
  "03155", "03156", "03157", "03158"
)
geo_ll[["032"]]   <- c(
  "03251", "03252", "03254",
  "03255", "03256", "03257"
)
geo_ll[["033"]]   <- c(
  "03351", "03352", "03353", "03354", "03355",
  "03356", "03357", "03358", "03359",
  "03360", "03361"
)
geo_ll[["034"]]   <- c(
  "03451", "03452", "03453",
  "03454", "03455","03456"
)
geo_ll[["01"]]    <- "010"
geo_ll[["02"]]    <- "020"
geo_ll[["020"]]   <- "02000"
geo_ll[["03"]]    <- c("031", "032", "033", "034")
geo_ll[["10"]]    <- "101"
geo_ll[["101"]]   <- "10155"

d <- hier_compute(
  inp = geo_ll,
  root = "Total",
  method = "list"
); d

## Reproduce example from above with input defined as named list
yae_ll <- list()
yae_ll[["Total"]] <- c("1.", "2.", "3.")
yae_ll[["1."]] <- paste0("1.", 1:9, ".")
yae_ll[["1.1."]] <- paste0("1.1.", 1:2, ".")
yae_ll[["1.2."]] <- paste0("1.2.", 1:5, ".")
yae_ll[["1.3."]] <- paste0("1.3.", 1:5, ".")
yae_ll[["1.4."]] <- paste0("1.4.", 1:6, ".")

# return result as data.frame
d <- hier_compute(
  inp = yae_ll,
  root = "Total",
  method = "list",
  as = "df"
); d

Converts hierarchies into different formats

Description

This functions allows to convert nested hierarchies into other data structures.

Usage

hier_convert(tree, as = "df")

Arguments

Examples

h <- hier_create(root = "Total", nodes = LETTERS[1:2])
h <- hier_add(h, root = "A", nodes = c("a1", "a2"))
h <- hier_add(h, root = "B", nodes = c("b1", "b2"))
h <- hier_add(h, root = "b1", nodes = "b1a")
hier_display(h)

# required code to build the hierarchy
hier_convert(h, as = "code")

# data.frame
hier_convert(h, as = "df")

Create a hierarchy

Description

This functions allows to generate a hierarchical data structure that can be used in other packages such as cellKey or sdcTable.

Usage

hier_create(root = "Total", nodes = NULL)

Arguments

Value

a (nested) sdc hierarchy tree

See Also

hier_add hier_delete hier_rename hier_export hier_convert hier_app hier_info

Examples

# without nodes
h <- hier_create(root = "tot")
hier_display(h)

# with nodes
h <- hier_create(root = "tot", nodes = LETTERS[1:5])
hier_display(h)

Delete nodes from an existing hierarchy

Description

This function allows to delete nodes (levels) from an existing nested hierarchy.

Usage

hier_delete(tree, nodes)

Arguments

Examples

h <- hier_create(root = "Total", nodes = LETTERS[1:2])
h <- hier_add(h, root = "A", nodes = c("a1", "a2"))
h <- hier_add(h, root = "B", nodes = c("b1", "b2"))
h <- hier_add(h, root = "b1", nodes = "b1a")
hier_display(h)

h <- hier_delete(h, nodes = c("a1", "b1a"))
hier_display(h)

Displays the hierarchy

Description

This function shows the entire hierarchy in a nice way.

Usage

hier_display(x, root = NULL)

Arguments

Value

NULL; the tree is printed to the prompt

Examples

h <- hier_create(root = "Total", nodes = LETTERS[1:2])
h <- hier_add(h, root = "A", nodes = c("a1", "a2"))

# display the entire tree
hier_display(h)

# display only a subtree
hier_display(h, root = "A")

Export a hierarchy into a file

Description

This function allows to write nested hierarchies into files on your disk.

Usage

hier_export(tree, as = "df", path, verbose = FALSE)

Arguments

Examples

h <- hier_create(root = "Total", nodes = LETTERS[1:2])
h <- hier_add(h, root = "A", nodes = c("a1", "a2"))
h <- hier_add(h, root = "B", nodes = c("b1", "b2"))
h <- hier_add(h, root = "b1", nodes = "b1a")
hier_display(h)

# export as input for tauArgus
hier_export(h, as = "argus", path = file.path(tempdir(), "h.hrc"))

Compute a grid given different hierarchies

Description

This function returns a data.table containing all possible combinations of codes from at least one hierarchy object. This is useful to compute a "complete" table from several hierarchies.

Usage

hier_grid(..., add_dups = TRUE, add_levs = FALSE, add_default_codes = FALSE)

Arguments

Value

a data.table featuring a column for each hierarchy object specified in argument .... These columns are labeled ⁠v{n}⁠. If add_levs is TRUE, for each hierarchy provided, an additional column labeled ⁠levs_v{n}⁠ is appended to the output. Its values define the hierarchy level of the corresponding code given in ⁠v{n}⁠ in the same row. If add_default_codes is TRUE, for each hierarchy provided an additional column ⁠default_v{n}⁠ is provided

Examples

# define some hierarchies with some "duplicates" or "bogus" codes
h1 <- hier_create("Total", nodes = LETTERS[1:3])
h1 <- hier_add(h1, root = "A", node = "a1")
h1 <- hier_add(h1, root = "a1", node = "aa1")

h2 <- hier_create("Total", letters[1:5])
h2 <- hier_add(h2, root = "b", node = "b1")
h2 <- hier_add(h2, root = "d", node = "d1")

# with all codes, also "bogus" codes
hier_grid(h1, h2)

# only the required codes to build the complete hierarchy (no bogus codes)
hier_grid(h1, h2, add_dups = FALSE)

# also contain columns specifying the hierarchy level
hier_grid(h1, h2, add_dups = FALSE, add_levs = TRUE)

Imports a nested data structure

Description

This function creates a nested sdc hierarchy from various input structures.

Usage

hier_import(inp, from = "json", root = NULL, keep_order = FALSE)

Arguments

Value

a (nested) hierarchy

See Also

hier_to_tree()

Examples

h <- hier_create(root = "Total", nodes = LETTERS[1:2])
h <- hier_add(h, root = "A", nodes = c("a1", "a2"))
h <- hier_add(h, root = "B", nodes = c("b1", "b2"))
h <- hier_add(h, root = "b1", nodes = "b1a")
hier_display(h)

df <- hier_convert(h, as = "df")
hier_display(df)

h2 <- hier_import(df, from = "df")
hier_display(h2)

# check order
df <- data.frame(
  level = c("@", "@@", "@@"),
  name = c("T", "m", "f")
)
hier_display(hier_import(df, from = "df")) # automatically sorted (T, f, m)
hier_display(hier_import(df, from = "df", keep_order = TRUE)) # original order (T, m, f)

Information about hierarchy-codes

Description

hier_info() computes various information about hierarchy codes or the (nested) hierarchy.

Usage

hier_info(tree, nodes = NULL)

Arguments

Value

a list with information about the required nodes. If nodes is NULL (the default), the information is computed for all available nodes of the hierarchy. The following properties are computed:

• exists: (logical) does the node exist

• name: (character) node name

• is_rootnode: (logical) is the node the overall root of the tree?

• level: (numeric) what is the level of the node

• is_leaf: (logical) is the node a leaf?

• siblings: (character) what are siblings of this node?

• contributing_codes: (character) which codes are contributing to this node? If none (it is a leaf), NA is returned

• children: (character) the names of the children of the node. If it has none (it is a leaf), NA is returned

• is_bogus: (logical) is it a bogus code (i. e the only children of a leaf?)

Examples

h <- hier_create(root = "Total",  nodes = LETTERS[1:3])
h <- hier_add(h, root = "A", nodes = c("a1", "a5"))
hier_display(h)

# about a specific node
hier_info(h, nodes = "a1")

# about all nodes
hier_info(h)

Match default and original node labels

Description

This function returns a data.table that maps original and default codes.

Usage

hier_match(tree, nodes = NULL, inputs = "orig")

Arguments

Value

a data.table with the following columns:

• "orig": the original node names

• '"default": the standardized names

• "is_bogus": TRUE if the code is a "bogus" (duplicated) node.

Examples

h <- hier_create(root = "Tot", nodes = letters[1:5])
h <- hier_add(h, root = "a", nodes = "a0")
h2 <- hier_convert(tree = h, as = "dt")
hier_match(tree = h, nodes = c("a", "b"), inputs = "orig")
hier_match(tree = h2, nodes = c("01", "02"), inputs = "default")

Extract name of nodes (levels)

Description

This function allows to extract the all the names of the nodes including all (sub)-nodes and leaves in the given hierarchy.

Usage

hier_nodenames(tree, root = NULL)

Arguments

Examples

h <- hier_create(root = "Total",  nodes = LETTERS[1:3])
h <- hier_add(h, root = "A", nodes = c("a1", "a5"))
hier_nodenames(h)

Rename nodes in an existing hierarchy

Description

This function allows to rename one or more node(s) (levels) in an existing nested hierarchy.

Usage

hier_rename(tree, nodes)

Arguments

Examples

h <- hier_create(root = "Total",  nodes = LETTERS[1:3])
h <- hier_add(h, root = "A", nodes = c("a1", "a5"))
hier_display(h)

h <- hier_rename(h, nodes = c("a1" = "x1", "A" = "X"))
hier_display(h)

Convert a nested hierarchy into the default format

Description

This function returns a tree in default format (as for example created using hier_create()) for objects created using hier_convert().

Usage

hier_to_tree(inp)

Arguments

Value

a nested hierarchy with default format

Examples

h <- hier_create(root = "Total",  nodes = LETTERS[1:3])
h <- hier_add(h, root = "A", nodes = c("a1", "a5"))
sdc <- hier_convert(h, as = "sdc")
hier_display(h)
hier_display(hier_to_tree(h))
hier_display(hier_to_tree(sdc))

Show the package vignette

Description

This function opens the introductionary package vignette and opens it in a new browser tab/window.

Usage

hier_vignette()

Value

a browser windows/tab with showing the vignette

Examples

## Not run: 
hier_vignette()

## End(Not run)