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, d’une accélération ou d’un ralentissement ;
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)

Calculer une évolution

La fonction de base est g(). Elle calcule une variation relative entre deux niveaux et renvoie le résultat en pourcentage.

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

Par convention :

x1 est le niveau le plus récent ;
x2 est le niveau le plus ancien.

Si x2 = 0, une valeur epsilon est utilisée pour éviter une division par zéro.

Formater les résultats

Pourcentages

format_g() formate une variation en pourcentage.

format_g(5.3654)
#> [1] "+5,4 %"
format_g(-5.3654)
#> [1] "-5,4 %"
format_g(5.3654, signe = FALSE)
#> [1] "5,4 %"

En anglais :

set_serad_language("en")
format_g(5.3654)
#> [1] "+5.4%"
format_g(-5.3654)
#> [1] "-5.4%"

Puis on revient en français pour la suite.

set_serad_language("fr")

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 et format_delta() une différence de niveau.

format_niv(365484)
#> [1] "365 500"
format_delta(365484)
#> [1] "+365 500"
format_delta(-365484)
#> [1] "-365 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_taux(g) — pour une formulation nominale ;
g_verbe(x1, x2) — et sa variante g_verbe_taux(g) — pour une formulation verbale.

Formulation nominale

g_nom(1.04, 1)
#> [1] "une forte hausse"
g_nom(1.001, 1)
#> [1] "une légère hausse"
g_nom(0.95, 1)
#> [1] "une forte baisse"

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

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

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

g_nom_taux(4, titre = TRUE)
#> [1] "Forte hausse"
g_nom_taux(-4, titre = TRUE)
#> [1] "Baisse"

Formulation verbale

g_verbe(1.10, 1)
#> [1] "bondit de 10,0 %"
g_verbe(1.003, 1)
#> [1] "augmente de 0,3 %"
g_verbe(0.96, 1)
#> [1] "baisse de 4,0 %"

Directement à partir d’un taux :

g_verbe_taux(10)
#> [1] "bondit de 10,0 %"
g_verbe_taux(0)
#> [1] "est stable"
g_verbe_taux(-4)
#> [1] "baisse de 4,0 %"

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

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

Comparaisons qualitatives

Le package propose aussi plusieurs fonctions pour comparer deux niveaux de façon qualitative.

Hausse, baisse ou stabilité

alahausse(1.004, 1)
#> [1] "à la hausse"
alahausse(0.996, 1)
#> [1] "à la baisse"
alahausse(1, 1.0004)
#> [1] "inchangé"

Au-dessus / en dessous

audessus(1.04, 1)
#> [1] "au-dessus"
audessus(0.96, 1)
#> [1] "en dessous"

Davantage / moins

davantage(1.04, 1)
#> [1] "davantage"
davantage(0.96, 1)
#> [1] "moins"

Dépassement avec accord grammatical

depasse(1.04, 1)
#> [1] "excèdent"
depasse(1.04, 1, sing = TRUE)
#> [1] "excède"
depasse(0.96, 1)
#> [1] "sont en dessous 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 accélération"
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] "accélère"
gETa_verbe(0.96, 1, 1.01)
#> [1] "recule de nouveau"
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.

set.seed(123)
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

Le package fournit aussi des helpers pour générer des expressions temporelles.

Mois

quelMois(3, 2023)
#> [1] "mars 2023"
quelMois(3, 2023, majuscule = TRUE)
#> [1] "Mars 2023"
nextMois(12, 2023)
#> [1] "janvier 2024"
prevMois(1, 2023)
#> [1] "décembre 2022"

Trimestres

quelTrim(3, 2023)
#> [1] "troisième trimestre 2023"
quelTrim(3, 2023, majuscule = TRUE)
#> [1] "Troisième trimestre 2023"
quelTrim(3, 2023, type = "chiffres")
#> [1] "3^e^ trimestre 2023"
nextTrim(4, 2023)
#> [1] "premier trimestre 2024"
prevTrim(1, 2023)
#> [1] "quatrième trimestre 2022"

Détection d’un mois dans un texte

whichMois("En Juil 98")
#> [1] 7
whichMois("March 2024")
#> [1] 3

Contributions

La fonction contributions() permet de documenter les contributions des différentes composantes à une évolution globale.

col0 <- c("Y1T1", "Y1T2", "Y1trim3", "Y1T4", "Y2T1", "Y2-T2")
col1 <- c(12, 6, 2, 86, 19, 10)
col2 <- c(4, 8, 7, 34, 87, 14)
col3 <- c(10, 20, 3, 66, 90, 54)
col4 <- c(29, 12, 4, 16, 40, 94)
col5 <- c(58, 76, 1, 3, 34, 19)

df1 <- data.frame(col0, col1, col2, col3, col4, col5)

contributions(df1)
#> [1] "col2 contribue pour +92,4 % à l'évolution entre Y2T1 et Y2-T2 ; col3 contribue pour +45,6 % à l'évolution entre Y2T1 et Y2-T2 ; col4 contribue pour -68,4 % à l'évolution entre Y2T1 et Y2-T2 ; "

En anglais :

set_serad_language("en")
contributions(df1, lang = "en")
#> [1] "col2 accounts for +92.4% of the change between Y2T1 and Y2-T2; col3 accounts for +45.6% of the change between Y2T1 and Y2-T2; col4 accounts for -68.4% of the change between Y2T1 and Y2-T2."
set_serad_language("fr")

Plus haut / plus bas niveau

La fonction plushautniveau() permet d’indiquer si la dernière valeur d’une série correspond au plus haut ou au plus bas niveau observé sur une certaine période.

col0 <- c("Y1T1", "Y1T2", "Y1trim3", "Y1T4", "Y2T1", "Y2-T2")
col1 <- c(12, 11, 7, 6, 9, 10)
col2 <- c(12, 11, 7, 6, 9, 14)
col3 <- c(12, 11, 3, 6, 9, 4)

df2 <- data.frame(col0, col1, col2, col3)

plushautniveau(df2)
#> [1] "C'est le plus haut niveau depuis Y1T2."
plushautniveau(df2, vary = "col2")
#> [1] "C'est le plus haut niveau depuis le début de la série."
plushautniveau(df2, vary = "col3")
#> [1] "C'est le plus bas niveau depuis Y1trim3."

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] "a strong increase"
g_verbe(1.04, 1)
#> [1] "rose sharply by 4.0%"
gETa_nom(1.1, 1, 0.99)
#> [1] "an acceleration"
gETa_verbe(1.1, 1, 0.99)
#> [1] "accelerated"
format_g(5.4)
#> [1] "+5.4%"
format_pts(2.3)
#> [1] "+2.3 points"
format_niv(365484)
#> [1] "365,500"
quelMois(3, 2023)
#> [1] "march 2023"
quelTrim(3, 2023)
#> [1] "third quarter 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_taux(), g_verbe_taux(), 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}