search

openfisca / openfisca-france

French tax and benefit system for OpenFisca
https://openfisca.org/fr
253 stars 96 forks source link

Document entities #807

Closed MattiSG closed 5 years ago

MattiSG commented 6 years ago

Explain what is the use and give examples of usage of all entities in docstrings.

Related to https://github.com/openfisca/legislation-explorer/issues/80.

MattiSG commented 6 years ago

@benjello On prévoit de présenter la doc sur les entités dans l'explorateur de législation, si tu as déjà un peu de texte sur le sujet (ou peut en rédiger ;) ) on sera preneurs :)

benjello commented 6 years ago

@MattiSG : je vais faire une proposition. Je mets cela où ?

MattiSG commented 6 years ago

Excellent !! L'idéal est de faire direct une PR en ajoutant des docstrings dans les entités 😃

  from openfisca_core.entities import build_entity
+ '''
+ Une Famille représente…
+ Elle s'utilise de la manière suivante :
+ …
+ Elle diffère d'un Ménage car…
+ '''
  Famille = build_entity(
    key = "famille",
    plural = "familles",
    label = u'Famille',
fpagnoux commented 6 years ago

Partially fixed by https://github.com/openfisca/openfisca-france/pull/811

benjello commented 6 years ago

@MattiSG, @maukoquiroga @fpagnoux : peut-on fermer ce ticket ? Si vous voyez des améliorations à apporter ne pas hésiter à les lister.

bonjourmauko commented 6 years ago

(Je me permet d'écrire en français ici)

Si je bien compris, et on regardant le code, nous avons déjà documenté :

mais, il reste encore à documenter :

Est-ce correct ? cc @benjello

benjello commented 6 years ago

Yep

fpagnoux commented 6 years ago

Les individus, il n'y a sans doute pas grand chose à dire, à par peut-être préciser que ce sont des personnes physiques.

Les familles oui, mais c'est une entité qui est assez mal définie. Le concept vient de la CAF, mais je ne suis pas sûr que la définition soit explicitée quelque part. En gros c'est un adulte, un conjoint qui "partage la vie" de cette personne, et des enfants qui sont "à leur charge". Le tout sans contrainte d'habiter sous le même toit, ni d'être dans le même foyer fiscal, et parfois à l'appréciation du contrôleur de la CAF.

@benjello est-ce que tu as une définition plus rigoureuse?

benjello commented 6 years ago

On pourrait traduire famille par foyer social, l'entité au nom duquel on touche des prestations sociales et/ou des minimas sociaux. Le problème est qu'il y a un foyer social pour la CAF concernant les familles, mais il diffère de celui pris en compte pour le RSA, l'ASPA etc. L'idéal serait d'avoir une entité par chacun de ce cas. Mais c'est lourd à moins d'avoir un moyen meta de définir ces entités par des liens entre les individus.

fpagnoux commented 6 years ago

On pourrait traduire famille par foyer social, l'entité au nom duquel on touche des prestations sociales et/ou des minimas sociaux. Le problème est qu'il y a un foyer social pour la CAF concernant les familles, mais il diffère de celui pris en compte pour le RSA, l'ASPA etc.

Oui. En pratique la Famille actuelle est l'union de tous les foyers sociaux de toutes les prestations, et ensuite chaque prestation ne prend en compte qu'une sous-partie des individus.

L'idéal serait d'avoir une entité par chacun de ce cas. Mais c'est lourd à moins d'avoir un moyen meta de définir ces entités par des liens entre les individus.

Une entité par prestation, ça semble en effet très lourd (les 3 entités sont déjà parfois pénibles à gérer) et ça ne colle pas avec des entités définies en avance : la composition du foyer social d'une prestation peut dépendre des ages, des revenus, etc.

benjello commented 6 years ago

C'est pour tant ce que font souvent les autres modèles de microsimulation. Il définissent l'entité au moment du calcul de la prestation. Ce que l'on fait en partie en prenant un sous ensemble de famille.

Morendil commented 5 years ago

Je pense que les besoins en termes de documentation sont atteints, je rejoins l'idée qu'on sait ce que sont un individu et une famille sans avoir besoin de plus d'explication (ou alors il faut rentrer dans des détails qui vont sans doute dépasser la demande implicite de l'usager faisant une recherche ou lisant le fichier de définition).

Il me semble qu'on pourrait améliorer l'UX de la recherche dans le legislation explorer (rien ne distingue les entités, les variables et les paramètres) et qu'il serait intéressant de tester l'intérêt d'une navigation entité -> variables (rattachées à cette entité) comme suggéré par Matti initialement ("give examples of usage"). Plus largement je m'interroge sur ce que sont les "jobs to be done" par le legislation explorer.

Mais ces questions dépassent le cadre de l'issue, et il me semble que la conversation a déjà dérivé, je ferme par souci de noter que quelque chose a été résolu.