# iperform

## Introduction

Décrire, résumer, modéliser et prédire font partie des principaux objectifs poursuivis lors de l’analyse d’une série temporelle. L’étape de la description, comme pour toutes les données, consiste souvent à des représentations graphiques telles que le chronogramme, l’histogramme, le diagramme retardé, et aux calculs des statistiques issuelles telles que la moyenne, la variance, le coefﬁcients d’aplatissement et d’asymétrie.

Dans les domaines de finance, de comptabilité ou de marketing opérationnel, les experts suivent au quotidien l’évolution de leurs activités en comparant à chaque fois les résultats d’une date (ou d’une période) par rapport à une date (ou une période) antérieure, par rapport aux résultats du marché global ou par rapport aux résultats de leurs concurrents directs. On parle là de concept de performance.

Si on note par \(x_t\) ~ \(\left\{x_t : t = 1, · · · , n\right\}\) une série temporelle où \(t\) represente le temps, les performances les plus souvent sont :

- La performance year-to-date (YTD) : qui conrespond au résultat cumulé commençant le premier jour de l’année civile ou de l’exercice en cours jusqu’à la date actuelle, \[YTD_x = \sum_{t=1}^{n} x_{t}\] \(x_1\) correspond à la valeur de la série au 1er janvier, et \(x_n\) à la valeur de la série à la date actuelle.

- La performance month-to-date (MTD) : qui conrespond au résultat cumulé commençant le premier jour du mois en cours jusqu’à la date actuelle au cours du même mois, \[MTD_x = \sum_{t=1}^{n} x_{t}\] \(x_1\) correspond à la valeur de la série au 1er jour du mois, et \(x_n\) à la valeur de la série à la date actuelle au cours du même mois.

- La performance week-to-date (WTD) : qui conrespond au résultat cumulé commençant le permier jour de la semaine jusqu’à la date actuelle au cours de la même semaine. \[WTD_x = \sum_{t=1}^{n} x_{t}\] \(x_1\) correspond à la valeur de la série au 1er jour de la semaine, et \(x_n\) à la valeur de la série à la date actuelle au cours de la même semaine.

On peut egalement parler des concepts de day-to-date (pour la durée écoulée au cours d’une journée pour ceux qui suivent l’activité par heure) ou quater-to-date (pour le résultat cumulé sur un trimestre) ou encore full month, full year, etc pour designer la totalité de la periode indiquée.

Ces concepts représentent à eux seuls près de 90% de l’information de pilotage des activités des analystes du secteur bancaire, bourse, télécommunication avant d’arriver à la modélisation et la prédiction des résultats futurs. Avec la révolution des solutions Big Data sur la visualisation des données, plusieurs tableaux de bord utilisent ces concepts en combinaison avec les variations par rapport aux dates ou periodes antérieures pour enrichir l’histoire lors de la présentation des données, des résultats ou de la performance de l’activité.

Cette vignette décrit l’utilisation des differentes fonctions offertes par le package iperfom pour répondre à ce besoin devenu de plus en plus important avec la révolution des données.

Le package iperform est une boite à outil qui permet de calculer les performances d’une série temporelle en une date ou sur une période bien spécifique. Couplé avec le package R lubridate, le package offre en cette prémière version les principales fonctions que voici regroupées en quatre (4) catégories :

### Les performances

- `dday()` qui renvoie la valeur d’une série à une date donnée en argument,

- `wtd()` qui renvoie la somme des valeurs de la série depuis le début de la semaine correspondante à la date renseignée en argurment,

- `mtd()` qui renvoie la somme des valeurs de la série depuis le début du mois correspondant à la date renseignée en argurment,

- `qtd()` qui renvoie la somme des valeurs de la série depuis le début du trimestre correspondant à la date renseignée en argurment,

- `ytd()` qui renvoie la somme des valeurs de la série depuis le début de l’année correspondante à la date renseignée en argurment,

- `full_m()` qui renvoie la somme des valeurs de la série depuis sur tout le mois correspondant à la date renseignée en argurment.

### Les aperçus

- `overview()` qui renvoie à l’image de la fonction `summary()`, un résumé des performances couplées avec des comparaisons par rapport aux périodes antérieures de la série.

### Les prévisions

