Introduction

Le package {serad} a pour objectif de faciliter la rédaction automatisée de textes de conjoncture à partir de séries statistiques. Il fournit des fonctions pour :

calculer des évolutions en pourcentage ou en niveau ;
formater proprement les valeurs numériques ;
choisir une formulation nominale ou verbale ;
tenir compte, si nécessaire, de l’accélération ;
produire des sorties en français ou en anglais.

L’idée générale est de séparer :

la logique économique (hausse, baisse, stabilité, accélération, ralentissement) ;
la mise en forme (pourcentage, points, niveaux, dates) ;
la rédaction proprement dite.

library(serad)

Initialisation et choix de la langue

Par défaut, le package est chargé en français. Il est toutefois possible de basculer en anglais.

get_serad_language()
#> [1] "fr"

Pour passer en anglais :

set_serad_language("en")

Pour revenir au français :

set_serad_language("fr")

On peut également choisir la langue avant le chargement du package :

options(serad.lang = "en")
library(serad)

Calcul des évolutions

La fonction g() calcule l’évolution relative entre deux niveaux selon la formule suivante :

\[ \frac{x_1-x_2}{x_2}\times 100 \]

Par convention :

x1 correspond au niveau le plus récent ;
x2 correspond au niveau le plus ancien.

Ainsi, le passage de 100 à 105 représente une hausse de 5 %, tandis que le passage de 100 à 95 représente une baisse de 5 % :

g(105, 100)
#> [1] 5
g(95, 100)
#> [1] -5

Formater les résultats

Pourcentages

format_taux() formate une valeur en pourcentage. L’argument signe permet d’afficher une variation avec son signe.

format_taux(5.3654, signe = FALSE)  # Part : 5,4 %
#> [1] "5,4 %"
format_taux(5.3654)                 # Hausse : +5,4 %
#> [1] "+5,4 %"
format_taux(-5.3654)                # Baisse : -5,4 %
#> [1] "-5,4 %"

Variations en points

format_pts() permet de formater une variation en points.

format_pts(5.3654)
#> [1] "+5,4 points"
format_pts(-1.2)
#> [1] "-1,2 point"
format_pts(1.3654, signe = FALSE)
#> [1] "1,4 point"
format_pts(5.3654, abrev = TRUE)
#> [1] "+5,4 pts"

Niveaux et différences de niveau

format_niv() formate un niveau. Pour afficher une différence de niveau avec son signe, utilisez signe = TRUE.

format_niv(365484)
#> [1] "365 500"
format_niv(365484, signe = TRUE)
#> [1] "+365 500"
format_niv(300000 - 365484, signe = TRUE)
#> [1] "-65 500"

Décrire une évolution simple

Pour nuancer l’ampleur d’une évolution, deux fonctions sont utilisées :

g_nom(x1, x2) — et sa variante g_nom_evo(g) — pour une formulation nominale ;
g_verbe(x1, x2) — et sa variante g_verbe_evo(g) — pour une formulation verbale.

Formulation nominale

g_nom(1.04, 1)
#> [1] "une hausse"
g_nom(1.001, 1)
#> [1] "une stabilité"
g_nom(0.95, 1)
#> [1] "une baisse"

On peut aussi travailler directement à partir d’un taux déjà calculé :

g_nom_evo(4)
#> [1] "une hausse"
g_nom_evo(0)
#> [1] "une stabilité"
g_nom_evo(-4)
#> [1] "une baisse"

Avec titre = TRUE, l’article initial est supprimé et la première lettre est mise en majuscule.

g_nom_evo(4, titre = TRUE)
#> [1] "Hausse"
g_nom_evo(-4, titre = TRUE)
#> [1] "Baisse"

Formulation verbale

g_verbe(1.10, 1)
#> [1] "augmente fortement de 10,0 %"
g_verbe(1.003, 1)
#> [1] "augmente légèrement de 0,3 %"
g_verbe(0.96, 1)
#> [1] "baisse de 4,0 %"

Directement à partir d’un taux :

