Fix area targets file specification and add targets file documentation

tmd/areas/create_area_weights.py

@@ -216,12 +216,14 @@ def prepared_data(area: str, vardf: pd.DataFrame):
             initial_weights_scale = row.target / national_population
         # construct variable array for this target
         assert (
-            row.count >= 0 and row.count <= 1
-        ), f"count value {row.count} not in [0,1] range on {line}"
-        if row.count == 0:
+            row.count >= 0 and row.count <= 2
+        ), f"count value {row.count} not in [0,2] range on {line}"
+        if row.count == 0:  # tabulate $ variable amount
             unmasked_varray = vardf[row.varname].astype(float)
-        else:
+        elif row.count == 1:  # count units with any variable amount
             unmasked_varray = np.ones(numobs, dtype=float)
+        else:  # count only units with non-zero variable amount
+            unmasked_varray = (vardf[row.varname] != 0.0).astype(float)
         mask = np.ones(numobs, dtype=int)
         assert (
             row.scope >= 0 and row.scope <= 2

tmd/areas/targets/README.md

@@ -1,3 +1,40 @@
 # areas / targets
 
 Contains sub-national area targets files.
+
+
+# Targets File Content
+
+An areas targets file is a CSV-formatted file with its first row
+containing column names and its second row containing the area
+population target.  Each subsequent row contains another target.
+Rows after the first two that start with a `#` character are
+considered comments and are skipped.
+
+Here are the column names and their valid values:
+
+- **`varname`**: any Tax-Calculator variable name.
+
+- **`count`**: integer in [0,2] range: count==0 implies dollar total
+               of varname is tabulated, count==1 implies number of
+               tax units with any value of varname is tabulated,
+               count==2 implies number of tax units with non-zero
+               values of varname is tabulated.
+
+- **`scope`**: integer in [0,2] range: scope==0 implies all tax units,
+               scope==1 implies PUF-derived filing units, and
+               scope==2 implies CPS-derived filing units.
+
+- **`agilo`**: float representing lower bound of the AGI range (which
+               is included in the range) that is tabulated.
+
+- **`agihi`**: float representing upper bound of the AGI range (which
+               is excluded from the range) that is tabulated.
+
+- **`fstatus`**: integer in [0,5] range: fstatus=0 implies all tax
+                 units are tabulated, other fstatus values imply just
+                 the tax units with the Tax-Calculator `MARS` variable
+                 equal to fstatus are included in the tabulation.
+
+- **`target`**: target amount (dollars if count==0 or number of
+                tax units if count==1 or count==2).