- `forecast_m()` qui renvoie une somme estimée sur une période de la série en tenant compte de la performance month-to-date. La fonction comprend un argument qui permet d’utiliser un modèle spécifique de prédiction.

### Les transformations

- `mean_m()`qui renvoie un nouveau jeu des données créé après transformation de la série intiales.

Dans cette vignette, on présente les mecanismes des calculs derrière ces fonctions.

## Exemples

Pour commencer, nous allons charger quelques packages nécessaires dont nous avons besoin

    library(lubridate)
    library(iperform)
    library(ggplot2)

### 0. Description des données

Nous allons illustré le fonctionnement de ces fonctions à l’aide d’un jeu de données contenant les indicateurs de l’activité du service voix mobile d’un operateur de téléphonie mobile anonyme.

    data(voix_mobile)

Ce jeu des données contient 4 variables :

- `date`, variable de type date qui part du 1er janvier 2021 au 30 septembre 2023,

- `Parc`, variable de type numeric qui renseigne le nombre des clients qui ont effectué au moin un appel sortant,

- `Usage`, variable de type numeric qui renseigne le nombre des minutes consommées par l’ensemble des clients lors des appels, et

- `Revenu`, variable de type numeric qui renseigne le revenu généré par les usages des clients à un tarif quelconque.

    head(voix_mobile)
    #>         date Parc    Usage Revenu
    #> 1 2021-01-01 5178 10444.69 615.66
    #> 2 2021-01-02 3808  7669.21 473.96
    #> 3 2021-01-03 3527  7099.51 437.71
    #> 4 2021-01-04 3932  7920.70 486.31
    #> 5 2021-01-05 4149  8360.29 514.61
    #> 6 2021-01-06 4146  8353.91 509.29

Un petit resumé sur des données

    summary(voix_mobile)
    #>       date                 Parc          Usage           Revenu
    #>  Min.   :2021-01-01   Min.   :2516   Min.   : 5051   Min.   :366.0
    #>  1st Qu.:2021-09-08   1st Qu.:5598   1st Qu.: 9550   1st Qu.:519.5
    #>  Median :2022-05-17   Median :7025   Median :10671   Median :557.0
    #>  Mean   :2022-05-17   Mean   :6625   Mean   :10546   Mean   :563.5
    #>  3rd Qu.:2023-01-22   3rd Qu.:7794   3rd Qu.:11664   3rd Qu.:603.2
    #>  Max.   :2023-09-30   Max.   :8154   Max.   :15285   Max.   :808.8

La variable Revenu sur quoi on va se focaliser varie de 365.96 usd à 808.79 usd, avec une moyenne de 563.5172084 usd. Elle a une variance de 3819 et un écart type de 62. La valeur de p-value < 0,05 de la sortie du test de normalité de Shapiro ci-dessous indique que la distribution des données est significativement différente de la distribution normale. Voilà le peu qu’on puisse dire, hormis les représentations graphiques sur ce qui est de la description de cette série.

    shapiro.test(voix_mobile$Revenu)
    #>
    #>  Shapiro-Wilk normality test
    #>
    #> data:  voix_mobile$Revenu
    #> W = 0.98597, p-value = 3.215e-08

### 1. La fonction dday()

Pour connaitre le `Revenu` que l’ensemble des clients ont généré en date du 11 août 2023, on utilise la fonction `dday()` comme suit :

    dday(data = voix_mobile,
          date = "2023-08-11",
          d = 0,
          x = "Revenu",
          unite = 1,
          decimal = 0)
    #> [1] 569

Les arguments de la fonction

- `data` le jeu des données qui contient l’ensemble des données à exploiter,

- `date` un character qui renseine la date à laquelle on cherche l’information,

- `d` un entier qui determine le decalage des jours à prendre, la valeur par défaut vaut `0`. si `d=1`, on prendra la date du 10 août 2023,

- `unite` un numeric qui renseigne l’echel des valeurs qu’on souhaite avoir. sa valeur par defaut vaut `1`. Si `unite=1000`, la fonction va renvoyer une valeur diviser par `1000`, et

- `decimal` un entier designant le nombre de chiffre après la virgule qu’on souhaite afficher si le résultat est un decimal. Sa valeur par défaut vaut `0`.

### 2. La fonction mtd()

