{"action":"created","comment":{"url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/comments/130819978","pull_request_review_id":53725152,"id":130819978,"diff_hunk":"@@ -51,76 +53,111 @@ we get the output:\n     flat_tax_on_salary:\n         2016-01: 500\n         2015-12: 400\n-        ...\n         2015-01: 400\n         2014-12: 440\n-        ...\n         2014-01: 440\n ```\n \n [Read more about how to code parameters](./legislation_parameters.md#parameters-and-time).\n \n-## Variable defined only for a specific time intervale\n+## Formula evolving over time\n+\n+Some fiscal or benefit mechanism significantly evolve over time, with bigger changes than a simple parameter adjustement.\n \n-As the legislation evolves, some fiscal or benefit mechanism appear and disapear. When creating a variable, you can specify the attribute `start_date` and `stop_date` to defines in which time intervale this variable make sense.\n+For instance, let's assume that from the 1st of Jan. 2017, our previous `flat_tax_on_salary` will not be applied on the first `1000` earned by the person.\n \n-When called outside of its definition intervale, a variable will **not** execute its formula and instead **return its default value**.\n+We implement this rule by adding a new formula to our variable, and _dating_ it:\n \n-For instance:\n ```py\n class flat_tax_on_salary(Variable):\n     column = FloatCol\n     entity = Person\n     label = u\"Individualized and monthly paid tax on salaries\"\n-    start_date = date(2014, 01, 01)\n     definition_period = MONTH\n \n-    def function(person, period, legislation):\n-        ...\n+    def formula_2017(self, simulation, period):\n+        salary = person('salary', period)\n+        salary_above_1000 = min_(salary - 1000, 0)\n+        return salary_above_1000 * legislation(period).taxes.salary.rate\n \n-class progressive_income_tax(Variable):\n-    column = FloatCol\n-    entity = Person\n-    label = u\"Former tax replaced by the flat tax on the 1st of Jan 2014\"\n-    stop_date = date(2013, 12, 31)\n-    definition_period = MONTH\n+    def formula(self, simulation, period):\n+        salary = person('salary', period)\n \n-    def function(person, period, legislation):\n-        ...\n+        return salary * legislation(period).taxes.salary.rate\n ```\n \n+If the `flat_tax_on_salary` is calculated for a person **before** the 31st of Dec. 2016 (included), `formula` is used. If it is called **after** the 1st of Jan 2017 (included), `formula_2017` is used.\n+\n Note that:\n-- A variable can of course have both a `start_date` and a `stop_date`.\n-- The `stop_date` is the last day a formula is valid, and not the first day it is not valid anymore.\n+- A formula name must always start with `formula`.\n+- To define a starting date for a formula, we add to its name a suffix made of an underscore followed by a date.\n+  - For instance, `formula_2017_01_01` is active from the 1st of Jan. 2017.\n - When defining a date, the month is given **before** the day.\n+- When no month or day is specified, OpenFisca uses '01' as default value.\n+  - For instance, `formula_2017` is equivalent to `formula_2017_01_01`.\n+- If no date is specified for a formula, OpenFisca will consider that this formula has been active since the dawn of time (or more precisely, since `0001-01-01`, as Python does not handle B.C. dates).\n+  - For instance, `formula` is active on `2010`.\n+- A formula is active until another formula, starting later, becomes active and replaces it.\n+  - For instance, `formula` is active until `2016-12-31` (included). On the day after, `2017-01-01`, `formula_2017` becomes active, and `formula` becomes inactive.\n \n-## Formula evolving over time\n \n-Some fiscal or benefit mechanism significantly evolve over time, with bigger changes than a simple parameter adjustement.\n+## Introduction of a formula\n+\n+In our previous example, we assumed that `flat_tax_on_salary` had _always_ had a formula, since the dawn of time. This is a reasonable hypothesis if we are only interested in running computations for recent years.\n \n-For instance, let's assume that from the 1st of Jan. 2017, our previous `flat_tax_on_salary` will not apply on the first `1000` earned by the person. We can implement this rule with a `DatedVariable`:\n+But most fiscal and benefit mechanisms have been introduced at some point. Let's for instance assume that our `flat_tax_on_salary` only appeared in our legislation on the 1st of June 2005. \n+\n+This is easily implemented by _dating_ the two formulas:\n \n ```py\n-class flat_tax_on_salary(DatedVariable):\n+class flat_tax_on_salary(Variable):\n     column = FloatCol\n     entity = Person\n     label = u\"Individualized and monthly paid tax on salaries\"\n     definition_period = MONTH\n \n-    @dated_function(start = date(2017, 1, 1))\n-    def function_2017(person, period, legislation):\n+    def formula_2017(self, simulation, period):\n         salary = person('salary', period)\n         salary_above_1000 = min_(salary - 1000, 0)\n         return salary_above_1000 * legislation(period).taxes.salary.rate\n \n-    @dated_function(start = date(2014, 01, 01), stop = date(2016, 12, 31))\n-    def function_2014(person, period, legislation):\n+    def formula_2005_06(self, simulation, period):\n         salary = person('salary', period)\n \n         return salary * legislation(period).taxes.salary.rate\n ```\n \n+Only a few characters changed in comparison with the last example: the suffix `_2005_06` has been added to the second formula name.\n+\n+Note that if `flat_tax_on_salary` is calculated **before** `2005-05-31` (included), _none_ of the two formulas is used, as they are _both inactive_ at this time. Instead, **the variable [default value](../variables.md#default-values) is returned**.\n+\n+\n+## Variable defined until a specific date","path":"coding-the-legislation/40_legislation_evolutions.md","position":156,"original_position":156,"commit_id":"ab93cab773fff77f419d6e92dd55b3a4f0bb2f1d","original_commit_id":"ab93cab773fff77f419d6e92dd55b3a4f0bb2f1d","user":{"login":"Anna-Livia","id":13916213,"avatar_url":"https://avatars0.githubusercontent.com/u/13916213?v=4","gravatar_id":"","url":"https://api.github.com/users/Anna-Livia","html_url":"https://github.com/Anna-Livia","followers_url":"https://api.github.com/users/Anna-Livia/followers","following_url":"https://api.github.com/users/Anna-Livia/following{/other_user}","gists_url":"https://api.github.com/users/Anna-Livia/gists{/gist_id}","starred_url":"https://api.github.com/users/Anna-Livia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Anna-Livia/subscriptions","organizations_url":"https://api.github.com/users/Anna-Livia/orgs","repos_url":"https://api.github.com/users/Anna-Livia/repos","events_url":"https://api.github.com/users/Anna-Livia/events{/privacy}","received_events_url":"https://api.github.com/users/Anna-Livia/received_events","type":"User","site_admin":false},"body":"## Variable end","created_at":"2017-08-02T08:51:40Z","updated_at":"2017-08-02T09:04:14Z","html_url":"https://github.com/openfisca/openfisca-doc/pull/83#discussion_r130819978","pull_request_url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83","_links":{"self":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/comments/130819978"},"html":{"href":"https://github.com/openfisca/openfisca-doc/pull/83#discussion_r130819978"},"pull_request":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83"}}},"pull_request":{"url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83","id":131110451,"html_url":"https://github.com/openfisca/openfisca-doc/pull/83","diff_url":"https://github.com/openfisca/openfisca-doc/pull/83.diff","patch_url":"https://github.com/openfisca/openfisca-doc/pull/83.patch","issue_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues/83","number":83,"state":"open","locked":false,"title":"Syntax evolution on dated variables and formulas","user":{"login":"sandcha","id":6567910,"avatar_url":"https://avatars1.githubusercontent.com/u/6567910?v=4","gravatar_id":"","url":"https://api.github.com/users/sandcha","html_url":"https://github.com/sandcha","followers_url":"https://api.github.com/users/sandcha/followers","following_url":"https://api.github.com/users/sandcha/following{/other_user}","gists_url":"https://api.github.com/users/sandcha/gists{/gist_id}","starred_url":"https://api.github.com/users/sandcha/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sandcha/subscriptions","organizations_url":"https://api.github.com/users/sandcha/orgs","repos_url":"https://api.github.com/users/sandcha/repos","events_url":"https://api.github.com/users/sandcha/events{/privacy}","received_events_url":"https://api.github.com/users/sandcha/received_events","type":"User","site_admin":false},"body":"Fixes #82 \r\n\r\nUpdates function names to formula\r\nExplains variable `end` attribute usage\r\nExplains formula starting date usage\r\nCleans outdated syntax\r\n\r\n-----\r\n\r\nEDIT by @fpagnoux: Replace Connected by Fixes","created_at":"2017-07-18T14:59:06Z","updated_at":"2017-08-02T09:04:14Z","closed_at":null,"merged_at":null,"merge_commit_sha":"90fec86ce6695f3b87a6931d56688f3d7358f492","assignee":null,"assignees":[],"requested_reviewers":[],"milestone":null,"commits_url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83/commits","review_comments_url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83/comments","review_comment_url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/comments{/number}","comments_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues/83/comments","statuses_url":"https://api.github.com/repos/openfisca/openfisca-doc/statuses/ab93cab773fff77f419d6e92dd55b3a4f0bb2f1d","head":{"label":"openfisca:formula-evolution-82","ref":"formula-evolution-82","sha":"ab93cab773fff77f419d6e92dd55b3a4f0bb2f1d","user":{"login":"openfisca","id":1794404,"avatar_url":"https://avatars0.githubusercontent.com/u/1794404?v=4","gravatar_id":"","url":"https://api.github.com/users/openfisca","html_url":"https://github.com/openfisca","followers_url":"https://api.github.com/users/openfisca/followers","following_url":"https://api.github.com/users/openfisca/following{/other_user}","gists_url":"https://api.github.com/users/openfisca/gists{/gist_id}","starred_url":"https://api.github.com/users/openfisca/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/openfisca/subscriptions","organizations_url":"https://api.github.com/users/openfisca/orgs","repos_url":"https://api.github.com/users/openfisca/repos","events_url":"https://api.github.com/users/openfisca/events{/privacy}","received_events_url":"https://api.github.com/users/openfisca/received_events","type":"Organization","site_admin":false},"repo":{"id":42248086,"name":"openfisca-doc","full_name":"openfisca/openfisca-doc","owner":{"login":"openfisca","id":1794404,"avatar_url":"https://avatars0.githubusercontent.com/u/1794404?v=4","gravatar_id":"","url":"https://api.github.com/users/openfisca","html_url":"https://github.com/openfisca","followers_url":"https://api.github.com/users/openfisca/followers","following_url":"https://api.github.com/users/openfisca/following{/other_user}","gists_url":"https://api.github.com/users/openfisca/gists{/gist_id}","starred_url":"https://api.github.com/users/openfisca/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/openfisca/subscriptions","organizations_url":"https://api.github.com/users/openfisca/orgs","repos_url":"https://api.github.com/users/openfisca/repos","events_url":"https://api.github.com/users/openfisca/events{/privacy}","received_events_url":"https://api.github.com/users/openfisca/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/openfisca/openfisca-doc","description":"User guide of OpenFisca","fork":false,"url":"https://api.github.com/repos/openfisca/openfisca-doc","forks_url":"https://api.github.com/repos/openfisca/openfisca-doc/forks","keys_url":"https://api.github.com/repos/openfisca/openfisca-doc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/openfisca/openfisca-doc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/openfisca/openfisca-doc/teams","hooks_url":"https://api.github.com/repos/openfisca/openfisca-doc/hooks","issue_events_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues/events{/number}","events_url":"https://api.github.com/repos/openfisca/openfisca-doc/events","assignees_url":"https://api.github.com/repos/openfisca/openfisca-doc/assignees{/user}","branches_url":"https://api.github.com/repos/openfisca/openfisca-doc/branches{/branch}","tags_url":"https://api.github.com/repos/openfisca/openfisca-doc/tags","blobs_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/refs{/sha}","trees_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/openfisca/openfisca-doc/statuses/{sha}","languages_url":"https://api.github.com/repos/openfisca/openfisca-doc/languages","stargazers_url":"https://api.github.com/repos/openfisca/openfisca-doc/stargazers","contributors_url":"https://api.github.com/repos/openfisca/openfisca-doc/contributors","subscribers_url":"https://api.github.com/repos/openfisca/openfisca-doc/subscribers","subscription_url":"https://api.github.com/repos/openfisca/openfisca-doc/subscription","commits_url":"https://api.github.com/repos/openfisca/openfisca-doc/commits{/sha}","git_commits_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/commits{/sha}","comments_url":"https://api.github.com/repos/openfisca/openfisca-doc/comments{/number}","issue_comment_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues/comments{/number}","contents_url":"https://api.github.com/repos/openfisca/openfisca-doc/contents/{+path}","compare_url":"https://api.github.com/repos/openfisca/openfisca-doc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/openfisca/openfisca-doc/merges","archive_url":"https://api.github.com/repos/openfisca/openfisca-doc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/openfisca/openfisca-doc/downloads","issues_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues{/number}","pulls_url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls{/number}","milestones_url":"https://api.github.com/repos/openfisca/openfisca-doc/milestones{/number}","notifications_url":"https://api.github.com/repos/openfisca/openfisca-doc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/openfisca/openfisca-doc/labels{/name}","releases_url":"https://api.github.com/repos/openfisca/openfisca-doc/releases{/id}","deployments_url":"https://api.github.com/repos/openfisca/openfisca-doc/deployments","created_at":"2015-09-10T14:03:10Z","updated_at":"2017-06-06T08:44:54Z","pushed_at":"2017-08-01T22:49:01Z","git_url":"git://github.com/openfisca/openfisca-doc.git","ssh_url":"git@github.com:openfisca/openfisca-doc.git","clone_url":"https://github.com/openfisca/openfisca-doc.git","svn_url":"https://github.com/openfisca/openfisca-doc","homepage":"https://doc.openfisca.fr/","size":1535,"stargazers_count":7,"watchers_count":7,"language":null,"has_issues":true,"has_projects":false,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":5,"mirror_url":null,"open_issues_count":8,"forks":5,"open_issues":8,"watchers":7,"default_branch":"master"}},"base":{"label":"openfisca:master","ref":"master","sha":"17e2fd82e013707028141362645c266b0adc0b29","user":{"login":"openfisca","id":1794404,"avatar_url":"https://avatars0.githubusercontent.com/u/1794404?v=4","gravatar_id":"","url":"https://api.github.com/users/openfisca","html_url":"https://github.com/openfisca","followers_url":"https://api.github.com/users/openfisca/followers","following_url":"https://api.github.com/users/openfisca/following{/other_user}","gists_url":"https://api.github.com/users/openfisca/gists{/gist_id}","starred_url":"https://api.github.com/users/openfisca/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/openfisca/subscriptions","organizations_url":"https://api.github.com/users/openfisca/orgs","repos_url":"https://api.github.com/users/openfisca/repos","events_url":"https://api.github.com/users/openfisca/events{/privacy}","received_events_url":"https://api.github.com/users/openfisca/received_events","type":"Organization","site_admin":false},"repo":{"id":42248086,"name":"openfisca-doc","full_name":"openfisca/openfisca-doc","owner":{"login":"openfisca","id":1794404,"avatar_url":"https://avatars0.githubusercontent.com/u/1794404?v=4","gravatar_id":"","url":"https://api.github.com/users/openfisca","html_url":"https://github.com/openfisca","followers_url":"https://api.github.com/users/openfisca/followers","following_url":"https://api.github.com/users/openfisca/following{/other_user}","gists_url":"https://api.github.com/users/openfisca/gists{/gist_id}","starred_url":"https://api.github.com/users/openfisca/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/openfisca/subscriptions","organizations_url":"https://api.github.com/users/openfisca/orgs","repos_url":"https://api.github.com/users/openfisca/repos","events_url":"https://api.github.com/users/openfisca/events{/privacy}","received_events_url":"https://api.github.com/users/openfisca/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/openfisca/openfisca-doc","description":"User guide of OpenFisca","fork":false,"url":"https://api.github.com/repos/openfisca/openfisca-doc","forks_url":"https://api.github.com/repos/openfisca/openfisca-doc/forks","keys_url":"https://api.github.com/repos/openfisca/openfisca-doc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/openfisca/openfisca-doc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/openfisca/openfisca-doc/teams","hooks_url":"https://api.github.com/repos/openfisca/openfisca-doc/hooks","issue_events_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues/events{/number}","events_url":"https://api.github.com/repos/openfisca/openfisca-doc/events","assignees_url":"https://api.github.com/repos/openfisca/openfisca-doc/assignees{/user}","branches_url":"https://api.github.com/repos/openfisca/openfisca-doc/branches{/branch}","tags_url":"https://api.github.com/repos/openfisca/openfisca-doc/tags","blobs_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/refs{/sha}","trees_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/openfisca/openfisca-doc/statuses/{sha}","languages_url":"https://api.github.com/repos/openfisca/openfisca-doc/languages","stargazers_url":"https://api.github.com/repos/openfisca/openfisca-doc/stargazers","contributors_url":"https://api.github.com/repos/openfisca/openfisca-doc/contributors","subscribers_url":"https://api.github.com/repos/openfisca/openfisca-doc/subscribers","subscription_url":"https://api.github.com/repos/openfisca/openfisca-doc/subscription","commits_url":"https://api.github.com/repos/openfisca/openfisca-doc/commits{/sha}","git_commits_url":"https://api.github.com/repos/openfisca/openfisca-doc/git/commits{/sha}","comments_url":"https://api.github.com/repos/openfisca/openfisca-doc/comments{/number}","issue_comment_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues/comments{/number}","contents_url":"https://api.github.com/repos/openfisca/openfisca-doc/contents/{+path}","compare_url":"https://api.github.com/repos/openfisca/openfisca-doc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/openfisca/openfisca-doc/merges","archive_url":"https://api.github.com/repos/openfisca/openfisca-doc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/openfisca/openfisca-doc/downloads","issues_url":"https://api.github.com/repos/openfisca/openfisca-doc/issues{/number}","pulls_url":"https://api.github.com/repos/openfisca/openfisca-doc/pulls{/number}","milestones_url":"https://api.github.com/repos/openfisca/openfisca-doc/milestones{/number}","notifications_url":"https://api.github.com/repos/openfisca/openfisca-doc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/openfisca/openfisca-doc/labels{/name}","releases_url":"https://api.github.com/repos/openfisca/openfisca-doc/releases{/id}","deployments_url":"https://api.github.com/repos/openfisca/openfisca-doc/deployments","created_at":"2015-09-10T14:03:10Z","updated_at":"2017-06-06T08:44:54Z","pushed_at":"2017-08-01T22:49:01Z","git_url":"git://github.com/openfisca/openfisca-doc.git","ssh_url":"git@github.com:openfisca/openfisca-doc.git","clone_url":"https://github.com/openfisca/openfisca-doc.git","svn_url":"https://github.com/openfisca/openfisca-doc","homepage":"https://doc.openfisca.fr/","size":1535,"stargazers_count":7,"watchers_count":7,"language":null,"has_issues":true,"has_projects":false,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":5,"mirror_url":null,"open_issues_count":8,"forks":5,"open_issues":8,"watchers":7,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83"},"html":{"href":"https://github.com/openfisca/openfisca-doc/pull/83"},"issue":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/issues/83"},"comments":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/issues/83/comments"},"review_comments":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83/comments"},"review_comment":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/pulls/83/commits"},"statuses":{"href":"https://api.github.com/repos/openfisca/openfisca-doc/statuses/ab93cab773fff77f419d6e92dd55b3a4f0bb2f1d"}}}}
{"actor":{"display_login":"Anna-Livia"}}