g_verbe_evo(10)
#> [1] "augmente fortement de 10,0 %"
g_verbe_evo(0)
#> [1] "est stable"
g_verbe_evo(-4)
#> [1] "baisse de 4,0 %"

En cas de stabilité, il est possible de conserver ou non la valeur.

g_verbe_evo(-0.1)
#> [1] "est stable"
g_verbe_evo(-0.1, stable_sans_valeur = FALSE)
#> [1] "est stable à -0,1 %"

Comparaisons qualitatives

Le package propose deux fonctions générales :

comparaison() compare deux niveaux à partir de leur écart absolu ;
comparaison_taux() les compare à partir de leur taux d’évolution.

Les formulations renvoyées en cas de hausse, de stabilité ou de baisse sont personnalisables.

Comparaison de niveaux

comparaison() permet de choisir une formulation selon l’évolution entre deux niveaux. Voici trois usages possibles :

# Situer un niveau
comparaison(104, 100, 
            "au-dessus de", 
            "au même niveau que",
            "en dessous de", 
            seuil = 0)
#> [1] "au-dessus de"

# Qualifier une tendance
comparaison(120, 100, 
            "à la hausse", 
            "stable",
            "à la baisse", 
            seuil = 0.1)
#> [1] "à la hausse"

# Comparer des quantités
comparaison(104, 100, 
            "davantage", 
            "autant",
            "moins", 
            seuil = 0)
#> [1] "davantage"

Comparaison de taux avec accord grammatical

L’argument alt permet de choisir une autre formulation, par exemple pour accorder un verbe :

comparaison_taux(
  1.04, 1,
  hausse_defaut = "excèdent",
  egalite_defaut = "sont au niveau de",
  baisse_defaut = "sont en dessous de",
  alt = TRUE,
  hausse_alt = "excède",
  egalite_alt = "est au niveau de",
  baisse_alt = "est en dessous de"
)
#> [1] "excède"

Tenir compte de l’accélération

Lorsque deux évolutions successives sont disponibles, {serad} permet de qualifier non seulement le sens de l’évolution, mais aussi son rythme.

Pour cela, on dispose de :

gETa_nom() et gETa_nom_taux() pour une formulation nominale ;
gETa_verbe() et gETa_verbe_taux() pour une formulation verbale.

Exemple nominal

gETa_nom(1.1, 1, 0.99)
#> [1] "une forte hausse"
gETa_nom(0.96, 1, 1.01)
#> [1] "un nouveau recul"
gETa_nom(1.00049, 1, 0.9996)
#> [1] "une stabilité"

Exemple verbal

gETa_verbe(1.1, 1, 0.99)
#> [1] "augmente fortement"
gETa_verbe(0.96, 1, 1.01)
#> [1] "baisse plus fortement qu'au mois précédent"
gETa_verbe(1.003, 1, 0.99, sing = FALSE)
#> [1] "ralentissent"

Utilisation d’une variante alternative

Certaines fonctions permettent, via l’argument alea, d’utiliser une formulation alternative.

alea = 0 : formulation principale uniquement ;
alea = 1 : formulation alternative systématique ;
entre 0 et 1 : tirage aléatoire.

gETa_verbe_taux(10, 1, alea = 1)
#> [1] "augmente plus vite"
gETa_nom_taux(10, 1, alea = 1)
#> [1] "un regain de dynamisme"

Dates, mois et trimestres

libelle_periode() produit le libellé d’un mois ou d’un trimestre. L’argument decalage permet d’obtenir une période précédente ou suivante.

Mois

libelle_periode(3, 2023, periode = "mois")
#> [1] "mars 2023"
libelle_periode(12, 2023, periode = "mois", decalage = 1)
#> [1] "janvier 2024"
libelle_periode(1, 2023, periode = "mois", decalage = -1)
#> [1] "décembre 2022"

Trimestres

libelle_periode(3, 2023, periode = "trimestre")
#> [1] "troisième trimestre 2023"
libelle_periode(3, 2023, periode = "trimestre", format = "chiffres")
#> [1] "3^e^ trimestre 2023"
libelle_periode(4, 2023, periode = "trimestre", decalage = 1)
#> [1] "premier trimestre 2024"