Pour connaître la performance month-to-date du revenu réalisée en date du 11 août 2023, c’est-à-dire la somme des valeurs partant du 01 août 2023 au 11 août 2023 inclus, on utilise la fonction `mtd()` comme suit :

    mtd(data = voix_mobile,
        date = "2023-08-11",
        m = 0,
        x = "Revenu",
        unite = 1,
        decimal = 0)
    #> [1] 6100

ici, seul l’argument `m` est nouveau, les autres ont la même utilité que pour la fonction `dday()`.

- `m` un entier qui determine le decalage du mois à prendre, la valeur par défaut vaut `0`. si `m=1`, on prendra la date du 11 juillet 2023.

### 3. La fonction ytd()

Pour connaître la performance year-to-date du revenu réalisée en date du 11 août 2023, c’est-à-dire la somme des valeurs partant du 01 janvier 2023 au 11 août 2023 inclus, on utilise la fonction `ytd()` comme suit :

    ytd(data = voix_mobile,
        date = "2023-08-11",
        a = 0,
        x = "Revenu",
        unite = 1000,
        decimal = 0)
    #> [1] 123

idem pour les arguments.

- `a` un entier qui determine le decalage de l’année à prendre, la valeur par défaut vaut `0`. Si `a=1`, on prendra la date du 11 août 2022.

### 4. La fonction wtd()

Pour connaître la performance week-to-date du revenu réalisée en date du 11 août 2023, on part du fait que la date 11 août 2023 est un vendredi, donc le 6e de la semaine en considerant le dimanche 06 août 2023 comme 1er jour. Ainsi, on calcule la somme des valeurs partant du 06 au 11 inclus en utilisant la fonction `wtd()` comme suit :

    wtd(data = voix_mobile,
        date = "2023-08-11",
        w = 0,
        x = "Revenu",
        unite = 1,
        decimal = 0)
    #> [1] 3348

idem pour les arguments.

- `w` un entier qui determine le decalage de la semaine à prendre, la valeur par défaut vaut `0`. Si `w=1`, on prendra la date du vendredi 4 août 2022.

### 5. La fonction full_m()

Cette fonction calcule la somme des valeurs d’une série au cours d’un mois. Le mois est déterminé par la date qu’on passe en argument à la fonction. Ainsi le code ci-dessous va nous renvoyer le total jusqu’en date du 31 août 2023 :

    full_m(data = voix_mobile,
           date = "2023-08-11",
           x = "Revenu",
           unite = 1000,
           decimal = 0,
           cumul = FALSE)
    #> [1] 16

Et cela quelque soit la date qu’on introduit en argument si cette dernière est comprise entre 01 août 2023 et 31 août 2023. On peut le verifier avec le code ci-dessous :

    full_m(data = voix_mobile,
           date = "2023-08-25",
           x = "Revenu",
           unite = 1000)
    #> [1] 16

### 6. La fonction forecast_m()

Pour cette version du package, la fonction `forecast_m()` ne fait pas grande chose, si ce n’est de calculer le total qu’on pourrait avoir sur un mois, connaissant sa performance month-to-date et le nombre du jour restant dans le même mois. Par exemple, si on place à la date du 2023-08-11, le forecast en cette date vaut :

    forecast_m(data = voix_mobile,
               date = "2023-08-11",
               x = "Revenu",
               unite = 1000,
               decimal = 0,
               cumul = FALSE,
               mod = "NULL")
    #> [1] 17

En constate que cette valeur sera différente en fonction de la date à laquelle on se place au cours du mois :

    vec_date = c("2023-08-20", "2023-08-25", "2023-08-28", "2023-08-30", "2023-08-31")

    for (d in vec_date) {
      F = forecast_m(data = voix_mobile,
                 date = d,
                 x = "Revenu",
                 unite = 1000)
      print(F)
      }
    #> [1] 17
    #> [1] 16
    #> [1] 16
    #> [1] 16
    #> [1] 16

L’arguments `mod`

- `mod`, un character qui determine le type de modèle à utiliser pour faire la prediction. Sa valeur par defaut est `NULL` et l’alternative ne fait pas l’objet de cette version.

Mais au moins, on constate que pour ce modèle, plus on donne en argument une date qui est proche de la clôture du mois, plus la fonction renvoit une valeur proche de la fonction `full_m`.

### 7. La fonction overview()

