Skip to content

Bonnes pratiques de modélisation

Jump to bottom Edit New page
Sasha-Laniece edited this page Feb 23, 2022 · 49 revisions

Ces lignes directrices documentent les consensus construits au sein de la communauté de personnes qui modélisent le modèle socio-fiscal français depuis des années, au fur et à mesure que des questions sont apparues.

Un point important d'étape date de 2021, où deux RFC, respectivement sur les variables et les paramètres ont été menées pour établir un consensus sur cette mise en forme. Les raisons des choix faits à l'époque sont détaillés dessus.





Variables

Nommage des variables

Préfixes

  • Si une variable décrit la réalité, sans interprétation législative, on ne préfixe pas son nom. Par exemple : distance entre domicile et lieu d'études (distance_domicile_etudes), âge (age) peuvent être décrites sans avoir besoin de faire référence à un autre concept.
  • Si une variable décrit la réalité dans une certaine interprétation définie par la loi, on ne préfixe pas selon le contexte de réutilisation mais on décrit l'interprétation retenue dans le nom de la variable. Par exemple : distance entre domicile et lieu d'études en kilomètres, distance orthodromique à l'hexagone (distance_orthodromique plutôt que aides_mobilite_distance).

Sinon, on a un risque de faible découvrabilité par les réutilisateurs, et de multiplication des variables qui seront redéfinies pour chaque contexte d'usage, ce qui a un coût mémoire.

Variables intermédiaires

  • Par défaut, on minimise le nombre de variables intermédiaires. Sinon, on a un risque de doublon, un coût mémoire et une perte de découvrabilité. Voir par exemple les variables créées dans le code M de la DGFIP.
  • Une variable intermédiaire peut être créée si la définition qu'elle modélise est réutilisable, complexe, ou si son implémentation est vraiment trop lourde. L'arbitrage se fait donc en priorité sur la complexité de la formule de calcul.





/// - CETTE PARTIE EST UN DRAFT EN ATTENTE DE LA CLOTURE DE LA RFC 1672 ///

Paramètres

Les paramètres OpenFisca représentent la loi le plus fidèlement possible. Chaque évolution de valeur doit être justifiée par une référence législative.

Par convention, les #commentaires sont interdits, et seront supprimés automatiquement à la validation. Il est recommandé de mettre ses annotations directement dans le champ documentation.

description

Ce champ obligatoire est une description en français du paramètre. Il n'est pas limité mais contraint à une unicité dans le système socio-fiscal. Par convention, il doit contenir le nom de l'ensemble des nœuds traversés dans l'arborescence depuis le dossier parameters, avec une expansion des abréviations et les abréviations entre parenthèses.

  • Nom : description
  • Type : Langage naturel non limité, sur une seule ligne, sans espace en début ni fin, unique dans le système socio-fiscal.
  • Échelle de déclaration : Racine du paramètre
  • Cas d'usage :
    • Désambiguer un paramètre dont le nom est une abréviation.
    • Rechercher et afficher un paramètre dans l'explorateur de législation.
  • Exemples :
    • "Contribution sociale généralisée (CSG) sur les allocations chômage"
    • "Contribution exceptionnelle sur les hauts revenus"



values / brackets

Le champ values contient les valeurs des paramètres à partir de leur date d'application (cf. plus bas).

Dans le cas d'un barème, ce champ se nomme brackets et contient deux sous unités: un seuil (threshold) et une valeur (qui peut être un taux rate, un montant amount, ...)

Lorsqu'un dispositif est éteint, les values passent à null.