L’année peut être masquée avec avec_annee = FALSE. La langue utilisée est celle définie pour SERAD, sauf si lang est renseigné explicitement.

Singulier et pluriel

pluriel() choisit une forme selon la valeur fournie. Elle est utile pour construire des libellés sans gérer l’accord dans chaque texte.

pluriel(1, "création", "créations")  # "création"
#> [1] "création"
pluriel(3, "création", "créations")  # "créations"
#> [1] "créations"

Version anglaise

Une fois la langue changée, les fonctions de rédaction et de formatage produisent des sorties anglaises.

set_serad_language("en")

g_nom(1.04, 1)
#> [1] "an increase"
g_verbe(1.04, 1)
#> [1] "increased by 4.0%"
gETa_nom(1.1, 1, 0.99)
#> [1] "a sharp increase"
gETa_verbe(1.1, 1, 0.99)
#> [1] "increased sharply"
format_taux(5.4)
#> [1] "+5.4%"
format_pts(2.3)
#> [1] "+2.3 points"
format_niv(365484)
#> [1] "365,500"
libelle_periode(3, 2023)
#> [1] "March 2023"

Retour au français :

set_serad_language("fr")

Personnaliser les règles de rédaction

Les formulations produites par {serad} reposent sur des tables de correspondance stockées dans les options du package.

Ces options sont initialisées par :

init_serad_fr()
init_serad_en()

Les principales tables sont :

evo_simple, utilisée par g_nom_evo(), g_verbe_evo(), g_nom() et g_verbe() ;
evo_accel, utilisée par gETa_nom_taux(), gETa_verbe_taux(), gETa_nom() et gETa_verbe() ;
evo_accel_alt, utilisée pour les formulations alternatives lorsque l’argument alea est supérieur à 0.

Pour une personnalisation avancée, la méthode recommandée consiste à copier le contenu de init_serad_fr() ou init_serad_en() dans un fichier de configuration dédié, puis à modifier directement les tableaux.

Par exemple, un utilisateur peut créer un fichier init_serad_perso.R :

serad0 <- init_serad_fr()

serad0$evo_simple <- tibble::tribble(
  ~seuil, ~verbe_sing, ~verbe_plur, ~nom,
  1,     "augmente", "augmentent", "une hausse",
  0,     "est stable", "sont stables", "une stabilité",
  -Inf,  "diminue", "diminuent", "une baisse"
)

options(serad = serad0)

Il est aussi possible de modifier les seuils utilisés pour les formulations avec accélération :

serad0 <- init_serad_fr()

serad0$seuil$stable <- 0.1
serad0$seuil$accel_hausse <- 40
serad0$seuil$accel_baisse <- -40

options(serad = serad0)

Cette approche est volontairement simple : elle permet de personnaliser l’ensemble des règles de rédaction dans un fichier versionné, sans modifier le code interne du package.

Pour plus de détails, consulter :

?init_serad

Bonnes pratiques

Pour utiliser {serad} efficacement dans une chaîne de production, il est recommandé de :

fixer explicitement la langue au début du script ;
distinguer les fonctions de calcul, de formatage et de rédaction ;
éviter d’écrire du texte en dur dans les scripts lorsque le package peut déjà produire la formulation souhaitée ;
tester les rendus en français et en anglais dans une session propre.

Par exemple :

options(serad.lang = "en")
library(serad)

# ou après chargement
set_serad_language("en")

Prise en main de {serad}

Introduction

Initialisation et choix de la langue

Calcul des évolutions

Formater les résultats

Pourcentages

Pourcentages

Variations en points

Niveaux et différences de niveau

Décrire une évolution simple

Formulation nominale

Formulation verbale

Comparaisons qualitatives

Comparaison de niveaux

Comparaison de taux avec accord grammatical

Tenir compte de l’accélération

Exemple nominal

Exemple verbal

Utilisation d’une variante alternative

Dates, mois et trimestres

Mois

Trimestres

Singulier et pluriel

Version anglaise

Personnaliser les règles de rédaction

Bonnes pratiques

Conclusion