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.
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)
if (FALSE) 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)
#> Warning: There are duplicates in the expectedly most detailed level
#> (last column). Please be sure columns are rightfully ordered.
if (FALSE) 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)
if (FALSE) 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)
#> Warning: Missing values in correspondence table will be filled in (see documentation).
#> If unintended, this can cause errors when using the .hrc file with tau-Argus.
if (FALSE) 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)
if (FALSE) {
path <- write_hrc2(astral_nu)
}
#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)
if (FALSE) read.table(path)