write_hrc2: Creates a hrc file from correspondence table

In InseeFrLab/rtauargus: Using Tau-Argus from R

Creates a hrc file from correspondence table

Description

Creates a .hrc hierarchy from a correspondence table.
Ecrit une hiérarchie .hrc à partir d'une table de correspondance.

Usage

write_hrc2(
  corr_table,
  file_name = NULL,
  sort_table = FALSE,
  rev = FALSE,
  hier_lead_string = getOption("rtauargus.hierleadstring"),
  adjust_unique_roots = TRUE,
  add_char = "ZZZ"
)

Arguments

corr_table	Data frame. Correspondence table, from most aggregated level to most detailed one Table de correspondance, du niveau le plus agrégé au niveau le plus fin
file_name	character string. Name for the output file (with .hrc extension or not). If NULL (default), file_name is set to the same name as the correspondence table Nom du fichier en sortie (avec ou sans l'extension .hrc) ; Si NULL (par défaut), le nom du fichier sera identique au nom de la table de correspondance.
sort_table	boolean. If TRUE, table will be sorted beforehand. (default to FALSE) Si TRUE, la table sera triée avant traitement. (défaut à FALSE)
rev	boolean. If TRUE, column order is reversed. Si TRUE, inverse l'ordre des colonnes.
hier_lead_string	character. (Single) character indicating the hierarchy depth in the .hrc file. By default, the value is set to the current value mentionned in the package options (i.e. "@" at the package startup). Caractère unique repérant le niveau de profondeur dans le .hrc
adjust_unique_roots	boolean. If TRUE (default) will add fictional roots to the correspondence table, by doing so there will be no unique roots in the hrc file. With tabular function, unique roots are not handled by Tau-Argus. Si TRUE la fonction va ajouter des feuilles fictives au fichier .hrc afin qu'il n'y ait plus de feuilles uniques. Les feuilles uniques peuvent générer des problèmes dans l'exécution de Tau-Argus
add_char	character If adjust_unique_roots is TRUE add_char is the string that will be used to create fictional roots, be sure that this string does not create duplicates.The string will be paste at the beginning of a unique root default = "ZZZ" character Si adjust_unique_roots est TRUE add_char est l'élément qui sera utilisé afin de créer des feuilles fictives, il faut être sur que cela ne crée pas de doublons dans la hiérarchie.La chaine de caractère sera ajouté au début d'une feuille unique. Par defaut :"ZZZ"

Details

Creates a .hrc hierarchy file adapted to tau-Argus from a correspondence table fully describing it. By default, lines are sorted alphabetically so as to regroup identical levels.

Ecrit un fichier de hiérarchie .hrc lisible par tau-Argus à partir d'une table de corrrespondance la décrivant complètement. Par défaut, les lignes du tableau seront triées afin de regrouper les niveaux de hiérarchie identiques.

Value

Invisible. Path to the written .hrc file.
Chemin vers le fichier .hrc.

Details about correspondence table & .hrc

Hierarchy files read by tau-Argus are expected to follow a strict pattern. This function mimicks some of its rigidities.

1 Ideal case

Here is how a correspondence table is assumed to look like:

type	details
⁠-------⁠	⁠------⁠
planet	telluric
planet	gasgiant
star	bluestar
star	whitedwarf
star	reddwarf
other	blackhole
other	pulsar

Columns must be ordered from most aggregated to most detailed. If they are in reverse order, you may want to use rev = TRUE. In any other case, please reorder columns by hand.

Hierarchy must be well-nested : fine levels must systematically be nested into unique higher levels. If this is not compatible with your situation, you will have to split it in different hierarchies and insure common cells are correctly protected (seek further documentation or help if needed).

2 Dealing with NAs

The write_hrc2 function has to be preferably used without any NAs in your correspondence table. In presence of NAs, the sort argument has to be to FALSE. Indeed, NAs would be sorted together and, thus, be separated from their expected place in the hierarchy.

Below, we introduce two common cases where correspondence tables could have NAs. The first one is supported by the function, the second one is not.

Please be careful when dealing with NAs and check thoroughly the resulting .hrc file, or consider filling in NAs beforehand.

2.1 Sparse hierarchies
Hierarchy is sparse when NAs are inserted instead of repeating under a given level.

type	details
⁠-------⁠	⁠------⁠
planet	telluric
	gasgiant
star	bluestar
	whitedwarf
	reddwarf
other	blackhole
	pulsar

Such cases still issue a warning for the presence of NAs, but do not pose any problem, if sort=FALSE is set.

2.2 Non-uniform hierarchies
Hierarchies with non-uniform depth happen when some levels are not detailed to the lowest detail, creating NAs.

type	details
⁠-------⁠	⁠------⁠
planet	telluric
planet	gasgiant
star
other	blackhole
other	pulsar

Processing such a file will generate an error with the following messages: Missing values on the last column of the correspondence table is not allowed. If relevant, you could fill in with the value of the previous column

Détails sur les tables de correspondance et le .hrc

Tau-Argus attend des fichiers écrits avec précision. Certaines de ses rigidités sont reproduites par cette fonction.

1 Cas idéal

Voici l'aspect général que devrait avoir une table de correspondance :

type	details
⁠-------⁠	⁠------⁠
planet	telluric
planet	gasgiant
star	bluestar
star	whitedwarf
star	reddwarf
other	blackhole
other	pulsar

Les colonnes doivent être ordonnées du niveau le plus agrégé au plus fin. Si elles sont en sens inverse, l'option rev = TRUE permet de les mettre en ordre. Dans toute autre situation, vous devrez d'abord les ordonner à la main.

La hiérarchie doit être bien emboîtée : un niveau fin doit systématiquement correspondre à un unique niveau agrégé. Si cette exigence n'est pas remplie, il faudra créer plusieurs hiérarchies et faire en sorte que les cellules communes soient correctement protégées (au besoin, consultez la documentation ou chercher de l'aide).

