<commit_before># Periods and Instants

A `Period` can be a day, a month, a year, `n` successive days, `n` successive months, `n` successive years or the eternity.

The smallest unit for OpenFisca periods is the **day**. Therefore:

- All periods are presumed to start on the first day of their first month.
- A period cannot be smaller than a day.

An `Instant` is a specific day, such as a cutoff date.


## Periods creation

To create a `Period`, you can use a simplified syntax. Here is an example for a period of one year covering `2015`:

```py
from openfisca_core import periods

period_2015 = periods.period('2015')
```

Internally, periods are stored as:
- a start `Instant`
- a unit (`DAY`, `MONTH`, `YEAR`)
- a quantity of units.

Thus, the previous example could also be defined as:

```py
from openfisca_core import periods

period_2015 = periods.Period(('month', periods.Instant((2015, 1, 1)), 12))
```

## Periods in simulations

In OpenFisca inputs, periods are encoded in strings. All the valid period formats are referenced in this table:

| Period format     | Period type     | Example             | Represents                                       | Disambiguation                                                        |
|-------------------|-----------------|---------------------|--------------------------------------------------|-----------------------------------------------------------------------|
| `AAAA`            | Calendar year   | `'2010'`            | The year 2010.                                   | From the 1st of January 2010 to the 31st of December 2010, inclusive. |
| `AAAA-MM`         | Month           | `'2010-04'`         | The month of April 2010.                         | From the 1st of April 2010 to the 30th of April 2010, inclusive.      |
| `year:AAAA-MM`    | Rolling year    | `'year:2010-04'`    | The 1 year period starting in April 2010. | From the 1st of April 2010 to the 31st of March 2011, inclusive       |
| `year:AAAA:N`     | N years         | `'year:2010:3'`     | The years 2010, 2011 and 2012.                   | From the 1st of January 2010 to the 31st of December 2012, inclusive. |
| `year:AAAA-MM:N`  | N rolling years | `'year:2010-04:3'`  | The three years period starting in April 2010.   | From the 1st of April 2010 to the 31st of March 2013, inclusive.      |
| `month:AAAA-MM:N` | N months        | `'month:2010-04:3'` | The three months from April to June 2010.        | From the 1st of April 2010 to the 30th of June 2010, inclusive.       |
| `day:AAAA-MM-DD:N` | N days        | `'day:2010-04-01:30'` | The thirty days of April 2010. | From the 1st of April 2010 to the 30th of April 2010, inclusive.       |
| `ETERNITY` | Forever        | `ETERNITY` | All of time.        | All past, present and future day, month or year|

This [YAML test](writing_yaml_tests.md) on `income_tax` evolution over time shows periods' impact on a variable:

```yaml
- name: Income tax over time
  period: 2016-01
  input:
    salary:
      year:2014:3: 100000 # This person earned 100,000 between 2014 and 2016
  output:
    income_tax:
      2014-01: 388.8889
      2015-01: 416.6667 # The income tax rate changes in 2015
      2016-01: 416.6667
      2017-01: 0 # The salary is not set for this period and defaults to 0
```

This syntax could also be used in Python.  
This example sets salaries for two persons:

```py
# Each person earned 60,000 between 2014 and 2016
simulation.set_input('salary', 'year:2014:3', [60000.0, 60000.0])
```

