Add documentation through Readme.md files to the repository

README.md

@@ -7,3 +7,67 @@
 PolicyEngine US is a microsimulation model of the US state and federal tax and benefit system.
 
 To install, run `pip install policyengine-us`.
+
+## START
+
+### When starting to work on a specific policy program
+- First check the legal code of the program
+ - Model based on legal code structure
+- Second check newest tax form for inflation adjusted amount confirmation
+
+### Create new issues
+![pic1](./page2image24204576.png)
+- Go to the ‘Issues’ tab
+- Click on ‘New Issue’
+- Can assign to specific person/people
+- Remember to add tags for better classification
+
+### Working on issues assigned in VS Code
+
+- Create a new working branch for the specific issue you are working on: you can do so by clicking the right arrow → (you don’t want to be working on the master branch)
+
+![pic2](./MyIssues.png)
+
+- There are four specific files you will need to work on for an issue:
+ - Test (.yaml)
+ - Parameter (.yaml)
+ - Variable (.py)
+ - Changelog (.yaml)
+
+![pic3](./changel.png)
+
+(Note: Test and Variable files should have the same name)
+- Type make format in terminal
+- Commit the changes you’ve made (under the Source Control menu)
+ - Enter Message before commiting
+
+![pic4](./page3image24275520.png)
+
+- Type git pull upstream master in the terminal to make sure you are using the latest version of the repository; you will need to do this before every sync or pull request (but never do this before you commit)
+- Create pull request
+ - Title: [Specific changes you’ve made for this pull request, e.g. ‘Add Virginia Personal Exemption’]
+ - Description: be sure to include ‘Fixes #[issue number]’ to link the pull request to the specific issue you are tackling
+ - Make sure you select the checkbox to create a draft pull request for
+review/merge
+
+### Troubleshooting
+- After you submit your pull request, you can go to the github.com to see if it has passed all the tests
+ - Lint error: usually can be resolved by typing ‘make format’ in the terminal 
+- Other common issues:
+ -  If making a parameter broken down by filing status, make sure you include all five parameters in your parameter file:
+    - SINGLE
+    - SEPARATE
+    - WIDOW
+    - HEAD_OF_HOUSEHOLD 
+    - JOINT
+
+(Sometimes, the tax instruction does not specify all five filing statuses. In that case, you can let the ‘WIDOW’ and the ‘HEAD_OF_HOUSEHOLD’ cases be the same as the ‘SINGLE’ case.)
+ - When you are trying to define a condition, use the where statement instead of an if statement. Similarly, use max_ and min_ instead of max and min. These are needed for vectorization.
+- Some useful commands:
+ - condainit
+ - gitconfig–globalpull.rebasefalse
+  - If you have a merge issue and it asks which you want to do 
+  - gitpull
+- gitcommit-am'resolve'
+- gitreset–hardHEAD
+- rm-ft

policyengine_us/parameters/README.md

