Merge branch 'main' of https://github.com/datakind/affordable-housing…

…-tooling

workstream1/documentation/README.md

@@ -238,13 +238,14 @@ across all projects in the portfolio
 must be more than 45 percent of the sum of ```txtUnitCount```
 across all projects in the portfolio. 
 
-1. The sum of the total project cost 
+1. The sum of the *total project cost* 
 aggregated across all projects in the portfolio
 must be ten times the sum of the CMF awards across the portfolio. 
 For example, an award of one million dollars in CMF funding
 would be the maximum funding permissible
 for a portfolio for which the sum of the 
 total project cost adds to ten million dollars.
+*Note that the constraint on this multiplier is based on total project cost, which includes funds from state or local governments, even though the CMF tool calculates a multiplier that is the ratio of private funding to CMF funding, which is also a useful metric.*
 
 1. Sixty percent of rental affordable housing units 
 must be located in either Areas of Economic Distress or High-Opportunity Areas for Eligible-Income Families. 

workstream1/test_cases/README.md

@@ -86,37 +86,75 @@ in the various income categories.
 
 1. ```OHA``` is based on the project "OHA" 
 from the CMF tool. 
-  This project tests the lower bound for...
+  This project tests the lower bound for the multiplier of private funding, since it has zero private funding but some government funding
 
 1. ```PBF``` is based on the project "PBF" 
 from the CMF tool. 
+  It provides an exampe of a project with a minimal multiplier of 2.5 but a maximal number of units designated for low-income families, with 100 percent. 
+    This can be used to examine portfolio allocation rules
+    that sacrifice the multiplier for extra service toward the goals of the CMF program.
 
 1. ```CMC``` is based on the project "CMC" 
 from the CMF tool. 
+  This is an alternative to the ```CMC``` project above, with a low multiplier but a medium level of units available for low-income families. 
 
 1. ```WP``` is based on the project "WP" 
 from the CMF tool. 
+  This is another alternative to the ```CMC``` project above, but with a (slightly higher) low multiplier but 100 percent of units available for low-income families. 
 
 1. ```AG``` is based on the project "AG" 
 from the CMF tool. 
+  This project has both a high multiplier and a high ratio
+  of units available for low-income families. 
+  It can be used to evaluate portfolio allocation rules, 
+  since it will likely be awarded a grant.
 
 1. ```CP``` is based on the project "CP" 
 from the CMF tool. 
+This is an alternative to the ```AG``` project above, 
+with a high multiplier but only 10 percent of units available for low-income families, which is below the threshold for
+eligibility. It should be rejected for a CMF grant.
 
 1. ```JB``` is based on the project "JB" 
 from the CMF tool. 
+This is an intermediate case with a moderately low multiplier
+of 6 and a barely-passable 20.5 percent 
+of units available for low-income families
+  Whether this project is funded will depend on the precise parameters of the portfolio evaluation stategy. 
 
 1. ```AP``` is based on the project "AP" 
 from the CMF tool. 
+This case is similar to ```AP```
+with a marginal 22.9 percent 
+of units available for low-income families
+but a multiplier of 9, which is only slightly below
+the overall target of 10. 
+It tests a portfolio allocation strategy 
+for whether a reasonable multiplier for a project 
+will make up for a minimal contribution of housing 
+for low-income families.
 
 1. ```CL1``` is based on the project "CL1" 
 from the CMF tool. 
+This project has capital multipliers
+and low-income family percantages within bounds
+but tests for errors in the allocation of housing units
+across income categories. The total allocation of units 
+to income categories does not match the sum of the number of units: the total is *higher* than the number of units. 
 
 1. ```CL2``` is based on the project "CL2" 
 from the CMF tool. 
+This case is an analogue for the case ```CL1```, 
+except that the total allocation of units 
+to income categories does not match the sum of the number of units: the total is *lower* than the number of units. 
 
 1. ```PC``` is based on the project "PC" 
 from the CMF tool. 
+Similar to the case ```PBF```, except that ```PC```
+includes public funding sources while ```PBF```
+had zero funding from public sources. 
+Differences in the two cases should distinguish between 
+allocation rules that favor either private or public funding.