-
Notifications
You must be signed in to change notification settings - Fork 99
Bonnes pratiques de modélisation
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.
- 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_orthodromiqueplutôt queaides_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.
- 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 ///
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.
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.
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.
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
- Exemples :
"Contribution sociale généralisée (CSG) sur les allocations chômage""Contribution exceptionnelle sur les hauts revenus"
Le champ description_en est directement issu de l'harmonisation avec l'IPP, et est affiché sur la version anglaise de leur site. Il s'agit de la traduction en anglais du champ description.
Ce champs est optionnel.
Le champ values contient les valeurs des paramètres à partir de leur date d'application.
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.)
- Nom :
valuesoubrackets- Type : Float
- Échelle de déclaration : Racine du paramètre
- Exemple 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
- Exemple 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
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
irpppour 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.
Cette metadata concerne la dernière valeur d’un paramètre et permet 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 ou égale à la dernière valeur du paramètre (et ceci peut facilement être vérifié en CI).
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
Elle est optionnelle et permet ainsi la capitalisation progressive de cette information dans la base de paramètres.
- Nom :
last_review- Type : String contenant une date
- Échelle de déclaration : Champ
metadata- Exemple :
values : 1978-01-01 : value : 0.005 metadata: + last_review: "2021-10-17"
Fournir la référence législative affichant directement la dernière valeur à jour: un article ou une circulaire. Si l’url est une information nouvelle, le contributeur peut décider de l’ajouter dans les références au niveau de 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.
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.
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.
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- Exemples :
Taux réduitFonds national d'aide au logement (FNAL)
L'application LexImpact de l'Assemblée nationale utilise beaucoup les ux_name, cet exemple montre :
- sur la gauche, le nom (
description) de la variable : "Contribution sociale généralisée (CSG) déductible prélevée sur les salaires" ; - sur la droite, le nom réduit (
ux_name) de la variable : "CSG déductible salaires".
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
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. Il est impératif que la référence soit officielle et il est préférable de sélectionner un article de loi codifié.
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.
- Automatiser la détection d'un changement législatif.
On demande systématiquement un intitulé title et une URL href pour chaque référence législative.
La référence est obligatoire, l'ajout de l'url est optionnelle mais vivement conseillée pour aider à la revue du paramètre.
- Nom :
reference- Échelle de déclaration : Champ
metadata- Exemples :
base: values: 2020-06-01: value: 124 2020-10-01: value: 150 metadata: + reference: + 2020-06-01: + - title: Article 197, I.1. du Code général des impôts + href: https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000042907517 + - 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
Bonne pratique d'écriture et règles de syntaxe
Pour le titre title, il est utile de suivre les règles suivantes pour harmoniser l'écriture des références :
- Mettre le nom de l’article avant le nom de la loi ou du Code qui l’englobe.
- Toujours spécifier le Code si l’article est codifié.
- Mettre une majuscule à « Code » et une minuscule pour les mots qui suivent.
Exemple : Article 197 du Code général des impôts
- S’il est utile d’ajouter le paragraphe ou le numéro de l’article. Séparer par une virgule :
Exemple : Article 197, 1. du Code général des impôts
- Si vous souhaitez ajouter le numéro de l’alinéa (pertinent uniquement si l’article est très grand, à éviter dans les autres cas, car ça alourdit beaucoup la référence) :
Exemple :
- Article 197, 1. §5 du Code général des impôts
- Article 197, 1. §§5 à 10 du Code général des impôts
Lorsque vous sélectionnez une URL sur Légifrance, celle-ci contient souvent par défaut la date du jour de la consultation. Cette date ne correspond à rien de légal, retirez-là.
À éviter : Une URL avec la date de votre consultation.
https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000044978323/2022-10-31/
Il faut retirer tout ce qui est après le numéro de l’article, qui correspond au parcours de recherche dans Legrifrance et qui n’apporte pas d'informations.
À choisir :
https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000044978323
À éviter : Voici un exemple d’url qui n’a pas été nettoyée :
https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000044978323?init=true&nomCode=E92-7A%3D%3D&page=1&query=&searchField=ALL&tab_selection=code
Pour que la référence passe les tests et fonctionne, voici quelques éléments de syntaxe à respecter :
+ 2003-07-01:
value: 29.56
metadata:
ux_name: Montant minimum journalier
unit: currency
reference:
+ 2003-07-01:
- href: https://www.legifrance.gouv.fr/URLdeLaPremiereReference
title: Article 197 du Code général des impôts2021-01-01 dans OpenFisca car le paramètre, et la Loi, s’applique aux revenus perçus en 2021.
Pour mettre plusieurs références pour un même paramètre, il faut créer une liste avec des tirets. => Ce fichier yaml est un bon exemple de référence, où il peut y avoir plusieurs références pour une seule et même date.
À faire :
reference: 2003-07-01: - href: https://www.legifrance.gouv.fr/URLdeLaPremiereReference title: Article 197 du Code général des impôts - href: https://www.legifrance.gouv.fr/URLdeLaSecondeReference title: Décret 2003-573 du 27/06/2003
Ne fonctionne pas : Il faut veiller à garder la syntaxe ci-dessus, y compris l’indentation, sinon les tests ne passent pas. L'exemple ci-dessous ne fonctionnera pas car l'indentation n'a pas été respectée :
reference: 2003-07-01: - href: https://www.legifrance.gouv.fr/URLdeLaPremiereReference title: Article 197 du Code général des impôts - href: https://www.legifrance.gouv.fr/URLdeLaSecondeReference title: Décret 2003-573 du 27/06/2003
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/1979Je suis dans une situation où j'ai besoin d'ajouter une référence dont la date est postérieure à la dernière valeur du paramètre :
- La référence (article) d'une valeur a changé, mais pas sa valeur.
- La seule référence en ma possession est postérieure à la dernière valeur.
- Le dispositif a changé (réforme) mais pas cette valeur.
- 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.
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. S’il y a plusieurs publications par dates, on fait un tableau [2019-01-01, 2019-01-04].
Cas d'usage :
- Pouvoir retrouver la publication dans le journal officiel
Ce champ est optionnel.
- Nom :
official_journal_date- Échelle de déclaration : Champ
value- Exemples :
values: 2021-01-01 : value: 200 2018-10-01 : value: 190 reference: 2021-01-01 : - title: Décret n°2020-769 du 24/06/2020, art. 2 href: https://www.legifrance.gouv.fr/jorf/article_jo/JORFARTI000042032526/ 2018-10-01 : - title: Décret n°2020-743 du 10/06/2018 href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514 + official_journal_date : 2021-01-01 : "2020-06-24" 2018-10-01 : [2018-06-12, 2018-06-10]
Le champ ipp_csv_id est directement issu de l'harmonisation avec l'IPP, et sert à la génération de leur site.
Ce champ est optionnel et sera retiré à l'issue du chantier d'harmonisation avec les barèmes de l'IPP.
Le champ notes contient des informations spécifiques à une date.
Cas d'usage :
- Ajouter une information spécifique à une
valueou une année- Ajouter une note en bas de chaque fichier Excel des barèmes IPP.
Ce champ est optionnel.
- Nom:
notes- Type : Texte libre
- Échelle de déclaration : Champ
metadata- Exemples :
values: 2021-01-01: value: 200 metadata: notes: 2021-01-01: Ce montant ne concerne plus les retraités
Ce champ de texte libre 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 (par exemple Service-Public ou l'Urssaf).
Cas d'usage :
- Indiquer les limites ou les choix faits pour la modélisation.
- Ajouter des information complémentaires.
Ce champ est optionnel et vise à accueillir tous les #commentaires qui seront bientôt supprimés.
- Nom:
documentation- Type : Texte libre
- Échelle de déclaration : Racine du paramètre
- Exemples :
documentation: | À partir de 2014, des seuils spécifiques (célibataire, couple) sont employés pour le calcul de la décote. documentation: | 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. documentation: | 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.
description: Montant (en % de la BMAF) de l'Allocation d'adoption (AA), une des prestations sociales familiales pour la petite enfance
values:
1995-01-01:
value: 0.3
1996-08-01:
value: 0.4595
2007-01-01:
value: null
metadata:
ux_name: Montant
last_review: "2022-02-22"
description_en: "Adoption allowance (AA): General conditions and amounts"
ipp_csv_id: aa_montant
unit: BMAF
reference:
1996-08-01:
- title: Article 197, I.1. du Code général des impôts
href: https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000042907517
- title: Décret n°2020-769 du 24/06/2020, art. 2
href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514
2007-01-01:
- title: Décret n°2020-1453 du 27 novembre 2020
href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042574431
official_journal_date:
1995-01-01: "1995-02-17"
1996-08-01: "1996-07-06"
2007-01-01: "2003-12-19"
notes:
1995-01-01:
- title: Pas cumulable avec l'ASF. Pour les enfants nés à partir du 01/01/1995; Le décret 95-165 du 16/02/1995 crée l'Allocation à l'Adoption
1996-08-01:
- title: Loi qui assure la parité des droits sociaux attachés à la naissance et à l'adoption.; Loi qui aligne l'allocation d'adoption sur l'APJE. Mêmes montants et mêmes plafonds (par contre, durée de l'aide, à fixer par décret).
documentation: |
Après 2007, la PAJE remplace en partie l'allocation d'adoption. Mais, transition progressive, jusqu'à fin 2006 (cf. art. 60, VIII de la loi)
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.
Est-ce que je peux ajouter une reference qui a une date postérieure à la dernière valeur du paramètre ?
Exemples:
- La référence (article) d'une valeur a changé, mais pas sa valeur.
- La seule référence en ma possession est postérieure à la dernière valeur.
- Le dispositif a changé (réforme) mais pas cette valeur.
- 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.
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 ///
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).
- 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.