On a l’habitude d’utiliser la fonction de base `summary()` qui renvoie les statistiques issuelles, cependant ces paramètres entrent rarement dans le narratif des analystes des données du secteur susmentionnés. Pour reporter les résultats, les experts presentent des apercus globaux ou ils parlent des performances YTD, MTD, WTD, etc… et leurs comparaisons par rapport aux périodes antérieures.

Rappellons ici quelques concepts des comparaisons :

- La comparaison DoD en date du 2023-08-11 : elle consiste à calculer la variation du revenu en cette date par rapport à la date du 2023-08-10, c-est-à-dire: \[DoD = \frac{dday - dday_1}{dday}\]

- La comparaison SPLM en date du 2023-08-11 : elle consite à calculer la variation MTD au 2023-08-11 par rapport au MTD en date du 2023-07-11 (on note souvent par \(MTD_1\)) : \[SLPM = \frac{MTD - MTD_1}{MTD}\]

- La performance YoY en date du 2023-08-11 : elle consite à calculer la variation YTD au 2023-08-11 par rapport au YTD en date du 2022-08-11 (on note souvent par \(YTD_1\)) : \[YoY = \frac{YTD - YTD_1}{YTD}\]

On parle aussi de la comparaison WoW, MoM, etc.

Ainsi, si on souhaite avoir un aperçu du revenu en date du 2023-08-11, on utilise la fonction `overview()` comme suit :

    overview(data = voix_mobile,
             date = "2023-08-11",
             x = "Revenu",
             unite = 1,
             decimal = 2,
             cumul = FALSE)

Lecture de la sortie du code R :

    #>   Facteur DDay7 DDay   DoD WTD1  WTD  WoW MTD1  MTD SPLM Full_M FORECAST  MoM
    #> 1  Revenu   577  569 -1.39 3228 3348 3.72 6035 6100 1.08  16308    17191 5.41
    #>     YTD1    YTD   SPLY
    #> 1 137302 122850 -10.53

On pourra par exemple dire :

En date du 2023-08-11, l’operateur mobile a réalisé un chiffre d’affaire de 6100 usd en MTD, soit une hausse de 1.08% comparé à la même periode du mois passé. Avec le nombre de jours restant au cours du mois, on prévoit un total de 1.7191^{4} usd à la fin mois, ce qui fera une hausse de 5.41% par rapport à tout le mois de Juillet. En outre, la performance year-to-date atteint 1.2285^{5} usd, soit une baisse de -10.53% par rapport à l’année passée.

Certe, ce discours ne represente pas les causes qui expliquent les resultats en chaque période ni les différentes variations, mais au moins, raconte une histoire évolutive et un aperçu global de la perfomance de l’activité. Il ne restera qu’au rapporteur d’enrichir son histoire avec les resultats des analyses des causes à effet.

### 8. La fonction mean_m()

Cette fonction transforme une série temporelle à une série de moyenne mobile où chaque terme de la série devient la moyenne de lui-même avec ses sept(6) derniers termes précédants. A la sortie, la fonction renvoie un jeu des données où chaque colonne renseigne les données d’une année pour être superposées sur un graphe.

Exemple d’utilisation

    df_mb = mean_m(data = voix_mobile,
                   x = "Revenu",
                   unite = 1,
                   decimal = 0)

    head(df_mb, 10)
    #>          date Min 2021 2022 2023 Max
    #> 1  2023-01-01 616  616  675  645 675
    #> 2  2023-01-02 545  545  587  633 633
    #> 3  2023-01-03 509  509  584  625 625
    #> 4  2023-01-04 503  503  573  615 615
    #> 5  2023-01-05 506  506  577  613 613
    #> 6  2023-01-06 506  506  580  612 612
    #> 7  2023-01-07 506  506  581  608 608
    #> 8  2023-01-08 491  491  568  591 591
    #> 9  2023-01-09 495  495  569  588 588
    #> 10 2023-01-10 497  497  575  587 587

- Tous les arguments ont le même sens sens que dans les fonctions précédentes,

- La colonne date est de longueur `n` inférieur ou egale à `365`. Elle depend de l’etendue de la période du jeu des données initial,

- Les moyennes calculées sont classées par année civiles, autant on a des années, autant on aura des colonnes,

- L’argument `borne` permet de masquer la colonne `Min` et `Max` de chaque ligne.