# Prise en main de {serad}

####

# 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 :

1. la logique économique (hausse, baisse, stabilité, accélération, ralentissement) ;
2. la mise en forme (pourcentage, points, niveaux, dates) ;
3. 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 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] "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] "a sharp increase"
    gETa_verbe(1.1, 1, 0.99)
    #> [1] "increased sharply"
    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")

# Conclusion

Le package `{serad}` permet de standardiser et d’automatiser une grande partie de la rédaction conjoncturelle. Il est particulièrement utile lorsque les mêmes structures de phrases doivent être réutilisées dans des publications récurrentes, tout en conservant :

- une cohérence de style ;
- une précision dans les formulations ;
- et désormais une capacité de sortie en français comme en anglais.