The same syntax could also be used to calculate a variable when the variable has a [set_input](35_periods.html#set-input-automatically-process-variable-inputs-defined-for-periods-not-matching-the-definition-period) attribute:

```py
simulation.set_input('salary', 'year:2014:3', [60000.0, 60000.0])

one_month_salaries = simulation.calculate('salary', 'month:2014-01:1')
print(one_month_salaries)  # prints [1666.6666 1666.6666]
```


## Periods in variable definition

```py
...
from openfisca_core.periods import MONTH  # openfisca_core is the architecture of OpenFisca

class salary(Variable):
    value_type = float
    entity = Person
    label = u"Salary for a month"
    definition_period = MONTH

    def formula(person, period):
        ...
```

Most of the values calculated in OpenFisca, such as `income_tax`, and `housing_allowance`, can change over time.

Therefore, all OpenFisca variables have a `definition_period` attribute:
  - `definition_period = DAY`: The variable may have a different value each day.
  - `definition_period = MONTH`: The variable may have a different value each month. *For example*, the salary of a person. When `formula` is executed, the parameter `period` will always be a whole month. Trying to compute `salary` with a period that is not a month will raise an error before entering `formula`.
  - `definition_period = YEAR`: The variable is defined for a year or it has always the same value every months of a year. *For example*, if taxes are to be paid yearly, the corresponding variable is yearly. When `formula` is executed, the parameter `period` will always be a whole year (from January 1st to December 31th).
  - `definition_period = ETERNITY`: The value of the variable is constant. *For example*, the date of birth of a person never changes. `period` is still the 2nd parameter of `formula`. However when `formula` is executed, the parameter `period` can be anything and it should not be used.

Each formula calculates the value of a variable for a period the size of **the given definition period**. This period is always the second argument of the formulas.

## Periods in formulas

### Calculate dependencies for a period different than the variable's `definition_period`
<commit_msg>Move periods section in same page<commit_after># Periods and Instants

A `Period` can be a day, a month, a year, `n` successive days, `n` successive months, `n` successive years or the eternity.

The smallest unit for OpenFisca periods is the **day**. Therefore:

- All periods are presumed to start on the first day of their first month.
- A period cannot be smaller than a day.

An `Instant` is a specific day, such as a cutoff date.

## Periods in simulations

In OpenFisca inputs, periods are encoded in strings. All the valid period formats are referenced in this table:

| Period format     | Period type     | Example             | Represents                                       | Disambiguation                                                        |
|-------------------|-----------------|---------------------|--------------------------------------------------|-----------------------------------------------------------------------|
| `AAAA`            | Calendar year   | `'2010'`            | The year 2010.                                   | From the 1st of January 2010 to the 31st of December 2010, inclusive. |
| `AAAA-MM`         | Month           | `'2010-04'`         | The month of April 2010.                         | From the 1st of April 2010 to the 30th of April 2010, inclusive.      |
| `year:AAAA-MM`    | Rolling year    | `'year:2010-04'`    | The 1 year period starting in April 2010. | From the 1st of April 2010 to the 31st of March 2011, inclusive       |
| `year:AAAA:N`     | N years         | `'year:2010:3'`     | The years 2010, 2011 and 2012.                   | From the 1st of January 2010 to the 31st of December 2012, inclusive. |
| `year:AAAA-MM:N`  | N rolling years | `'year:2010-04:3'`  | The three years period starting in April 2010.   | From the 1st of April 2010 to the 31st of March 2013, inclusive.      |
| `month:AAAA-MM:N` | N months        | `'month:2010-04:3'` | The three months from April to June 2010.        | From the 1st of April 2010 to the 30th of June 2010, inclusive.       |
| `day:AAAA-MM-DD:N` | N days        | `'day:2010-04-01:30'` | The thirty days of April 2010. | From the 1st of April 2010 to the 30th of April 2010, inclusive.       |
| `ETERNITY` | Forever        | `ETERNITY` | All of time.        | All past, present and future day, month or year|

This [YAML test](writing_yaml_tests.md) on `income_tax` evolution over time shows periods' impact on a variable:

```yaml
- name: Income tax over time
  period: 2016-01
  input:
    salary:
      year:2014:3: 100000 # This person earned 100,000 between 2014 and 2016
  output:
    income_tax:
      2014-01: 388.8889
      2015-01: 416.6667 # The income tax rate changes in 2015
      2016-01: 416.6667
      2017-01: 0 # The salary is not set for this period and defaults to 0
```

This syntax could also be used in Python.  
This example sets salaries for two persons:

```py
# Each person earned 60,000 between 2014 and 2016
simulation.set_input('salary', 'year:2014:3', [60000.0, 60000.0])
```

The same syntax could also be used to calculate a variable when the variable has a [set_input](35_periods.html#set-input-automatically-process-variable-inputs-defined-for-periods-not-matching-the-definition-period) attribute:

```py
simulation.set_input('salary', 'year:2014:3', [60000.0, 60000.0])

one_month_salaries = simulation.calculate('salary', 'month:2014-01:1')
print(one_month_salaries)  # prints [1666.6666 1666.6666]
```

## Manipulating Period objects in Python

To create a `Period`, you can use a simplified syntax. Here is an example for a period of one year covering `2015`:

```py
from openfisca_core import periods

period_2015 = periods.period('2015')
```

> Internally, periods are stored as:
> - a start `Instant`
> - a unit (`DAY`, `MONTH`, `YEAR`)
> - a quantity of units.

Thus, the previous example could also be defined as:

```py
from openfisca_core import periods

period_2015 = periods.Period(('month', periods.Instant((2015, 1, 1)), 12))
```

## Periods in variable definition

```py
...
from openfisca_core.periods import MONTH  # openfisca_core is the architecture of OpenFisca

class salary(Variable):
    value_type = float
    entity = Person
    label = u"Salary for a month"
    definition_period = MONTH

    def formula(person, period):
        ...
```

Most of the values calculated in OpenFisca, such as `income_tax`, and `housing_allowance`, can change over time.

Therefore, all OpenFisca variables have a `definition_period` attribute:
  - `definition_period = DAY`: The variable may have a different value each day.
  - `definition_period = MONTH`: The variable may have a different value each month. *For example*, the salary of a person. When `formula` is executed, the parameter `period` will always be a whole month. Trying to compute `salary` with a period that is not a month will raise an error before entering `formula`.
  - `definition_period = YEAR`: The variable is defined for a year or it has always the same value every months of a year. *For example*, if taxes are to be paid yearly, the corresponding variable is yearly. When `formula` is executed, the parameter `period` will always be a whole year (from January 1st to December 31th).
  - `definition_period = ETERNITY`: The value of the variable is constant. *For example*, the date of birth of a person never changes. `period` is still the 2nd parameter of `formula`. However when `formula` is executed, the parameter `period` can be anything and it should not be used.

Each formula calculates the value of a variable for a period the size of **the given definition period**. This period is always the second argument of the formulas.

## Periods in formulas

### Calculate dependencies for a period different than the variable's `definition_period`

{'fraction_non_alphanumeric': 0.11958120619537943, 'fraction_numerical': 0.05901185428744484, 'mean_word_length': 2.7319987084275104, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1358847', 'n_tokens_mistral': 3816, 'n_tokens_neox': 3139, 'n_words': 1450}