La date associée à un paramètre étant celle appliquée pour les simulations, il s'agit de la date d'entrée en application du point de vue du calcul du dispositif. Or, cette date peut être différente de la date de publication du texte (elle peut être mentionnée à la fin du texte officiel qui met en place la réforme, dans un décret d'application, etc.)

Pour l'IR, il y a une subtilité supplémentaire: d'une part, l'IR est un dispositif annuel, donc sa date d'application pour le calcul de l'impôt ne peut être qu'un 1er janvier. D'autre part, la convention actuelle dans Openfisca est en "année revenus", c'est-à-dire que la variable irpp pour une année N correspond, non pas à l'IR de la déclaration de revenus faite en année N, mais à l'IR au titre des revenus de l'année N (déclaration en N+1).

Donc, les paramètres de l'IR N+1 sur les revenus N sont à mettre systématiquement au 01/01/N. Une alternative serait une convention en "année paiement" (l'irpp de l'année N serait l'impôt effectivement payé en N), mais l'impôt sur les revenus N n'est pas forcément payé en N+1. N+1 n'est que la date de déclaration. Pour le paiement, il y a maintenant le prélèvement à la source et avant, il y avait un système d'acomptes et chaque contribuable pouvait choisir entre différentes options.

  • Nom : values ou brackets
  • Type : Float
  • Échelle de déclaration : Racine du paramètre
  • Exemples :
    • Dans le cas d'un paramètre simple:
values:
    1995-01-01:
      value: null
    1994-07-01:
      value: 74.01
    1993-01-01:
      value: 72.92
    1992-07-01:
      value: 71.98
    1992-01-01:
      value: 70.71
  • Dans le cas d'un barème:
brackets:
  - rate:
      1967-10-01:
        value: 0.095
      1970-08-01:
        value: 0.1025
      1981-11-01:
        value: 0.0545
      1984-01-01:
        value: null
    threshold:
      1967-10-01:
        value: 0.0
      1984-01-01:
        value: null
  - rate:
      1967-10-01:
        value: 0.02
      1976-01-01:
        value: 0.025
      1981-11-01:
        value: 0.08
      1984-01-01:
        value: 0.126
      1992-01-01:
        value: 0.128
      2016-01-01:
        value: 0.1284
      2018-01-01:
        value: 0.13
    threshold:
      1967-10-01:
        value: 1.0
      1984-01-01:
        value: 0.0



last_review

Cette metadata concerne la dernière valeur d’un paramètre. Il s’agit donc de ne vérifier qu’une seule valeur de la série : la dernière en vigueur. Ainsi, la date de ce champ est forcément postérieure à la dernière valeur du paramètre (et ceci peut facilement être vérifié en CI).

Elle est optionnelle et permet ainsi la capitalisation progressive de cette information dans la base de paramètres.

La bonne pratique est de fournir la référence législative correspondante à date. Si l’url est une information nouvelle, le contributeur peut décider de l’ajouter dans les références, avec une date postérieure à la dernière date de value. On mettra l'url à date uniquement dans la merge request s'il est déjà dans les références, afin d'éviter les redondances.

  • Nom : last_review
  • Type : String contenant une date
  • Échelle de déclaration : Champ metadata
  • Cas d'usage :
    • Indiquer qu’un paramètre est à jour, même si sa valeur n’a pas changée depuis X années.
    • Indiquer en front la dernière date de validité du code
  • Exemple :
values :
    1978-01-01 :
        value : 0.005
metadata:
+  last_review: "2021-10-17"



ux_name

La métadonnée ux_name répond au besoin d'un nom non-ambigu avec un nombre connu (limité) de caractères. Ce nom court autorise les abréviations les plus connues. Il s'inscrit toujours dans un contexte de présentation reprenant l'arborescence du yaml, permettant ainsi de différencier deux paramètres ayant le même ux_name.

Cette métadonnée est aussi introduite dans les index.yaml (cf. section ci-dessous).

Ce champ n'est pas obligatoire.

  • Nom : ux_name
  • Type : langage naturel limité à 70 caractères, sur une seule ligne, sans espace en début ni fin.
  • Échelle de déclaration : Champ metadata
  • Cas d'usage :
    • Afficher un nom reconnaissable par une personne non experte du modèle OpenFisca dans un espace d'affichage connu d'avance.
    • Faciliter la construction d'interfaces graphiques en ayant une contrainte connue de taille d'affichage.
  • Exemples :
    • Taux réduit
    • Fonds national d'aide au logement (FNAL)



