---
title: "Prise en main de {serad}"
author: ""
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Prise en main de {serad}}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE
)
```

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

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.

```{r setup}
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.

```{r}
get_serad_language()
```

Pour passer en anglais :

```{r, eval = FALSE}
set_serad_language("en")
```

Pour revenir au français :

```{r, eval = FALSE}
set_serad_language("fr")
```

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

```{r, eval = FALSE}
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 % :

```{r}
g(105, 100)
g(95, 100)
```

# Formater les résultats

## Pourcentages
## Pourcentages

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

```{r}
format_taux(5.3654, signe = FALSE)  # Part : 5,4 %
format_taux(5.3654)                 # Hausse : +5,4 %
format_taux(-5.3654)                # Baisse : -5,4 %
```

## Variations en points

`format_pts()` permet de formater une variation en points.

```{r}
format_pts(5.3654)
format_pts(-1.2)
format_pts(1.3654, signe = FALSE)
format_pts(5.3654, abrev = TRUE)
```

## Niveaux et différences de niveau

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

```{r}
format_niv(365484)
format_niv(365484, signe = TRUE)
format_niv(300000 - 365484, signe = TRUE)
```

# 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

```{r}
g_nom(1.04, 1)
g_nom(1.001, 1)
g_nom(0.95, 1)
```

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

```{r}
g_nom_evo(4)
g_nom_evo(0)
g_nom_evo(-4)
```

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

```{r}
g_nom_evo(4, titre = TRUE)
g_nom_evo(-4, titre = TRUE)
```

## Formulation verbale

```{r}
g_verbe(1.10, 1)
g_verbe(1.003, 1)
g_verbe(0.96, 1)
```

Directement à partir d'un taux :

```{r}
g_verbe_evo(10)
g_verbe_evo(0)
g_verbe_evo(-4)
```

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

```{r}
g_verbe_evo(-0.1)
g_verbe_evo(-0.1, stable_sans_valeur = FALSE)
```

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

```{r}
# Situer un niveau
comparaison(104, 100, 
            "au-dessus de", 
            "au même niveau que",
            "en dessous de", 
            seuil = 0)

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

# Comparer des quantités
comparaison(104, 100, 
            "davantage", 
            "autant",
            "moins", 
            seuil = 0)
```

## Comparaison de taux avec accord grammatical

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

```{r}
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"
)
```

# 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

```{r}
gETa_nom(1.1, 1, 0.99)
gETa_nom(0.96, 1, 1.01)
gETa_nom(1.00049, 1, 0.9996)
```

## Exemple verbal

```{r}
gETa_verbe(1.1, 1, 0.99)
gETa_verbe(0.96, 1, 1.01)
gETa_verbe(1.003, 1, 0.99, sing = FALSE)
```

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

```{r}
gETa_verbe_taux(10, 1, alea = 1)
gETa_nom_taux(10, 1, alea = 1)
```

# 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

```{r}
libelle_periode(3, 2023, periode = "mois")
libelle_periode(12, 2023, periode = "mois", decalage = 1)
libelle_periode(1, 2023, periode = "mois", decalage = -1)
```

## Trimestres

```{r}
libelle_periode(3, 2023, periode = "trimestre")
libelle_periode(3, 2023, periode = "trimestre", format = "chiffres")
libelle_periode(4, 2023, periode = "trimestre", decalage = 1)
```

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.

```{r}
pluriel(1, "création", "créations")  # "création"
pluriel(3, "création", "créations")  # "créations"
```

# Version anglaise

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

```{r}
set_serad_language("en")

g_nom(1.04, 1)
g_verbe(1.04, 1)
gETa_nom(1.1, 1, 0.99)
gETa_verbe(1.1, 1, 0.99)
format_taux(5.4)
format_pts(2.3)
format_niv(365484)
libelle_periode(3, 2023)
```

Retour au français :

```{r}
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 :

```{r, eval = FALSE}
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` :

```{r, eval = FALSE}
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 :

```{r, eval = FALSE}
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 :

```{r, eval = FALSE}
?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 :

```{r, eval = FALSE}
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.