2 Valeurs manquantes

La fonction write_hrc2 doit être utilisée de préférence sans aucun NA dans votre table de correspondance. En présence de NAs, l'argument sort doit être à FALSE. En effet, les NAs seraient triés ensemble et, donc, être séparées de leur place attendue dans la hiérarchie.

Ci-dessous, nous présentons deux cas courants où les tables de correspondance pourraient avoir NAs. Le premier cas est pris en charge par la fonction, le second ne l'est pas.

Soyez prudent lorsque vous manipulez des NA et vérifiez soigneusement le fichier .hrc résultant ou envisagez de remplir les NAs à l'avance.

2.1 Hiérarchies creuses
Une hiérarchie est creuse si des NAs sont insérées au lieu de répéter un niveau donné verticalement.

type	details
⁠-------⁠	⁠------⁠
planet	telluric
	gasgiant
star	bluestar
	whitedwarf
	reddwarf
other	blackhole
	pulsar

De tels cas émettent toujours un avertissement du fait de la présence de NA, mais ne posent aucun problème, si on utilise sort=FALSE.

2.2 Hiérarchies non-uniformes
Les hiérarchies à profondeur non-uniforme correspondent aux cas où certains niveaux ne sont pas détaillés jusqu'au bout, la fin de certaines lignes étant manquante.

type	details
⁠-------⁠	⁠------⁠
planet	telluric
planet	gasgiant
star
other	blackhole
other	pulsar

Le traitement d'un tel fichier générera une erreur avec les messages suivants : Missing values on the last column of the correspondence table is not allowed. If relevant, you could fill in with the value of the previous column

Examples

# 1. Standard example. Table will be written on your working directory.
# Exemple standard. La table sera écrite dans votre répertoire de travail.
astral <- data.frame(
  type      = c("planet", "planet", "star", "star", "star", "other", "other"),
  details   = c(
    "telluric", "gasgiant", "bluestar", "whitedwarf",
    "reddwarf", "blackhole", "pulsar")
)
path <- write_hrc2(astral)
## Not run: read.table(path)
# Note that line order was changed ('other' comes before 'planet'), to no
# consequence whatsoever for Tau-Argus.
# Remarque : l'ordre des lignes a été modifié ('other' arrive avant 'planet'),
# ce qui n'a aucune conséquence pour Tau-Argus.

# Wrong column order:
# Mauvais ordonnancement des colonnes :
astral_inv <- data.frame(
  details = c(
    "telluric", "gasgiant", "bluestar", "whitedwarf",
    "reddwarf", "blackhole", "pulsar"),
    type = c("planet", "planet", "star", "star", "star", "other", "other")
)
path <- write_hrc2(astral_inv)
## Not run: read.table(path)
# Because of the inverted order, everything is written backwards : planet is a
# subtype of gasgiant, etc.
# À cause de l'inversion des colonnes, tout est écrit à l'envers : planet est
# devenu une sous-catégorie de gasgiant, par exemple.

# Correction :
path <- write_hrc2(astral_inv, rev = TRUE)
## Not run: read.table(path)

# 2.1 Sparse case
# Cas creux
astral_sparse <- data.frame(
  type      = c("planet", NA, "star", NA, NA, "other", NA),
  details   = c(
    "telluric", "gasgiant", "bluestar", "whitedwarf",
    "reddwarf", "blackhole", "pulsar")
)
# NAs in general are risky, but, in this case, the function works well.
# Les valeurs manquantes causent un risque, mais, dans ce genre de cas,
# la fonction a le comportement attendu.
path <- write_hrc2(astral_sparse)
## Not run: read.table(path)

# 2.2 Non-uniform depth
# Hiérarchie non-uniforme
astral_nu <- data.frame(
  type      = c("planet", "planet", "star", "other", "other"),
  details  = c("telluric", "gasgiant", NA, "blackhole", "pulsar")
)
# The following code will generate an error
# (see section Details about correspondence table & .hrc)
## Not run: 
path <- write_hrc2(astral_nu)

## End(Not run)
#To fix the issue, you have to fill in the NAs beforehand.

astral_nu_fill <- data.frame(
  type      = c("planet", "planet", "star", "other", "other"),
  details  = c("telluric", "gasgiant", "star", "blackhole", "pulsar")
)
# The following code will work
path <- write_hrc2(astral_nu_fill)
## Not run: read.table(path)

InseeFrLab/rtauargus documentation built on Feb. 25, 2025, 6:32 a.m.