@@ -0,0 +1,72 @@
+## PARAMETERS
+
+### Types of parameters
+- Single value example
+  - [USD Example](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/dc/tax/income/credits/eitc/without_children/phase_out/start.yaml)
+  - [% Example](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/dc/tax/income/credits/eitc/with_children/match.yaml) 
+  - [Age Example](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/ma/tax/income/exemptions/aged/age.yaml)
+
+
+- [List parameter Example](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/sc/tax/income/subtractions/subtractions.yaml)
+- [Marginal rate Example](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/ny/tax/income/main/joint.yaml)
+- [Single amount Example](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/or/tax/income/subtractions/federal_tax_liability/cap/joint.yaml)
+- Breakdown parameter
+  - Breakdown by Enum variable
+  - [Filing status variable example:](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/household/demographic/tax_unit/filing_status.py) 
+  - [Filing status parameter example:](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/ia/tax/income/alternative_minimum_tax/threshold.yaml)
+
+- Scale Parameter interactions: Documentation
+  - scale = parameters(period).some.tax.scale
+  - scale.thresholds: list[float]
+  - scale.amounts: list[float]
+  - scale.rates: list[float]
+  - scale.thresholds[-1]: float - final element
+  - scale.thresholds[0]: float - first element
+- Do not use “name:” metadata
+   name: mo_federal_income_tax_deduction_rates
+- Generally avoid using single amount parameters when scale parameters can created to summarize the value structure 
+
+### Example of a standard parameter
+
+- Essential components: 
+    - description 
+    - metadata (unit, label, period, reference-title/href)
+    - values
+
+- Multiple references example:
+    - https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/parameters/gov/states/or/tax/income/subtractions/federal_tax_liability/cap/joint.yaml 
+    - Cite both legal code and tax form if possible
+
+- Description
+    - Name of State + name of Program
+    - Full sentence including period and active language
+    - No numeric values
+    - Examples:
+        - Arizona taxes the personal income for head of household filers at this rate.
+        - Rhode Island provides filers a standard deduction of this amount, depending on filing status.
+        - New Jersey TANF counts these income sources as unearned income.
+        - California limits the young child tax credit to filers with children below this age.
+- Label
+    - Key Words, no numeric values
+    - Not full sentence
+    - Name of State + Name of Program
+        - Utah income tax rate
+        - Iowa nonrefundable tax credits
+- Reference 
+    - Title: Refer to the specific part of legislative source, as specific as possible
+        - Code of the District of Columbia § 47–1806.04 (f)(1)(C)(ii)
+        - 2021 DC Form D-40 Booklet, Page 24, Line 5
+    - href: the link to the reference. 
+        - when applicable, add “# page=page number” to the end of the link to skip to the designated page.
+        - Example: https://otr.cfo.dc.gov/sites/default/files/dc/sites/otr/publication/attachments/52926_D-40_12.21.21_Final_Rev011122.pdf#page=24
+
+- Important: economy and household metadata
+    - Certain yaml file names are reserved for functions and can not be used 
+        - children.yaml
+        - if.yaml 
+        - parents.yaml
+        - else.yaml
+    - Set these to false while your program is in development
+        - This hides parameters and folders when both are flagged, or if just one is flagged, ensures that users see a notice about the limitations of the parameter:
+    - Set them to true when you complete the development and hook it up to the net income tree
+    - You can do this at the folder level - [see this example PR](https://github.com/PolicyEngine/policyengine-us/pull/2583)

policyengine_us/variables/README.md

@@ -0,0 +1,24 @@
+## Variables
+
+- Update the following files to add the state model into income tree:
+    - [policyengine_us/variables/gov/states/tax/income/state_income_tax.py](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/gov/states/tax/income/state_income_tax.py) 
+    - [policyengine_us/variables/household/income/household/household_tax_before_refundable_credits.py](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/household/income/household/household_tax_before_refundable_credits.py)
+    - [policyengine_us/variables/household/income/household/household_refundable_tax_credits.py](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/household/income/household/household_refundable_tax_credits.py)
+    - [policyengine_us/variables/gov/states/tax/income/state_income_tax_before_refundable_credits.py](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/gov/states/tax/income/state_income_tax_before_refundable_credits.py)
+    - [policyengine-us/blob/master/policyengine_us/variables/household/income/household/household_state_income_tax.py ](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/household/income/household/household_state_income_tax.py)
+    - [policyengine-us/modelled_policies.yaml](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/modelled_policies.yaml)
+- After Martin Holmer verifies that it passes taxsim tests:
+    - Delete parameters/gov/states/state/index.yaml
+- Useful variable classes:
+    - [Adjusted gross income](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/gov/irs/income/taxable_income/adjusted_gross_income/adjusted_gross_income.py)
+    - [Exemptions](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/gov/irs/income/taxable_income/exemptions.py)
+    - [Dependents in tax unit](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/household/demographic/tax_unit/tax_unit_dependents.py)
+    - [Is a dependent (person level)](https://github.com/PolicyEngine/policyengine-us/blob/master/policyengine_us/variables/household/demographic/tax_unit/is_tax_unit_dependent.py)
+
+- Add readme.md files to state program variable folders per [this PR](https://github.com/PolicyEngine/policyengine-us/pull/2740)
+    - Eliminate abbreviations on the front end
+
+- Dividing by 0 Problem
+    - [PR example](https://github.com/PolicyEngine/policyengine-us/pull/2561/files) to overcome /0 
+    - Mask example:
+        - Use when a division can lead to a “dividing by 0” issue