reference

Une référence législative est exigée à chaque ajout ou modification d'une valeur, afin d'identifier la loi d'où provient le paramètre. Cette référence peut être le lien vers le décret qui modifie la valeur, ou un lien direct vers l'article en vigueur ou, idéalement, les deux.

On demande systématiquement un intitulé et une URL pour chaque référence législative, par le biais d'un dictionnaire, dont les clefs sont des noms de textes légaux et les valeurs sont des URLs publiquement accessibles ou des chaînes vides

  • Nom : reference
  • Type : Dictionnaire
  • Échelle de déclaration : Champ metadata
  • Cas d'usage :
    • Vérifier la validité d'une formule en consultant son origine légale.
    • Afficher l'intitulé de la source légale dans l'explorateur de législation.
  • Exemples :
  base:
    values:
      2020-05-01:
        value: 150
      2020-06-01:
        value: null
      2020-10-01:
        value: 150
  metadata:
+   reference:
+     2020-05-01:
+       - title: Décret n°2020-519 du 05/052020
+         href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000041849630/
+     2020-06-01:
+       - title: Décret n°2020-769 du 24/06/2020, art. 2
+         href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514
+     2020-10-01:     
+       - title: Décret n°2020-1453 du 27 novembre 2020
+         href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042574431

On notera, qu'à l'heure actuelle, il existe aussi de nombreuses références sans url. Elles prennent alors la forme suivante:

  base:
    values:
      1979-07-01:
        value: 150
  metadata:
+   reference:
+     1979-07-01:
+      - Loi cadre 79-32 du 16/01/1979
+      - Arrêté du 02/05/1979 portant agrément de la convention du 27/03/1979



official_journal_date

Anciennement 'date_parution_journal_officiel' côté IPP, ce champ a été renommé en anglais lors de l'intégration à OpenFisca.

Il se compose des dates de publication dans le Journal Officiel, pour chaque value. Il est donc inséré dans le noeud value pour éviter les répétitions des clefs (et donc le risque d’erreur). S’il y a plusieurs publications par dates, on fait un tableau [2019-01-01, 2019-01-04].

Ce champ n’est pas obligatoire.

  • Nom : official_journal_date
  • Échelle de déclaration : Champ value
  • Cas d'usage :
    • Pouvoir retrouver la publication dans le journal officiel
  • Exemples :
 values :
 2021-01-01 :
  value : 200
  reference :
    - "Article 2 du Décret n°2020-769 du 24 juin 2020: https://www.legifrance.gouv.fr/jorf/article_jo/JORFARTI000042032526/"
    - "Décret n°2020-769 du 24 juin 2020: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514”
+  official_journal_date : 2020-12-21
 2018-10-01 :
  value : 190
  reference :
    - "Article 2 du Décret n°2020-726 du 12 juin 2018: https://www.legifrance.gouv.fr/jorf/article_jo/JORFARTI000042032526/"
    - "Décret n°2020-743 du 10 juin 2018: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514”
+  official_journal_date : [2018-06-12, 2018-06-10]



description_en

Le champ description_en est directement issu de l'harmonisation avec l'IPP, et est affiché sur la version anglaise de leur site. Il n'est pas obligatoire.



notes

Le champ notes est directement issu de l'harmonisation avec l'IPP. Il contient des informations spécifiques à une date.

  • Nom: notes
  • Type : Texte libre
  • Échelle de déclaration : Champ metadata
  • Cas d'usage :
    • Ajouter une note en bas de chaque fichier Excel des barèmes IPP.
  • Exemples :
  values:
    2021-01-01:
      value: 200
  metadata:
    notes:
      2021-01-01: Ce montant ne concerne plus les retraités



documentation

