Simulation suggestions and linting

source/simulate/analyse-simulation.md

@@ -1,6 +1,6 @@
 # Analysing or debugging a simulation
 
-To understand how a result was calculated when simulating with the Python API, intermediate variables and parameters have been taken into account.
+To understand how a result was calculated when simulating with the Python API, analysis of the intermediate variables and parameters have been taken into account.
 
 > To trace a simulation calculation with the web API, please see [/trace endpoint documentation](../openfisca-web-api/trace-simulation.md).
 
@@ -54,12 +54,12 @@ TEST_CASE = {
         'Javier': {}
     },
     'households': {
-        'hh1': {
+        'household_1': {
             'children': ['Leila'], 
             'parents': ['Ari', 'Paul'],
             'rent': {'2011-01': 300}
         },
-        'hh2': {'parents': ['Javier']}
+        'household_2': {'parents': ['Javier']}
     },
 }
 ```
@@ -71,7 +71,7 @@ The previous code example would give us this output:
     rent<2011-01> >> [300.   0.]
 ```
 
-The `rent` variable is indented to the right relative to `housing_allowance` indicating that `housing_allowance` variable called the `rent` calculation. It was called on the same period: '2011-01'. The [rent variable](https://legislation.demo.openfisca.org/rent)'s value was an input value given by the `TEST_CASE` and was returned to `housing_allowance`. The [housing_allowance variable](https://legislation.demo.openfisca.org/housing_allowance) used the `rent` value to calculate `housing_allowance` for its two households (`hh1` and `hh2`): `[75.  0.]`
+The `rent` variable is indented to the right relative to `housing_allowance` indicating that `housing_allowance` variable called the `rent` calculation. It was called on the same period: '2011-01'. The [rent variable](https://legislation.demo.openfisca.org/rent)'s value was an input value given by the `TEST_CASE` and was returned to `housing_allowance`. The [housing_allowance variable](https://legislation.demo.openfisca.org/housing_allowance) has a valid formula for '2011-01' which used the `rent` value to calculate `housing_allowance` for its two households (`household_1` and `household_2`): `[75.  0.]`
 
 Thus, on the left side of the double chevrons, the trace can be read from top to bottom to see the dependencies between the variables. The right side can be read from bottom to top to see how the simulation result is built.
 

source/simulate/profile-simulation.md

@@ -1,4 +1,4 @@
-# Profiling a simulation's performance 
+# Profiling a simulation's performance
 
 The following outlines how to tackle a simulation that is running too slow.
 

source/simulate/replicate-simulation-inputs.md

@@ -13,8 +13,8 @@ The following example does this by adding an "axes" entry to a test case:
 WITH_AXES = {
     'persons': {'Ari': {}, 'Paul': {}, 'Leila': {}, 'Javier': {}},
     'households': {
-        'hh1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
-        'hh2': {'parents': ['Javier']}
+        'household_1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
+        'household_2': {'parents': ['Javier']}
         },
     'axes': [[{'count':10, 'name':'salary', 'min':0, 'max':3000, 'period':'2018-11'}]]
     }
@@ -25,7 +25,7 @@ simulation = simulation_builder.build_from_entities(tax_benefit_system, WITH_AXE
 
 Be careful to note the structure of the "axes" field: an **array of arrays** of axis objects.
 
-This example describes one household with two parents and one child, plus a second household which is in fact a single adult person. 
+This example describes one household with two parents and one child, plus a second household which is in fact a single adult person.
 With this simulation the following code indicates that there will be 40 results:
 
 ```py
@@ -61,8 +61,8 @@ The control provided by an axis is fine-grained and targets one individual. To s
 WITH_AXES = {
     'persons': {'Ari': {}, 'Paul': {}, 'Leila': {}, 'Javier': {}},
     'households': {
-        'h1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
-        'h2': {'parents': ['Javier']}
+        'household_1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
+        'household_2': {'parents': ['Javier']}
         },
     'axes': [[{'count':10, 'index': 3, 'name':'salary', 'min':0, 'max':3000, 'period':'2018-11'}]]
     }
@@ -96,8 +96,8 @@ Sets of axes in the inner array are "parallel". They allow additional variables
 WITH_PARALLEL_AXES = {
     'persons': {'Ari': {}, 'Paul': {}, 'Leila': {}, 'Javier': {}},
     'households': {
-        'h1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
-        'h2': {'parents': ['Javier']}
+        'household_1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
+        'household_2': {'parents': ['Javier']}
         },
     'axes': [[
         {'count':10, 'name':'age', 'min':18, 'max':78, 'period':'2018-11'},
@@ -145,8 +145,8 @@ Sets of axes in the outer array are "perpendicular" resulting in independent var
 WITH_PERPENDICULAR_AXES = {
     'persons': {'Ari': {}, 'Paul': {}, 'Leila': {}, 'Javier': {}},
     'households': {
-        'h1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
-        'h2': {'parents': ['Javier']}
+        'household_1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
+        'household_2': {'parents': ['Javier']}
         },
     'axes': [
         [{'count':4, 'name':'age', 'min':18, 'max':78, 'period':'2018-11'}],

source/simulate/run-simulation.md

@@ -1,12 +1,12 @@
 # How to run a simulation
 
-To calculate legislation variables on people's situations, a _Simulation_ needs to be created and run. 
+To calculate legislation variables on people's situations, a _Simulation_ needs to be created and run.
 OpenFisca looks for two kinds of inputs:
 
 - how persons are dispatched in other entities,
 - what variables' values are already known.
 
-This is true for both [test cases](run-simulation.md#test-cases) and [data](run-simulation.md#data), the two approaches to running Simulations, 
+This is true for both [test cases](run-simulation.md#test-cases) and [data](run-simulation.md#data), the two approaches to running Simulations.
 
 ## How to run a simulation on a test case
 
@@ -23,22 +23,22 @@ Here is an example of test case (in Python):
 BASIC_TEST_CASE = {
     'persons': {'Ari': {}, 'Paul': {}, 'Leila': {}, 'Javier': {}},
     'households': {
-        'hh1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
-        'hh2': {'parents': ['Javier']}
+        'household_1': {'children': ['Leila'], 'parents': ['Ari', 'Paul']},
+        'household_2': {'parents': ['Javier']}
         },
     }
 ```
 
 This test case defines 4 persons, `Ari`, `Paul`, `Leila` and `Javier`.
-They belong to 2 households named `hh1` and `hh2`.
-For example, `Ari` and `Paul` are parents in `hh1` and have one child, `Leila`.
+They belong to 2 households named `household_1` and `household_2`.
+For example, `Ari` and `Paul` are parents in `household_1` and have one child, `Leila`.
 
 Information that can be added at the _individual_ level or at the _group entity_ level:
 
 - known variable values,
 - and definition periods for those variable values.
 
-To add a salary to `Ari` and `rent` to `hh1` would look like this:
+To add a salary to `Ari` and `rent` to `household_1` would look like this:
 
 ```py
 TEST_CASE = {
@@ -51,12 +51,12 @@ TEST_CASE = {
         'Javier': {}
     },
     'households': {
-        'hh1': {
+        'household_1': {
             'children': ['Leila'],
             'parents': ['Ari', 'Paul'],
             'rent': {'2011-01': 300}
         },
-        'hh2': {'parents': ['Javier']}
+        'household_2': {'parents': ['Javier']}
     },
 }
 ```
@@ -215,7 +215,7 @@ In the following example, the [pandas](https://pandas.pydata.org) library can be
     simulation.set_input('salary', period, numpy.array(data.person_salary))
     ```
 
-I is now possible to calculate the [income_tax](https://legislation.demo.openfisca.org/income_tax) variable for each person of the `data.csv` file for the same period:
+It is now possible to calculate the [income_tax](https://legislation.demo.openfisca.org/income_tax) variable for each person described in the `data.csv` file for the same period:
 
 ```py
 income_tax = simulation.calculate('income_tax', period)
@@ -249,7 +249,7 @@ The following example calculates the `income_tax` of the 8th person in the list:
 
 #### Application: calculate households total taxes from a CSV file
 
-This example will manage the `persons` and `households` entities. To calculate households' `total_taxes`, it requires each persons' `income_tax`. 
+This example will manage the `persons` and `households` entities. To calculate households' `total_taxes`, it requires each persons' `income_tax`.
 First link the persons list to the households and define their roles.
 
 Persons and households lists in this example are defined in distinct files:
@@ -350,7 +350,7 @@ where `household_id` is used as a pivot item linking these files contents.
     simulation.set_input('salary', period, data_persons.person_salary)
     ```
 
-Calculate the [total_taxes](https://legislation.demo.openfisca.org/total_taxes) variable for each household of the `data_households.csv` file and the same period:
+This now allows calculation of the [total_taxes](https://legislation.demo.openfisca.org/total_taxes) variable for each household of the `data_households.csv` file over the given period:
 
 ```py
 total_taxes = simulation.calculate('total_taxes', period)