Ce champ contient du texte libre qui contient des informations relatives au paramètre, notamment des explications générales, l'extension des acronymes, ou encore des références législatives plus larges que des valeurs spécifiques.

  • Nom: documentation
  • Type : Texte libre
  • Échelle de déclaration : Racine du paramètre
  • Cas d'usage :
    • Indiquer les limites ou les choix faits pour la modélisation.
    • Ajouter des information complémentaires.
  • Exemples :
    • À partir de 2014, des seuils spécifiques (célibataire, couple) sont employés pour le calcul de la décote.
    • La taxe d'apprentissage est créée par la Loi de finances du 13 juillet 1925. La loi 77-704 du 05/07/1977créé une cotisation supplémentaire de 0,2% pour financer la formation en alternance; elle doit être versée de manière exceptionnelle en 1977. Elle a été maintenue par la LFR pour 1978. En 1990, la contribution supplémentaire de 0,10% est remplacée par une cotisation pérenne de 0,10% pour la formation en alternance.
    • Une incertitude subsiste sur le taux applicable en Alsace-Lorraine entre 1973 et 1978 inclus. Taxe d'apprentissage : CGI, art. 224 et s. et art. 140 A et s. de l'annexe I ; pour l'Alsace-Moselle, art. 1599 ter J.



FAQ - Cas particuliers et questions ouvertes

Selon les paramètres, il arrive de rencontrer des cas un peu particuliers. Voici une liste des décisions prises pour chacun de ces cas. À noter qu'elles n'ont pas fait l'objet d'une RFC, et ne sont donc pas le résultat d'un consensus, mais plutôt de bonnes pratiques observées.



1 - Ajout de références 'récentes'

Est-ce que je peux ajouter une reference qui a une date postérieure à la dernière valeur du paramètre ?

Exemples:

  1. La référence (article) d'une valeur a changé, mais pas sa valeur.
  2. La seule référence en ma possession est postérieure à la dernière valeur.
  3. Le dispositif a changé (réforme) mais pas cette valeur.
  4. Je trouve une référence récente qui détaille un mécanisme ou une réforme.

Dans les cas 1, 2 et 3, on peut ajouter cette référence si celle-ci n'est pas redondante avec les références précédentes. (Par redondant, on entend: le même lien LégiFrance mais pas à la même date)

Dans le cas 4, cette référence étant un peu plus large que la value, il faudra plutôt l'ajouter dans le champ documentation.



2 - Le ux_name peut porter à confusion

Dans certains cas, le ux_name, même présenté dans son contexte d'arborescence, peut prêter à confusion.

Exemple: Pour le paramètre parameters.prelevements_sociaux.contributions_sociales.csg.chomage.imposable.taux_reduit.yaml, l'arborescence des ux_name (dans les index.yaml des noeuds) devrait être le chemin suivant:

Prélèvements sociaux / Contributions de Sécurité sociale du régime général / CSG / Chômage / Imposable / Taux réduit

Cependant, on va s'autoriser un peu de redondance par souci de clarification:

Prélèvements sociaux / Contributions de Sécurité sociale du régime général / CSG / Allocations chômage / CSG imposable / Taux réduit

Ceci permet de souligner deux choses:

  • La CSG est prélevée sur les allocations chômage et non pas pour l'assurance chômage
  • Il s'agit de la part imposable de CSG et non pas d'une CSG prélevée sur la part imposable des allocations chômage



/// FIN DE LA PARTIE EN DRAFT ///





Index

Dans le dossier parameters, chaque sous-dossier doit contenir un fichier index.yaml, qui explicite le noeud correspondant. La création d'un tel fichier est obligatoire lors de l'ajout d'un dossier.

Ce fichier se compose ainsi:

label: Cotisations du régime d'assurance maladie
metadata:
  ux_name: Assurance Maladie
  description_en: SSCs of the sickness scheme

Chacun de ces champs respecte les mêmes règles que pour les paramètres (cf. ci-dessus).





Tests

  • Les tests doivent être faits sur les variables le plus en aval possible. Les différents cas doivent être distingués par des différences d'attributs en amont et non avec des valeurs différentes pour les variables intermédiaires. Sinon, le risque est de ne pas arriver à tester des situations réelles mais des abstractions partielles.
Add a custom footer
Add a custom sidebar
Clone this wiki locally